Jupytext

Haben Sie sich schon immer gewünscht, dass Jupyter-Notizbücher reine Textdokumente wären? Wünschten Sie, Sie könnten sie in Ihrer Lieblings-IDE bearbeiten? Und bei der Versionskontrolle klare und aussagekräftige Unterschiede erhalten? Dann ist Jupytext möglicherweise das Tool, nach dem Sie suchen!

Textnotizbücher

Ein im Format py:percent codiertes Python-Notizbuch hat die Erweiterung .py und sieht folgendermaßen aus:

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

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

Es sind nur die Notebook-Eingaben (und optional die Metadaten) enthalten. Textnotizbücher eignen sich gut zur Versionskontrolle. Sie können sie auch in einer IDE bearbeiten oder umgestalten – das .py -Notizbuch oben ist eine normale Python-Datei.

Wir empfehlen das percent für Notizbücher, die hauptsächlich Code enthalten. Das percent ist für Julia, Python, R und viele andere Sprachen verfügbar.

Wenn Ihr Notizbuch dokumentationsorientiert ist, ist möglicherweise ein Markdown-basiertes Format (Textnotizbücher mit der Erweiterung .md ) besser geeignet. Je nachdem, was Sie mit Ihrem Notebook vorhaben, bevorzugen Sie möglicherweise das Myst-Markdown-Format, das sehr gut mit Jupyter Book zusammenarbeitet, oder Quarto-Markdown oder sogar Pandoc-Markdown.

Installation

Installieren Sie Jupytext in der Python-Umgebung, die Sie für Jupyter verwenden. Benutzen Sie beides

 pip install jupytext

oder

 conda install jupytext -c conda-forge

Starten Sie dann Ihren Jupyter Lab-Server neu und stellen Sie sicher, dass Jupytext in Jupyter aktiviert ist: .py und .md -Dateien haben ein Notebook-Symbol und Sie können sie mit einem Rechtsklick in Jupyter Lab als Notebooks öffnen.

Gepaarte Notizbücher

Textnotizbücher mit der Erweiterung .py oder .md eignen sich gut für die Versionskontrolle. Sie können bequem in einer IDE bearbeitet oder verfasst werden. Sie können sie mit einem Rechtsklick als Notebooks in Jupyter Lab öffnen und ausführen. Beim Schließen des Notebooks gehen jedoch die Notebook-Ausgaben verloren, da in Text-Notebooks nur die Notebook-Eingaben gespeichert werden.

Eine praktische Alternative zu Textnotizbüchern sind Paarnotizbücher. Hierbei handelt es sich um einen Satz aus zwei Dateien, beispielsweise .ipynb und .py , die dasselbe Notizbuch enthalten, jedoch in unterschiedlichen Formaten.

Sie können die .py Version des gekoppelten Notebooks bearbeiten und die Änderungen in Jupyter wiederherstellen, indem Sie „Notebook von Datenträger neu laden“ auswählen. Die Ausgaben werden aus der .ipynb Datei neu geladen, sofern diese vorhanden ist. Die .ipynb Version wird aktualisiert oder neu erstellt, wenn Sie das Notebook das nächste Mal in Jupyter speichern.

Um ein Notebook in Jupyter Lab zu koppeln, verwenden Sie den Befehl Pair Notebook with percent Script aus der Befehlspalette:

Um alle Notebooks in einem bestimmten Verzeichnis zu koppeln, erstellen Sie eine Konfigurationsdatei mit folgendem Inhalt:

 # jupytext.toml at the root of your notebook directory
formats = "ipynb,py:percent"

Befehlszeile

Jupytext ist auch über die Befehlszeile verfügbar. Du kannst

Koppeln Sie ein Notebook mit jupytext --set-formats ipynb,py:percent notebook.ipynb
Synchronisieren Sie die gepaarten Dateien mit jupytext --sync notebook.py (die Eingaben werden aus der zuletzt gepaarten Datei geladen)
Konvertieren Sie ein Notizbuch in einem Format in ein anderes mit jupytext --to ipynb notebook.py (verwenden Sie -o , wenn Sie eine bestimmte Ausgabedatei wünschen)
Leiten Sie ein Notebook an einen Linter weiter, beispielsweise mit jupytext --pipe black notebook.ipynb

Beispielanwendungsfälle

Notizbücher unter Versionskontrolle

Dies ist eine kurze Anleitung:

Öffnen Sie Ihr .ipynb Notebook in Jupyter und koppeln Sie es mit einem .py -Notebook, indem Sie entweder den Pair -Befehl in Jupyter Lab oder eine globale Konfigurationsdatei verwenden
Speichern Sie das Notizbuch – dadurch wird ein .py Notizbuch erstellt
Fügen Sie dieses .py Notizbuch zur Versionskontrolle hinzu

Sie können .ipynb Dateien von der Versionskontrolle ausschließen (es sei denn, Sie möchten die Ausgaben versioniert sehen!). Jupytext erstellt die .ipynb Dateien lokal neu, wenn die Benutzer die .py -Notizbücher öffnen und speichern.

Zusammenarbeit an Notebooks mit Git

Die Zusammenarbeit an Jupyter-Notebooks über Git wird so einfach wie die Zusammenarbeit an Textdateien.

Gehen Sie davon aus, dass Ihre .py Notebooks unter Versionskontrolle stehen (siehe oben). Dann,

Ihr Mitarbeiter ruft das .py Notizbuch ab
Sie öffnen es als Notizbuch in Jupyter (Rechtsklick in Jupyter Lab).
Zu diesem Zeitpunkt verfügt das Notebook über keine Ausgänge. Sie führen das Notebook aus und speichern es. Die Ausgaben werden neu generiert und eine lokale .ipynb Datei wird erstellt
Sie bearbeiten das Notizbuch und übertragen die aktualisierte Datei notebook.py . Der Diff ist nichts anderes als ein Standard-Diff in einem Python-Skript.
Sie rufen das aktualisierte Skript notebook.py ab und aktualisieren Ihren Browser. Die Eingabezellen werden basierend auf dem neuen Inhalt von notebook.py aktualisiert. Die Ausgaben werden aus Ihrer lokalen .ipynb Datei neu geladen. Schließlich bleiben die Kernelvariablen unberührt, sodass Sie die Möglichkeit haben, nur die geänderten Zellen auszuführen, um die neuen Ausgaben zu erhalten.

Bearbeiten oder Umgestalten eines Notebooks in einer IDE

Sobald Ihr Notebook mit einer .py Datei gekoppelt ist, können Sie die .py Darstellung des Notebooks in einer IDE problemlos bearbeiten oder umgestalten.

Sobald Sie mit der Bearbeitung des .py Notizbuchs fertig sind, müssen Sie das Notizbuch nur noch in Jupyter laden , um dort die neuesten Änderungen zu erhalten.

Hinweis: Es ist einfacher, das .ipynb Notizbuch in Jupyter zu schließen, wenn Sie die gekoppelte .py Datei bearbeiten. Eine Verpflichtung dazu besteht nicht; Wenn Sie dies jedoch nicht tun, sollten Sie darauf vorbereitet sein, die Popup-Meldungen sorgfältig zu lesen. Wenn Jupyter versucht, das Notebook zu speichern, während die gekoppelte .py Datei seit dem letzten Neuladen auch auf der Festplatte bearbeitet wurde, wird ein Konflikt erkannt und Sie werden aufgefordert, zu entscheiden, welche Version des Notebooks (im Speicher oder auf der Festplatte) die ist passender.