Jupytext

Avez-vous toujours souhaité que les blocs-notes Jupyter soient des documents en texte brut ? Vous souhaiteriez pouvoir les modifier dans votre IDE préféré ? Et obtenir des différences claires et significatives lors du contrôle de version ? Alors, Jupytext pourrait bien être l’outil que vous recherchez !

Cahiers de texte

Un notebook Python codé au format py:percent a une extension .py et ressemble à ceci :

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

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

Seules les entrées du notebook (et éventuellement les métadonnées) sont incluses. Les blocs-notes de texte sont bien adaptés au contrôle de version. Vous pouvez également les modifier ou les refactoriser dans un IDE - le bloc-notes .py ci-dessus est un fichier Python standard.

Nous recommandons le format percent pour les notebooks qui contiennent principalement du code. Le format percent est disponible pour Julia, Python, R et de nombreux autres langages.

Si votre bloc-notes est orienté documentation, un format basé sur Markdown (bloc-notes texte avec une extension .md ) pourrait être plus approprié. Selon ce que vous envisagez de faire avec votre notebook, vous préférerez peut-être le format Myst Markdown, qui interagit très bien avec Jupyter Book, ou Quarto Markdown, ou encore Pandoc Markdown.

Installation

Installez Jupytext dans l'environnement Python que vous utilisez pour Jupyter. Utilisez soit

 pip install jupytext

ou

 conda install jupytext -c conda-forge

Ensuite, redémarrez votre serveur Jupyter Lab et assurez-vous que Jupytext est activé dans Jupyter : les fichiers .py et .md ont une icône de bloc-notes et vous pouvez les ouvrir en tant que blocs-notes avec un clic droit dans Jupyter Lab.

Cahiers jumelés

Les blocs-notes de texte avec une extension .py ou .md sont bien adaptés au contrôle de version. Ils peuvent être édités ou créés facilement dans un IDE. Vous pouvez les ouvrir et les exécuter en tant que blocs-notes dans Jupyter Lab avec un clic droit. Cependant, les sorties du bloc-notes sont perdues lorsque celui-ci est fermé, car seules les entrées du bloc-notes sont enregistrées dans les blocs-notes de texte.

Les cahiers jumelés constituent une alternative pratique aux cahiers de texte. Il s'agit d'un ensemble de deux fichiers, par exemple .ipynb et .py , qui contiennent le même bloc-notes, mais dans des formats différents.

Vous pouvez modifier la version .py du bloc-notes couplé et récupérer les modifications dans Jupyter en sélectionnant recharger le bloc-notes à partir du disque . Les sorties seront rechargées à partir du fichier .ipynb , s'il existe. La version .ipynb sera mise à jour ou recréée la prochaine fois que vous enregistrerez le bloc-notes dans Jupyter.

Pour associer un notebook dans Jupyter Lab, utilisez la commande Pair Notebook with percent Script de la palette de commandes :

Pour associer tous les notebooks d'un certain répertoire, créez un fichier de configuration avec ce contenu :

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

Ligne de commande

Jupytext est également disponible sur la ligne de commande. Tu peux

associez un cahier avec jupytext --set-formats ipynb,py:percent notebook.ipynb
synchronisez les fichiers couplés avec jupytext --sync notebook.py (les entrées sont chargées à partir du fichier couplé le plus récent)
convertissez un notebook d'un format à un autre avec jupytext --to ipynb notebook.py (utilisez -o si vous voulez un fichier de sortie spécifique)
dirigez un notebook vers un linter avec par exemple jupytext --pipe black notebook.ipynb

Exemples de cas d'utilisation

Notebooks sous contrôle de version

Voici une procédure rapide :

Ouvrez votre notebook .ipynb dans Jupyter et associez-le à un notebook .py , à l'aide de la commande pair dans Jupyter Lab ou d'un fichier de configuration global.
Enregistrez le bloc-notes - cela crée un bloc-notes .py
Ajoutez ce notebook .py au contrôle de version

Vous pouvez exclure les fichiers .ipynb du contrôle de version (sauf si vous souhaitez voir les sorties versionnées !). Jupytext recréera les fichiers .ipynb localement lorsque les utilisateurs ouvriront et enregistreront les blocs-notes .py .

Collaborer sur des notebooks avec Git

Collaborer sur des notebooks Jupyter via Git devient aussi simple que collaborer sur des fichiers texte.

Supposons que vos notebooks .py soient sous contrôle de version (voir ci-dessus). Alors,

Votre collaborateur récupère le notebook .py
Ils l'ouvrent sous forme de bloc-notes dans Jupyter (clic droit dans Jupyter Lab)
À ce stade, le portable n'a aucune sortie. Ils exécutent le bloc-notes et le sauvegardent. Les sorties sont régénérées et un fichier .ipynb local est créé
Ils modifient le bloc-notes et envoient le fichier notebook.py mis à jour. Le diff n'est rien d'autre qu'un diff standard sur un script Python.
Vous extrayez le script notebook.py mis à jour et actualisez votre navigateur. Les cellules d'entrée sont mises à jour en fonction du nouveau contenu de notebook.py . Les sorties sont rechargées à partir de votre fichier .ipynb local. Enfin, les variables du noyau restent intactes, vous avez donc la possibilité d'exécuter uniquement les cellules modifiées pour obtenir les nouvelles sorties.

Modification ou refactorisation d'un notebook dans un IDE

Une fois votre bloc-notes associé à un fichier .py , vous pouvez facilement modifier ou refactoriser la représentation .py du bloc-notes dans un IDE.

Une fois que vous avez terminé de modifier le bloc-notes .py , il vous suffira de recharger le bloc-notes dans Jupyter pour y obtenir les dernières modifications.

Remarque : Il est plus simple de fermer le bloc-notes .ipynb dans Jupyter lorsque vous modifiez le fichier .py associé. Il n’y a aucune obligation de le faire ; cependant, si vous ne le faites pas, vous devez être prêt à lire attentivement les messages contextuels. Si Jupyter tente de sauvegarder le notebook alors que le fichier .py associé a également été modifié sur le disque depuis le dernier rechargement, un conflit sera détecté et il vous sera demandé de décider quelle version du notebook (en mémoire ou sur disque) est la celui qui convient.