Cours
Écrire des fonctions en Python
4 h
113.5K
En science des données, vous devez souvent créer des rapports pour les présenter à des décideurs ou à des publics non techniques. Convertir votre notebook Jupyter en PDF ou en HTML stable facilite le partage avec des collègues qui n’ont pas Python ni Jupyter installés. Python s’appuie sur une bibliothèque appelée nbconvert et sur un langage de templating nommé Jinja2 pour la conversion de documents. Les modèles définissent la manière dont un document s’affiche sur une page web ou dans un autre format de sortie. Savoir personnaliser ces modèles vous aidera à produire des rapports soignés à partir de vos notebooks.
Les notebooks Jupyter permettent d’exécuter du code Python dans votre navigateur. Si vous souhaitez en savoir plus sur Python, consultez notre cours gratuit Intro to Python for Data Science.
Dans ce tutoriel, vous allez aborder les sujets suivants :
- Les modèles et le moteur de templates
Jinja2. - Le rendu des modèles et l’héritage.
- Comment utiliser
nbconvertpour exporter vos notebooks. - La syntaxe et la structure pour étendre les modèles HTML par défaut de Jupyter.
- Les différences d’export vers LaTeX et PDF.
Qu’est-ce qu’un modèle ?
D’après le wiki Python : « Le templating, et en particulier le templating web, est un moyen de représenter des données sous différentes formes… Les solutions de templating impliquent fréquemment un document (le modèle) et des données. Les modèles ressemblent généralement au rendu final, avec des espaces réservés à la place des données réelles ».
Vous pouvez exporter un notebook Jupyter très facilement via File -> Download As (dans JupyterLab, vous verrez Export Notebook As). Cette option utilise les modèles par défaut fournis par l’environnement Jupyter. Jinja2 est un langage de templating puissant pour Python, permettant de définir des blocs et la mise en forme. Les modèles comportent des sections, définies par des balises, qui indiquent comment rendre les données en entrée. Les données remplacent les variables ou expressions au moment du rendu du modèle.
Les délimiteurs des différentes sections d’un modèle sont :
{% ... %}pour les instructions (Statements){{ ... }}pour les expressions affichées dans la sortie{# ... #}pour les commentaires non inclus dans la sortie
Voici un court exemple de modèle Jinja (extrait de la documentation Jinja2) :
<!DOCTYPE html>
<html lang="en">
<head>
{% block head %}
<link rel="stylesheet" href="style.css" />
<title>{% block title %}{% endblock %} - My Webpage </title>
{% endblock %}
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
<div id="footer">
{% block footer %}
© Copyright 2008 by <a href="http://domain.invalid">you </a>.
{% endblock %}
</div>
</body>
</html>
Vous voyez ci‑dessus que le modèle ressemble beaucoup à un document HTML classique. Jinja ajoute juste quelques lignes pour interpréter le code en tant que modèle. Le bloc {% block head %} définit l’en‑tête du document HTML et la façon dont ce modèle étendra sa mise en forme. La section {% block title %} indique l’emplacement d’affichage du titre en entrée. Et {% endblock %} apparaît à plusieurs endroits pour clôturer chaque bloc correspondant.
Vous êtes maintenant prêt à utiliser Jinja pour créer vos propres modèles personnalisés.
Introduction à Jinja
Jinja est un moteur de templates qui vous permet de définir l’affichage de vos documents. Dans ce tutoriel, vous allez vous concentrer sur l’export de votre notebook Jupyter à l’aide de modèles Jinja.
Commencez par importer Template depuis Jinja2 :
from jinja2 import Template
Comprendre le rendu de base avec les modèles
Rendre des données dans des modèles Jinja est assez simple. À l’aide d’accolades et de noms de variables, vous pouvez afficher vos données dans le modèle :
myTemplate = Template("My template is {{ something }}!")
myTemplate.render(something="awesome")
'My template is awesome!'
Appeler .render(input) permet d’afficher le modèle dans votre notebook en remplaçant l’occurrence générique {{ something }} par votre entrée. C’est un exemple d’utilisation d’une expression dans Jinja.
Vous pouvez rendre un modèle plus dynamique en définissant une instruction Python, que Jinja interprétera.
myFancyTemplate = Template("Let's count to 10: {% for i in range(11) %}{{i}} " "{% endfor %}")
myFancyTemplate.render()
"Let's count to 10: 0 1 2 3 4 5 6 7 8 9 10 "
Remarquez que vous avez défini une boucle for et que le modèle a rendu les nombres de 0 à 10 séparés par des espaces. La syntaxe d’instruction {% expression %} offre une grande flexibilité pour créer un modèle sur mesure.
Héritage de modèles
Pour étendre les exports par défaut de Jupyter, vous pouvez utiliser l’héritage de modèles. En programmation, l’héritage permet à un objet enfant de réutiliser les fonctionnalités définies par le parent. Par exemple, si vous avez un objet Dog qui peut aboyer, manger et marcher, vous pouvez créer, par héritage, un objet Dalmatian qui récupère ces attributs et en ajoute d’autres, comme a des taches. Dans ce tutoriel, vous verrez à quel point l’héritage est utile pour les modèles, car il suffit souvent de petites modifications pour personnaliser la sortie. Comme d’autres langages d’héritage, Jinja utilise des mots‑clés comme extends et super pour accéder aux définitions parentes.
Reprenez l’exemple de modèle parent ci‑dessus, appelé base.html :
<!DOCTYPE html>
<html lang="en">
<head>
{% block head %}
<link rel="stylesheet" href="style.css" />
<title>{% block title %}{% endblock %} - My Webpage </title>
{% endblock %}
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
<div id="footer">
{% block footer %}
© Copyright 2008 by <a href="http://domain.invalid">you </a>.
{% endblock %}
</div>
</body>
</html>
Un modèle enfant pourrait ressembler à ceci (d’après la documentation Jinja2) :
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block head %}
{{ super() }}
<style type="text/css">
.important { color: #336699; }
</style>
{% endblock %}
{% block content %}
<h1>Index</h1>
<p class="important">
Welcome to my awesome homepage.
</p>
{% endblock %}
Notez que le modèle enfant commence par {% extends "base.html" %}. Cette déclaration indique au moteur de templates Jinja comment traiter ce document (comme un HTML héritant de base.html). Utiliser ce modèle enfant permet de spécifier différents attributs pour la page d’accueil (par exemple une couleur CSS spécifique). Vous voyez aussi dans le bloc head que le modèle enfant hérite du style du parent grâce à l’appel à super().
Utiliser nbconvert pour exporter des notebooks Jupyter
Maintenant que vous maîtrisez la syntaxe de base et l’héritage des modèles, voyons comment exporter votre notebook Jupyter avec nbconvert et définir des modèles pour personnaliser le rendu.
Commencez par importer nbconvert :
import nbconvert
nbconvert peut produire de nombreux formats. Ce tutoriel se concentre sur les sorties HTML et LaTeX/PDF. Pour visualiser le rendu dans le notebook, utilisez la fonction d’affichage d’IPython et l’option --stdout dans votre appel à nbconvert.
example = !jupyter nbconvert --to html 'Example.ipynb' --stdout
from IPython.display import HTML, display
display(HTML('\n'.join(example)))
[NbConvertApp] Converting notebook Example.ipynb to html
Cet extrait d’un notebook ressemble beaucoup au fichier .ipynb d’origine. La sortie s’affiche comme un document autonome avec titres et texte tels qu’ils apparaissent habituellement dans un notebook. Les cellules de code sont présentées dans des encadrés gris (appelé « Notebook style »). La principale différence visible est que le modèle HTML par défaut de Jupyter n’affiche pas les invites « Out: » comme le font les notebooks actifs.
Utiliser nbconvert et un modèle enfant personnalisé pour exporter des notebooks Jupyter
En pratique, vous souhaiterez étendre les modèles d’export par défaut de Jupyter Notebook et apporter de petites touches de design à votre sortie.
Par exemple, voici un modèle simple qui supprime les cellules Markdown de la sortie (appelé rmMkdwn.tpl) :
{% extends 'basic.tpl'%}
{% block markdowncell -%}
{% endblock markdowncell %}
Pour appliquer un modèle avec nbconvert, utilisez l’option --template= :
example = !jupyter nbconvert --to html 'Example.ipynb' --template='rmMkdwn.tpl' --stdout
display(HTML('\n'.join(example)))
[NbConvertApp] Converting notebook Example.ipynb to html 
Même un modèle très simple, comme rmMkdwn.tpl, peut vous aider à personnaliser considérablement votre rendu.
Voici un modèle plus élaboré, qui encadre les cellules en rouge (appelé boxRed.tpl) :
{% extends 'full.tpl'%}
{% block any_cell %}
<div style="border:thin solid red">
{{ super() }}
</div>
{% endblock any_cell %}
example = !jupyter nbconvert --to html 'Example.ipynb' --template='boxRed.tpl' --stdout
display(HTML('\n'.join(example)))
[NbConvertApp] Converting notebook Example.ipynb to html 
Comme vous le voyez, l’unique changement de style est l’ajout d’un encadré rouge autour de chaque cellule. L’appel à super() garantit que chaque cellule conserve son style individuel défini par le modèle parent full.tpl.
Différences de modèles pour l’export LaTeX et PDF
Comme { } et % sont des caractères spéciaux en LaTeX, vous devez utiliser (( )) et *. Les modèles LaTeX par défaut sont base.tplx, article.tplx et report.tplx, qui correspondent aux classes de documents LaTeX.
Voici comment supprimer les cellules Markdown avec un modèle enfant LaTeX :
((* extends 'article.tplx' *))
((* block markdowncell -*))
((* endblock markdowncell *))
nbconvert peut produire du LaTeX ou du PDF – le PDF est compilé à partir des modèles LaTeX. Pour faciliter la lecture dans ce tutoriel, observons l’export en PDF avec rmMkdwn.tplx.
!jupyter nbconvert --to pdf 'Example.ipynb' --template='rmMkdwn.tplx'
from IPython.display import IFrame
IFrame('Example.pdf', width=800, height=500)
[NbConvertApp] Converting notebook Example.ipynb to pdf
[NbConvertApp] Support files will be in Example_files/
[NbConvertApp] Making directory Example_files
[NbConvertApp] Writing 16047 bytes to notebook.tex
[NbConvertApp] Building PDF
[NbConvertApp] Running xelatex 3 times: ['xelatex', 'notebook.tex']
[NbConvertApp] Running bibtex 1 time: ['bibtex', 'notebook']
[NbConvertApp] WARNING | bibtex had problems, most likely because there were no citations
[NbConvertApp] PDF successfully created
[NbConvertApp] Writing 16102 bytes to Example.pdf
Vous remarquerez que le rendu diffère sensiblement de la version HTML. LaTeX fait remonter la première cellule Markdown en titre d’article, elle s’affiche donc dans la sortie. Le modèle a bien supprimé le sous‑titre (il a donc considéré cette cellule comme du vrai Markdown). La classe de document article met à jour la date du jour — ce qui n’est pas présent dans le notebook d’origine. La police et les espacements diffèrent de la version HTML. Enfin, par défaut, la sortie utilise l’affichage IPython classique, et non le « Notebook style ».
Si vous choisissez d’étendre une classe de document LaTeX fournie par Jupyter, assurez‑vous d’en maîtriser les règles de mise en forme.
Conclusion
Voici les points essentiels à retenir sur les modèles, Jinja2 et nbconvert.
Les modèles définissent la façon dont un document s’affiche sur une page web ou dans un autre format. Les notebooks Jupyter utilisent des modèles Jinja pour proposer différents formats d’export. Les modèles suivent des règles d’héritage qui permettent de définir des modèles parents et enfants pour des pages similaires avec une mise en forme légèrement différente.
Les modèles Jinja contiennent des instructions, des expressions et (facultativement) des commentaires. Les instructions, délimitées par {% statement %}, structurent le modèle. Les expressions, délimitées par {{ expression }}, injectent vos données dans le modèle. Les commentaires, délimités par {# comment #}, ne s’affichent pas en sortie — ils sont internes au modèle.
nbconvert est une bibliothèque Python qui permet de convertir votre notebook Jupyter vers d’autres formats, comme HTML, LaTeX et PDF. nbconvert utilise des modèles Jinja pour définir l’affichage des notebooks dans ces formats. Vous pouvez définir des modèles personnalisés ou étendre les modèles par défaut de Jupyter via l’héritage.
Vous êtes maintenant prêt à créer vos propres modèles et à exporter de superbes documents Jupyter Notebook !
Références :