Zenn
Open12

Jupytextしたい

Jupyter Notebook
Python
JupyterLab
jupytext
myst
shotakahashotakaha

Jupytext

https://jupytext.readthedocs.io/en/latest/

  • Jupyter Notebook（.ipynb）をMarkdown（.md）やPythonスクリプト（.py）に変換できるツール
  • 変換した .ipynb、.md、.pyファイルをペアリングして同期できる
  • .ipynbのGit管理から解放される
shotakahashotakaha

インストール

  • pipxでインストール
pipx
$ pipx install jupytext
  • poetryでインストール（--group=devにした）
poetry
$ poetry add jupytext --group=dev
  • uvでインストール
uv
$ uv tool install jupytext
shotakahashotakaha

基本コマンド

pair & sync
// ノートブック（.ipynb）を他の形式（md:mystとpy:light）をペアリング
$ jupytext --set-formats ipynb,md:myst,py:light ノートブック.ipynb
[jupytext] Reading ファイル.ipynb in format ipynb
[jupytext] Updating notebook metadata with '{"jupytext": {"formats": "ipynb,md:myst"}}'
[jupytext] Updating ファイル.ipynb
[jupytext] Updating ファイル.md
[jupytext] Updating ファイル.py

// ノートブックを編集したあと、他のファイルと同期
$ jupyter --sync ノートブック.ipynb
[jupytext] Reading ファイル.ipynb in format ipynb
[jupytext] Loading ファイル.md
[jupytext] Unchanged ファイル.ipynb
[jupytext] Updating ファイル.md
[jupytext] Updating ファイル.py
  • いろいろなオプションがあるが、メインは上の2つ（たぶん）
  • --set-formats SET_FORMATS: ペアリング
  • --sync: 同期
shotakahashotakaha

ディレクトリを指定

ディレクトリ構造
$ tree
PROJECT_ROOT/
  |-- notebooks/    # .ipynbを保存
  |-- markdowns/    # .mdを保存
  |-- scripts/    # .mdを保存
  • ペアリングしたファイルは、デフォルトで同じ階層に作成される
  • ノートブックが大量にある場合、上のように、ファイルの種類ごとにディレクトリを分けて管理したほうがよいと思う
  • --set-formatsオプションで、ディレクトリを分けることができる
PROJECT_ROOT
// notebooks/*.ipnyb のノートブックをまとめて変換＆ペアリング
$ jupytext --set-formats notebooks//ipynb,markdowns//md:myst,scripts//py:light notebooks/*.ipynb
  • ディレクトリの指定は ディレクトリ//フォーマットのように記述する
PROJECT_ROOT
// まとめて同期できる
$ jupytext --sync notebooks/*.ipynb
  • --syncもまとめて同期できる
shotakahashotakaha

全体設定（jupytext.toml）

jupytext.toml
[formats]
"notebooks/" = "ipynb"
"markdowns/" = "md:myst"
"scripts/" = "py:light"
  • プロジェクトルートにjupytext.tomlを配置して、全体設定できる
  • ディレクトリ別に管理する場合は、このファイルに書いてから実行したほうがよい
  • なお、単体ファイルの設定は、全体設定より優先される
PROJECT_ROOT
$ jupyter --sync notebooks/*.ipynb
$ jupyter --sync markdowns/*.md
$ jupyter --sync scripts/*.py
  • jupytext.tomlの[formats]の設定があれば、jupyter --syncするだけでOK
  • どのディレクトリに対して実行してもOK
  • （ただし、ノートブックを基準に変換するユースケースが多いと思う）
shotakahashotakaha

追加の設定

jupytext.toml
notebook_metadata_filter = ""
cell_metadata_filter = ""

[formats]
"notebooks/" = "ipynb"
"markdowns/" = "md:myst"
"scripts/" = "py:light"
shotakahashotakaha

VS Codeでの作業

  • Jupytext for NotebooksというVS Code拡張があるが、使い方がまだわかっていない
  • なので、原始的な作業フローにしている
  1. 空のipynbファイルを作成する
$ touch notebooks/NEW_NOTEBOOK.ipynb
  1. VS Codeで編集する
$ code notebooks/NEW_NOTEBOOK.ipynb
  1. jupytextで変換する
$ jupytext --sync notebooks/*.ipynb
  1. 追加の編集はmdファイルにする
$ code markdowns/NEW_NOTEBOOK.md
  1. jupytextで同期する
$ jupytext --sync notebooks/*.ipynb
[jupytext] Loading notebooks/NEW_NOTEBOOK.ipynb
[jupytext] Loading markdowns/NEW_NOTEBOOK.md
[jupytext] Updating notebooks/NEW_NOTEBOOK.ipynb
[jupytext] Updating scripts/NEW_NOTEBOOK.py
[jupytext] Unchanged markdowns/NEW_NOTEBOOK.md
  1. Git管理する
// 関係するファイルをまとめてステージ
$ git add notebooks/NEW_NOTEBOOK.ipynb
$ git add scripts/NEW_NOTEBOOK.py
$ git add markdowns/NEW_NOTEBOOK.md

// ひとつのコミット
$ git commit
shotakahashotakaha

フォーマットの種類

  1. Markdown用
  2. スクリプト用
  3. ノートブック用
shotakahashotakaha

Markdown用

  1. md: 標準的なMarkdown
  2. md:myst: MyST Markdown（Sphinx拡張）
  3. md:pandoc: Pandoc Markdown（Pandoc拡張）
  4. Rmd: R Markdown
shotakahashotakaha

スクリプト用

  1. py: 標準的なPython
  2. py:percent: セルマーカー（# %%）あり（Jupyter Notebookと互換性がある形式。他のIDEでもセルを認識できる）
  3. py:light: セルマーカーなし（Jupytext専用の形式。コードがすっきりする）
  4. R / R:percent / R:light: R（# %%）
  5. jl / jl:percent / jl:light: Julia（# %%）
  6. cpp / cpp:percent / cpp:light: C++（// %%）
  7. js / js:percent / js:light: JavaScript（// %%）
  8. ts / ts:percent / ts:light: TypeScript（// %%）
shotakahashotakaha

フォーマットの選び方

  • Sphinxを使うならばmd:mystがよさそう
  • 他のIDEは使わないならばpy:lightでよさそう
  • 広く共同編集するならpy:percentにする
shotakahashotakaha

pre-commitフック

repos:
  - repo: https://github.com/mwouts/jupytext
    rev: v1.14.7
    hooks:
    -  id: jupytext
        args: [--sync]
  • https://jupytext.readthedocs.io/en/latest/using-pre-commit.html
  • pre-commitフックを設定して、コミットを作成時にjupytext --syncできる
    • 通常はファイルが変更されたときにjupytext --syncが走る
    • フックも設定しておくことで、同期忘れを防ぐことができる（かもしれない）
$ pre-commit autoupdate
$ pre-commit run jupytext
  • pre-commit autoupdateでrevを最新版に更新できる
  • pre-commit run jupytextで手動でフックを実行できる