Юпитекст

Вы всегда хотели, чтобы блокноты Jupyter представляли собой обычные текстовые документы? Хотели бы вы редактировать их в своей любимой IDE? И получить четкие и содержательные различия при управлении версиями? Тогда Jupytext вполне может быть тем инструментом, который вы ищете!

Текстовые блокноты

Блокнот Python, закодированный в формате py:percent имеет расширение .py и выглядит следующим образом:

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

# %%
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.

Установка

Установите Jupytext в среду Python, которую вы используете для Jupyter. Используйте либо

 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 , если он существует. Версия .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

Примеры использования

Ноутбуки под контролем версий

Это краткое руководство:

Откройте свой блокнот .ipynb в Jupyter и соедините его с блокнотом .py , используя либо команду пары в Jupyter Lab, либо файл глобальной конфигурации.
Сохраните блокнот — будет создан блокнот .py
Добавьте этот блокнот .py в систему контроля версий.

Вы можете исключить файлы .ipynb из контроля версий (если только вы не хотите видеть версионированные выходные данные!). Jupytext воссоздаст файлы .ipynb локально, когда пользователи откроют и сохранят блокноты .py .

Совместная работа над блокнотами с помощью Git

Совместная работа над блокнотами Jupyter через Git становится такой же простой, как и над текстовыми файлами.

Предположим, что ваши записные книжки .py находятся под контролем версий (см. выше). Затем,

Ваш соавтор извлекает блокнот .py
Они открывают его как блокнот в Jupyter (щелкните правой кнопкой мыши в Jupyter Lab).
На этом этапе у ноутбука нет выходов. Они запускают блокнот и сохраняют его. Выходные данные регенерируются и создается локальный файл .ipynb
Они редактируют блокнот и отправляют обновленный файл notebook.py . Разница — это не что иное, как стандартная разница в скрипте Python.
Вы извлекаете обновленный сценарий notebook.py и обновляете браузер. Входные ячейки обновляются на основе нового содержимого notebook.py . Выходные данные перезагружаются из вашего локального файла .ipynb . Наконец, переменные ядра остаются нетронутыми, поэтому у вас есть возможность запускать только измененные ячейки, чтобы получить новые выходные данные.

Редактирование или рефакторинг записной книжки в IDE

После того как ваша записная книжка будет связана с файлом .py , вы сможете легко редактировать или реорганизовать представление записной книжки в .py в IDE.

Как только вы закончите редактирование блокнота .py , вам просто нужно будет перезагрузить блокнот в Jupyter, чтобы получить туда последние изменения.

Примечание. Закрыть блокнот .ipynb в Jupyter проще при редактировании парного файла .py . Нет никаких обязательств делать это; однако, если вы этого не сделаете, вы должны быть готовы внимательно прочитать всплывающие сообщения. Если Jupyter попытается сохранить записную книжку, в то время как парный файл .py также редактировался на диске с момента последней перезагрузки, будет обнаружен конфликт, и вам будет предложено решить, какая версия записной книжки (в памяти или на диске) является подходящий.