Jupyter notebook : écrivez, exécuter, documentez et publiez votre code Python
Un notebook, en programmation, permet de combiner des sections en langage naturel et des sections en langage de programmation dans un même document.
Un exemple de notebook que j’ai hébergé sur mon compte GitLab
Jupyter est une application web permettant de créer des notebooks. Jupyter permet de programmer en direct en langage Python, langage Julia et langage R. Le code s’y exécute. Le langage de balisage Markdown permet de commenter ce code en langage naturel.
Les documents générés portent l’extension « .ipynb » pour « ipython notebook », Jupyter étant une évolution de IPython. Certains sites permettent de lire nativement ces notebooks. Evidemment, le site officiel de Jupyter à travers son Notebook Viewer en ligne et en ce qui me concerne, puisque j’y publie du code, GitLab possède maintenant un lecteur intégré de notebooks.
Ces notebooks peuvent être facilement exportés au format HTML.
Installation :
Jupyter doit obligatoirement fonctionner avec une installation préalable du langage Python. Python 2.7 ou Python 3.3 et suivant. Les distribution Anaconda intègrent directement Jupyter. Nous allons installer Jupyter via notre gestionnaire de paquets préféré pip.
Vous allez dans le dossier racine de votre installation Python, pour moi : C:\Python3X. Vous appuyez sur la touche MAJ, puis clic droit sur la souris. Vous choisissez « Ouvrir une fenêtre de commande ici »
C:\Python34 > python -m pip install jupyter
Démarrage de l’application et utilisation :
Toujours via CMD (par prudence, dans le dossier d’installation de Python pour être sûr de démarrer l’application avec la version voulue du langage – chez moi 3 versions ;-))
C:\Python34 > jupyter notebook
Par cette manœuvre, vous démarrez le serveur Notebook. Un petit laps de temps est nécessaire. La page http://localhost:8888/tree s’ouvrira dans votre navigateur par défaut. Vous voyez apparaître ce qu’on appelle le tableau de bord (dashboard) et l’arborescence (tree) du dossier dans lequel vous avez démarré le serveur en ligne de commande.
Sur la droite, vous avez le bouton – liste déroulante intitulé « New » qui vous permet de démarrer la création d’un nouveau notebook. Au passage, vous pouvez vérifiez quelle est la version de Python qui sera sollicitée pour exécuter votre code. Ici , il s’agit de Python 3.
Vous cliquez sur « Python 3 ». Un nouvel onglet s’ouvre, intitulé provisoirement « Untitled » puisque sans titre :
Le serveur de Jupyter fait très régulièrement une sauvegarde automatique du document. Voir l’indication «
Par défaut, la première cellule où vous pouvez écrire est configurée pour recevoir du code en entrée.
En effet, la mention « Code » est visible dans la liste déroulante du menu d’édition.
- Code : permet d’écrire du code Python dans la cellule
- Markdown : permet d’écrire du texte dans la cellule avec les balises Markdown
- Raw NBConvert : permet d’écrire dans la cellule du texte simple
- Heading : permet d’écrire du texte avec les balises Markdown consacrées aux titres.
Un petit guide GitHub des balises Markdown qui au passage rend l’écriture d’une page HTML très facile, ce langage étant universellement reconnu par tous les navigateurs.
Dans notre première cellule, nous allons y mettre un titre principal :
Nous choisissons donc « Heading » dans la liste déroulante :
Jupyter vous renseigne rapidement quelle est la syntaxe Markdown pour créer des titres et évidemment pour en modifier la hiérarchie :
# correspond à la balise HTML <h1></h1> ## correspond à la balise <h2></h2>
Ce n’est pas compliqué ! 🙂
Pour désactiver l’édition de cette cellule et l’intégrer au document, il vous suffit d’appuyer simultanément sur la touche MAJ (flèche vers le haut) et la touche ENTER.
Toujours par défaut, la nouvelle cellule est prête à accueillir du code. Si vous voulez rééditer une cellule, il suffit de double-cliquer dessus et d’appuyer simultanément sur la touche MAJ (flèche vers le haut) et la touche ENTER pour la réenregistrer.
Dans la seconde cellule, nous allons mettre un titre secondaire :
Dans la troisième cellule, nous allons y mettre du code à exécuter !
Combinaison magique MAJ+ENTER
Le code est exécuté automatiquement !
Autre exemple avec une fonction input ( ) :
MAJ+ENTER
Entrez un nombre dans la fenêtre
MAJ+ENTER
Si vous voulez ajouter dans votre notebook un texte simple, vous sélectionnez votre cellule puis, dans le menu, vous choisissez « Raw NBConvert », vous tapez votre texte puis MAJ+ENTER ou vous choisissez « Markdown » sans balise puis MAJ+ENTER.
Voici l’aspect des deux formes de textes simples :
Si vous voulez sauvegarder votre notebook avec un nom précis, dans le menu File>Rename. Une boîte de dialogue s’ouvre et vous lui donner le nom que vous voulez.
Si vous avez la curiosité de retourner sur votre onglet « Home » de votre serveur Jupyter :
Vous y trouverez votre notebook, Jupyter vous renseignant qu’il est actif (Running).
Après avoir arrêté votre serveur Jupyter, vous pouvez évidemment créer un dossier consacré à vos notebooks. Puis les recharger lorsque vous relancez votre serveur Jupyter pour par exemple les rééditer.
Pour conclure, je vais évoquer des fonctionnalités intéressantes de Jupyter via le menu « Kernel » :
« Restart & Clear Output » permet d’effacer les cellules d’exécution des codes.
Vous devrez relancer l’exécution de vos codes manuellement avec MAJ+ENTER
« Restart & Run All » permet de relancer l’exécution de toutes vos cellules de code.
Tous les codes s’exécutent automatiquement. Sauf les input ( ).
Au passage ces fonctionnalités renumérotent vos entrées In [ ] dans l’ordre croissant au fil du document.
Concernant la publication : Gitlab et GitHub savent lirent vos notebooks nativement, donc vos fichiers .ipynb. Sinon, logez quelque-part vos fichiers et copier-en le lien dans la page NB Viewer du site consacré à Jupyter. ou tout simplement exportez les au format HTML pour les publier.