papermill

papermill est un outil de paramétrage, d'exécution et d'analyse des notebooks Jupyter.

Papermill vous permet de :

• paramétrer les notebooks
• exécuter des cahiers

Cela ouvre de nouvelles opportunités quant à la façon dont les ordinateurs portables peuvent être utilisés. Par exemple:

• Peut-être avez-vous un rapport financier que vous souhaitez générer avec des valeurs différentes le premier ou le dernier jour d'un mois ou au début ou à la fin de l'année, l'utilisation de paramètres facilite cette tâche.
• Voulez-vous exécuter un notebook et, en fonction de ses résultats, choisir un notebook particulier à exécuter ensuite ? Vous pouvez désormais exécuter un flux de travail par programmation sans avoir à copier et coller manuellement d'un bloc-notes à l'autre.

Papermill adopte une approche avisée du paramétrage et de l'exécution des notebooks, basée sur nos expériences d'utilisation de notebooks à grande échelle dans des pipelines de données.

Installation

Depuis la ligne de commande :

 pip install papermill

Pour toutes les dépendances io facultatives, vous pouvez spécifier des bundles individuels comme s3 ou azure – ou utiliser all . Pour utiliser Black pour formater les paramètres que vous pouvez ajouter en supplément, il faut ['black'].

 pip install papermill[all]

Prise en charge des versions Python

Cette bibliothèque prend actuellement en charge les versions Python 3.8+. Comme les versions mineures de Python sont officiellement supprimées par la papeterie de l'organisation Python, elles abandonneront également leur support à l'avenir.

Usage

Paramétrage d'un bloc-notes

Pour paramétrer votre notebook désignez une cellule avec la balise parameters .

Papermill recherche la cellule parameters et traite cette cellule comme valeur par défaut pour les paramètres transmis au moment de l'exécution. Papermill ajoutera une nouvelle cellule étiquetée avec injected-parameters avec des paramètres d'entrée afin d'écraser les valeurs dans parameters . Si aucune cellule n'est étiquetée avec parameters la cellule injectée sera insérée en haut du cahier.

De plus, si vous réexécutez les blocs-notes via Papermill, cela réutilisera la cellule injected-parameters de l'exécution précédente. Dans ce cas, Papermill remplacera l'ancienne cellule injected-parameters par les entrées de la nouvelle exécution.

Exécuter un bloc-notes

Les deux manières d'exécuter le notebook avec des paramètres sont : (1) via l'API Python et (2) via l'interface de ligne de commande.

Exécuter via l'API Python

 import papermill as pm

pm.execute_notebook(
   'path/to/input.ipynb',
   'path/to/output.ipynb',
   parameters = dict(alpha=0.6, ratio=0.1)
)

Exécuter via CLI

Voici un exemple d'un bloc-notes local exécuté et envoyé vers un compte Amazon S3 :

 $ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1

REMARQUE : Si vous utilisez plusieurs comptes AWS et que vous avez correctement configuré vos informations d'identification AWS, vous pouvez spécifier le compte à utiliser en définissant la variable d'environnement AWS_PROFILE sur la ligne de commande. Par exemple:

 $ AWS_PROFILE=dev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1

Dans l'exemple ci-dessus, deux paramètres sont définis : alpha et l1_ratio en utilisant -p ( --parameters fonctionne également). Les valeurs de paramètres qui ressemblent à des booléens ou à des nombres seront interprétées comme telles. Voici les différentes manières dont les utilisateurs peuvent définir les paramètres :

 $ papermill local/input.ipynb s3://bkt/output.ipynb -r version 1.0

En utilisant -r ou --parameters_raw , les utilisateurs peuvent définir les paramètres un par un. Cependant, contrairement à -p , le paramètre restera une chaîne, même s'il peut être interprété comme un nombre ou un booléen.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -f parameters.yaml

En utilisant -f ou --parameters_file , les utilisateurs peuvent fournir un fichier YAML à partir duquel les valeurs des paramètres doivent être lues.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -y "
alpha: 0.6
l1_ratio: 0.1"

En utilisant -y ou --parameters_yaml , les utilisateurs peuvent directement fournir une chaîne YAML contenant les valeurs des paramètres.

 $ papermill local/input.ipynb s3://bkt/output.ipynb -b YWxwaGE6IDAuNgpsMV9yYXRpbzogMC4xCg==

En utilisant -b ou --parameters_base64 , les utilisateurs peuvent fournir une chaîne YAML, codée en base64, contenant les valeurs des paramètres.

Lorsque vous utilisez YAML pour transmettre des arguments, via -y , -b ou -f , les valeurs des paramètres peuvent être des tableaux ou des dictionnaires :

 $ papermill local/input.ipynb s3://bkt/output.ipynb -y "
x:
    - 0.0
    - 1.0
    - 2.0
    - 3.0
linear_function:
    slope: 3.0
    intercept: 1.0"

Gestionnaires de noms pris en charge

Papermill prend en charge les gestionnaires de noms suivants pour les chemins d'entrée et de sortie lors de l'exécution :

• Système de fichiers local : local

• Protocole HTTP, HTTPS : http://, https://

• Services Web Amazon : AWS S3 s3://

• Azure : Azure DataLake Store, Azure Blob Store adl://, abs://

• Google Cloud : Google Cloud Storage gs://

Guide de développement

Lisez CONTRIBUTING.md pour obtenir des directives sur la façon de configurer un environnement de développement local et d'apporter des modifications au code dans Papermill.

Pour les directives de développement, consultez le fichier DEVELOPMENT_GUIDE.md. Cela devrait vous informer sur la manière d'effectuer des ajouts particuliers à la base de code.

Documentation

Nous hébergeons la documentation Papermill sur ReadTheDocs.