Explication du code

Les extensions de jupyter notebook

Toutes les extension Jupyter installées sont stockées dans le répertoire de jupyter_contrib_nbextensions/nbextensions. Faites la commande « jupyter --path » pour retrouver ce répertoire. Le code de la plupart des extensions est organisé en 3 fichiers :

• .yaml fichier de configuration qui a les informations sur l’extension et les ressources utilisées
• main.js contenant le script en JavaScript
• readme.md pour la documentation. Certaines extensions plus complexes contiennent également du code python et des fichiers de ressource comme des images... Pour créer son extension, il suffit de créer un répertoire dans nbextensions et d’y mettre les 3 fichiers. Ensuite il faut l’installer et l’autoriser via ligne de commande par exemple.

Installer une extension :

jupyter nbextension install <chemin du dossier de l’extension>

Activer une extension :

jupyter nbextension enable < chemin du fichier JavaScript de l’extension (ex. main.js)>

Contenu d’un fichier notebook

Dans cet extension on manipule les données d’un notebook pour la faire fonctionner. Un notebook est un dictionnaire ayant deux clés cells qui est un tableau de cellules et metadata (Une métadonnée est une donnée servant à définir ou décrire une autre donnée quel que soit son support). Une cellule est un dictionnaire contenant toutes les informations sur elle, à savoir le type de cellule “cell_type”, “metadata” , “source” et si c’est du code la cellule a deux autres clés “execution_count” le nombre de fois que le code a été exécuté et “outputs” le résultat un fois exécuté. Les types de cellule sont markdown, code, raw et la source est le texte brut contenant dans la cellule.

Fonctionnement de l’extension

Fichier de configuration de l’extension

Dans ce fichier description.yaml on définit les informations nécessaires et options. L’extension de nom « Visual Python Tutor » est de type Jupyter Notebook extension, elle est campatible avec les versions supérieurs 4.x et 5.x de jupyter. Pour les options nous avons deux checkbox (variable boolean) et un input de type texte :

• add_btn_toobar : Affiche le bouton "Python Tutor" dans le menu de la barre d'outils
• add_btn_cell : Permet d'ajouter le bouton d'une cellule par défaut.
• server_url : Choisissez le serveur sur lequel le code est affiché, par défaut, nous utilisons un tuteur python en ligne. Si vous avez pytutor localement, entrez la valeur «http://localhost:8003/». Ces variables seront utilisées dans main.js pour changer le comportement de l’extension selon les choix de l’utilisateur.

Les paramètres sur l'interface de configuration des nbextensions de jupyter.

Organisation du code JavaScript

Dans le fichier .js il y a une fonction define prenant deux paramètres :

• un tableau qui contient les librairies à importées.
• l'autre paramètre est une fonction avec des objets en paramètre comme Jupyter, events, requirejs. La fonction define retourne un objet ayant un attribut spécialement nommé load_ipython_extension avec comme valeur une fonction. Cette dernière sera appelée par le notebook lorsque la nbextension doit être chargée. Cependant, son exécution ne doit pas prendre trop de temps, sinon le notebook supposera qu'une erreur s'est produite.

Explication du code :

Nous avons besoin des variables globales et des fonctions pour bien organiser le code.

Les variables

• btnvisu : c’est une chaîne contenant l'élément html qui a le bouton vers python tutor, donc elle sera accessible dès que qu’on veut ajouter un nouveau bouton.
• params : un objet qui a les paramètres de l’extension, il a 3 attributs booléens qui sont initialisés à true par défaut : add_btn_toobar, add_btn_cell, add_btn_create_select_cell. Voir la section Fichier de configuration de l’extension pour savoir leur utilité.
• nb_visualize : contient la métadata visualization du notebook : Jupyter.notebook.metadata.visualization, cela évite de recréer cette variable à chaque fois qu'on veut ajouter un bouton à coté dune cellule.

Les fonctions

• load_ipython_extension() : elle sera appelée par le notebook lorsque la nbextension doit être chargée. La fonction define retourne un objet dont le membre ‘load_ipython_extension’ a pour valeur la fonction load_ipython_extension().

• init : elle charge les paramètres de l'extension avant d'initialiser les boutons et les événements. On charge les paramétres avec le serveur de notebook via ‘$.extend(true, params, Jupyter.notebook.config.data)’. Elle ajoute le bouton ‘python tutor’ du menu si les paramétres de le permet, puis ajoute les boutons pour les cellules qui doivent en avoir. Enfin elle ajoute un évènement à chaque bouton, ce qui permet de visualiser le code pour une cellule spécifique. Une cellule aura un bouton si certaines conditions sont remplies:

_ la cellule doit être de type ‘code’ et son métadata ‘visualization’ vaut pas false sinon aucun bouton n’est ajouté et si true le bouton python tutor est ajouté.

_ Dans le cas où la métadata de la cellule n’est pas définie, on vérifie celle du notebook, si elle vaut true il y’a le bouton sinon on passe aux paramètres de l’extension et rien n’est fait si la métadata du notebook faut false.

_ Si aucune de ces conditions ci-dessus n’est remplie on regarde la valeur add_btn_cell des paramètres, le bouton est ajouté si et selement si le elle est true.

• toPyTutor(cell) : fonction prenant en paramètre une cellule et qui renvoie vers python tutor le code de la cellule si elle n’est pas vide (message d’alerte dans ce cas). Elle récupère le code de la celle avec cell.get_text(), crée l’url avec la fonction fixedEncodeURIComponent(codeCell) et l’ouvre dans un nouveau onglet.

• fixedEncodeURIComponent(str) : Pour créer le lien vers le tuteur python, nous devons remplacer les caractères par la référence de codage d'URL HTML La fonction encodeURIComponent() permet de le faire et on remplace certains caractères qui empêchent la visualisation sur python tutor.

• on_changeType_or_create_cell : quand une cellule est créée (ajoutée au notebook) ou change de type, cette fonction est aussi appelée ajouter un bouton à la nouvelle cellule ou à une cellule qui change de type vers ‘code’ si les conditions sont satisfaites. On remarque lors du changement de type, la cellule met un peu de temps à se recréer. Nous utilisons donc un setTimeout() et attendre la fin de sa création avant d'appeler la fonction add_btn_to_element (), à partir de là, nous pouvons accéder aux métadonnées de la cellule.