Jupytext

你是否一直希望Jupyter笔记本是纯文本文档？希望可以在你喜欢的IDE中编辑它们？在进行版本控制时获得清晰且有意义的差异？那么，Jupytext很可能就是你一直在寻找的工具！

文本笔记本

用py:percent格式编码的Python笔记本有一个.py扩展名，看起来像这样：

# %% [markdown]
# 这是一个markdown单元格

# %%
def f(x):
  return 3*x+1

只包含笔记本输入（可选地包含元数据）。文本笔记本非常适合版本控制。你还可以在IDE中编辑或重构它们 - 上面的.py笔记本是一个常规的Python文件。

我们推荐使用percent格式来处理主要包含代码的笔记本。percent格式适用于Julia、Python、R和许多其他语言。如果你的笔记本以文档为导向，那么基于Markdown的格式（扩展名为.md的文本笔记本）可能更合适。根据你计划如何使用你的笔记本，你可能更喜欢Myst Markdown格式（与Jupyter Book很好地兼容），或Quarto Markdown，甚至Pandoc Markdown。

安装

在你用于Jupyter的Python环境中安装Jupytext。可以使用以下命令：

pip install jupytext

或者

conda install jupytext -c conda-forge

然后，重启你的Jupyter Lab服务器，并确保Jupytext在Jupyter中已激活：.py和.md文件有一个笔记本图标，你可以在Jupyter Lab中右键单击将它们作为笔记本打开。

配对笔记本

扩展名为.py或.md的文本笔记本非常适合版本控制。它们可以在IDE中方便地编辑或创作。你可以在Jupyter Lab中右键单击将它们作为笔记本打开和运行。但是，当笔记本关闭时，笔记本的输出会丢失，因为文本笔记本只保存笔记本的输入。

配对笔记本是一个方便的替代方案。它们是一组两个文件，比如.ipynb和.py，它们包含相同的笔记本，但格式不同。

你可以编辑配对笔记本的.py版本，然后在Jupyter中选择"从磁盘重新加载笔记本"来获取编辑内容。如果.ipynb文件存在，输出将从中重新加载。下次你在Jupyter中保存笔记本时，.ipynb版本将被更新或重新创建。

要在Jupyter Lab中配对笔记本，请从命令面板使用"将笔记本与百分比脚本配对"命令：

要配对某个目录中的所有笔记本，请创建一个包含以下内容的配置文件：

# jupytext.toml 位于笔记本目录的根目录
formats = "ipynb,py:percent"

命令行

Jupytext也可以在命令行中使用。你可以：

使用 jupytext --set-formats ipynb,py:percent notebook.ipynb 配对笔记本
使用 jupytext --sync notebook.py 同步配对文件（输入从最新的配对文件加载）
使用 jupytext --to ipynb notebook.py 将一种格式的笔记本转换为另一种（如果你想要特定的输出文件，请使用 -o）
使用 jupytext --pipe black notebook.ipynb 将笔记本通过管道传输给代码格式化工具

示例用例

版本控制下的笔记本

以下是快速操作指南：

在Jupyter中打开你的.ipynb笔记本，并将其与.py笔记本配对，可以使用Jupyter Lab中的配对命令或全局配置文件
保存笔记本 - 这将创建一个.py笔记本
将这个.py笔记本添加到版本控制中

你可以将.ipynb文件排除在版本控制之外（除非你想看到版本控制的输出！）。当用户打开和保存.py笔记本时，Jupytext会在本地重新创建.ipynb文件。

通过Git协作处理笔记本

通过Git协作处理Jupyter笔记本变得像协作处理文本文件一样简单。

假设你的.py笔记本已经在版本控制下（见上文）。那么，

你的协作者拉取.py笔记本
他们在Jupyter中将其作为笔记本打开（在Jupyter Lab中右键单击）
此时笔记本没有输出。他们运行笔记本并保存。输出被重新生成，并创建一个本地.ipynb文件
他们编辑笔记本，并推送更新后的notebook.py文件。差异只是Python脚本的标准差异
你拉取更新后的notebook.py脚本，并刷新浏览器。输入单元格根据notebook.py的新内容更新。输出从你的本地.ipynb文件重新加载。最后，内核变量保持不变，所以你可以选择只运行修改过的单元格来获取新的输出

在IDE中编辑或重构笔记本

一旦你的笔记本与 .py 文件配对，你就可以在 IDE 中轻松编辑或重构笔记本的 .py 表示形式。

编辑完 .py 笔记本后，你只需在 Jupyter 中重新加载笔记本即可获取最新的编辑内容。

注意：当你编辑配对的 .py 文件时，最好先在 Jupyter 中关闭 .ipynb 笔记本。这并非必须，但如果不这样做，你应该准备仔细阅读弹出的消息。如果 Jupyter 尝试保存笔记本，而配对的 .py 文件自上次重新加载后也在磁盘上被编辑过，系统会检测到冲突，并要求你决定哪个版本的笔记本（内存中的还是磁盘上的）是合适的。

jupytext