jupyter-to-marimo

将 Jupyter Notebook 转换为 Marimo

先转换

重要： 阅读源 Notebook 之前，先运行转换器：

uvx marimo convert <notebook.ipynb> -o <notebook.py>

只有在转换失败或生成的文件遗漏必要信息时，才阅读 .ipynb 文件。将生成的文件视为初稿。

转换完成以及完成大量编辑后，运行此命令：

uvx marimo check <notebook.py>

检查转换结果

• 验证 PEP 723 元数据中的所有必需软件包。转换器可能会遗漏某些软件包安装形式。
• 删除残留的安装单元格和过时的安装说明。仅在必要时添加版本约束。
• Notebook 使用 PEP 723 元数据时，使用 --sandbox。
• 保留源 Notebook 的用途和预期工作流。
• 为展示效果安排单元格。marimo 根据变量的定义和引用来确定执行顺序。
• 单元格可以出现在定义其输入的单元格之前。
• 如果当前的单元格边界影响清晰度，请合并或拆分单元格。
• 删除多余的 Jupyter 产物，例如不必要的 display() 调用。
• 检查转换后的魔法命令。保留有效的转换结果，并处理指出不支持的魔法命令的注释。
• 将要渲染的值放在每个单元格的最后一个表达式中。
• 添加的 UI 和辅助函数应与 Notebook 的用途相称。
• 替换那些会等待终端输入或无法在目标界面中使用的交互式输入方式。使用合适的 UI 控件、脚本参数或环境值。
• 不要打印、记录或保存机密信息。对于多个环境值，可考虑使用 EnvConfig。
• 找出耗时操作和外部副作用。如果操作必须等待，请使用 mo.stop() 和合适的 UI 元素来控制。
• 如果用户必须一次提交多个值，请使用表单。
• 在控制节点之后定义下游值，以便依赖图延迟执行依赖单元格。
• 使用简单的原生组件展示有用结果。只有预期工作流需要时，才添加实时刷新。
• 对于 ipywidgets，请阅读 references/widgets.md。
• 对于 LaTeX 和 MathJax，请阅读 references/latex.md。

验证结果

• 所有编辑完成后，再次运行 marimo check。
• 以每种预期模式运行 Notebook，确认其行为符合预期。
• 条件允许时，将源 Notebook 和转换后的 Notebook 并排打开，请用户检查。
• 比较内容、控件、输出和工作流。单元格顺序和布局可以不同。
• 检查已更改的文件，确保其中没有机密信息、生成的数据、缓存、日志和其他运行时文件。