ジュピーテキスト

Jupyter ノートブックがプレーンテキストドキュメントだったらいいのにといつも思っていませんか?お気に入りの IDE で編集できたらいいのにと思いませんか?バージョン管理を行うときに、明確で意味のある差分を取得しますか?そうすれば、Jupytext があなたが探しているツールになるかもしれません。

テキストノート

py:percent形式でエンコードされた Python ノートブックには.py拡張子があり、次のようになります。

 # %% [markdown]
# This is a markdown cell

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

ノートブックの入力 (およびオプションでメタデータ) のみが含まれます。テキストノートブックはバージョン管理に適しています。 IDE で編集またはリファクタリングすることもできます。上記の.pyノートブックは通常の Python ファイルです。

コードがほとんど含まれるノートブックにはpercent形式をお勧めします。 percent形式は、Julia、Python、R、およびその他の多くの言語で使用できます。

ノートブックがドキュメント指向である場合は、Markdown ベースの形式 (拡張子.mdが付いたテキストノートブック) の方が適切な場合があります。ノートブックで何をするかによっては、Jupyter Book、Quarto Markdown、さらには Pandoc Markdown と非常にうまく相互運用できる Myst Markdown 形式を好む場合があります。

インストール

Jupyter に使用する Python 環境に Jupytext をインストールします。どちらかを使用してください

 pip install jupytext

または

 conda install jupytext -c conda-forge

次に、Jupyter Lab サーバーを再起動し、Jupyter で Jupytext がアクティブになっていることを確認します。.py .md .pyにはノートブックアイコンがあり、Jupyter Lab で右クリックするとノートブックとして開くことができます。

ペアになったノートブック

拡張子が.pyまたは.mdのテキストノートブックは、バージョン管理に適しています。これらは IDE で簡単に編集または作成できます。右クリックして、Jupyter Lab でノートブックとして開いて実行できます。ただし、テキストノートブックにはノートブックの入力のみが保存されるため、ノートブックを閉じるとノートブックの出力は失われます。

テキストノートの代わりに便利なのがペアノートです。これらは 2 つのファイル ( .ipynbと.pyのセットで、同じノートブックが含まれていますが、形式は異なります。

ペアになったノートブックの.pyバージョンを編集し、 [ディスクからノートブックを再ロード]を選択して編集内容を Jupyter に戻すことができます。出力は.ipynbファイルが存在する場合、そこから再ロードされます。 .ipynbバージョンは、次回 Jupyter でノートブックを保存するときに更新または再作成されます。

Jupyter Lab でノートブックをペアリングするには、コマンドパレットからPair Notebook with percent Scriptを使用します。

特定のディレクトリ内のすべてのノートブックをペアにするには、次の内容を含む構成ファイルを作成します。

 # jupytext.toml at the root of your notebook directory
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ノートブックを開き、Jupyter Lab のペアコマンドまたはグローバル構成ファイルを使用して、それを.pyノートブックとペアリングします。
ノートブックを保存します - これにより.pyノートブックが作成されます
この.pyノートブックをバージョン管理に追加します

.ipynbファイルをバージョン管理から除外することもできます (出力のバージョン管理を希望する場合を除く)。 Jupytext は、ユーザーが.pyノートブックを開いて保存すると、ローカルで.ipynbファイルを再作成します。

Git を使用したノートブックでのコラボレーション

Git を介した Jupyter ノートブックでのコラボレーションは、テキストファイルでのコラボレーションと同じくらい簡単になります。

.pyノートブックがバージョン管理下にあると仮定します (上記を参照)。それから、

共同作業者が.pyノートブックをプルします
Jupyter でノートブックとして開きます (Jupyter Lab で右クリック)。
この段階では、ノートブックには出力がありません。彼らはノートブックを実行して保存します。出力が再生成され、ローカルの.ipynbファイルが作成されます
ノートブックを編集し、更新されたnotebook.pyファイルをプッシュします。 diff は、Python スクリプトの標準的な diff に他なりません。
更新されたnotebook.pyスクリプトをプルし、ブラウザを更新します。入力セルは、 notebook.pyの新しい内容に基づいて更新されます。出力はローカルの.ipynbファイルから再ロードされます。最後に、カーネル変数は変更されないため、変更されたセルのみを実行して新しい出力を取得するオプションがあります。

IDE でのノートブックの編集またはリファクタリング

ノートブックを.pyファイルと組み合わせると、IDE でノートブックの.py表現を簡単に編集またはリファクタリングできます。

.pyノートブックの編集が完了したら、Jupyter でノートブックを再ロードして最新の編集内容を取得するだけです。

注: ペアになった.pyファイルを編集する場合は、Jupyter で.ipynbノートブックを閉じる方が簡単です。そうする義務はありません。ただし、そうでない場合は、ポップアップメッセージを注意深く読む準備ができている必要があります。前回のリロード以降、ペアになった.pyファイルもディスク上で編集されているときに、Jupyter がノートブックを保存しようとすると、競合が検出され、ノートブックのバージョン (メモリ内またはディスク上) がどちらであるかを決定するよう求められます。適切なもの。