scrapbook

album

La bibliothèque Scrapbook enregistre les valeurs des données d'un bloc-notes et le contenu visuel généré sous forme de « fragments ». Les fragments enregistrés peuvent être lus ultérieurement.

Consultez la documentation de Scrapbook pour plus d'informations sur l'utilisation de Scrapbook.

Cas d'utilisation

Les utilisateurs d'ordinateurs portables peuvent souhaiter enregistrer les données produites lors de l'exécution d'un ordinateur portable. Ces données enregistrées, les fragments , peuvent être utilisées ultérieurement ou transmises dans un flux de travail à un autre bloc-notes en tant qu'entrée.

À savoir, Scrapbook vous permet de :

• conserver les données et le contenu visuel affichés dans un bloc-notes sous forme de fragments

• rappeler tout morceau de données persistant

• résumer des collections de cahiers

Prise en charge des versions Python

La cible de support à long terme de cette bibliothèque est Python 3.6+. Il prend actuellement également en charge Python 2.7 jusqu'à ce que Python 2 atteigne sa fin de vie en 2020. Après cette date, la prise en charge de Python 2 cessera et seules les versions 3.x seront maintenues.

Installation

Installer en utilisant pip :

pip install scrapbook

Pour installer des dépendances IO facultatives, vous pouvez spécifier des bundles de magasin individuels, comme s3 ou azure :

pip install scrapbook[s3]

ou utilisez all :

pip install scrapbook[all]

---

Modèles et terminologie

Scrapbook définit les éléments suivants :

• scraps : valeurs de données sérialisables et visualisations telles que des chaînes, des listes d'objets, des dataframes pandas, des graphiques, des images ou des références de données.

• notebook : un objet notebook nbformat encapsulé avec des méthodes supplémentaires pour interagir avec les scraps.

• scrapbook : une collection de cahiers avec une interface pour poser des questions sur la collection.

• encoders : un traducteur enregistré de données vers/depuis des formats de stockage d'ordinateurs portables.

modèle scrap

Le modèle scrap héberge quelques attributs clés dans un tuple, notamment :

• name : Le nom du scrap

• data : toutes les données capturées par l'appel de l'API Scrapbook

• encoder : Le nom de l'encodeur utilisé pour encoder/décoder les données vers/depuis le notebook

• display : Toutes les données d'affichage utilisées par IPython pour afficher du contenu visuel

---

API

Scrapbook ajoute quelques commandes API de base qui permettent d'enregistrer et de récupérer des données, notamment :

• glue pour conserver les restes avec ou sans sortie d'affichage

• read_notebook lit un cahier

• scraps fournit un dictionnaire consultable de tous les scraps par nom

• reglue qui copie un morceau d'un autre cahier vers le cahier actuel

• read_notebooks lit de nombreux cahiers à partir d'un chemin donné

• scraps_report affiche un rapport sur les chutes collectées

• papermill_dataframe et papermill_metrics pour une compatibilité ascendante pour deux fonctionnalités obsolètes de l'usine à papier

Les sections suivantes fournissent plus de détails sur ces commandes API.

glue pour faire persister les restes

Enregistre un scrap (données ou valeur d'affichage) dans la cellule donnée du bloc-notes.

Le scrap (valeur enregistrée) peut être récupéré lors d'une inspection ultérieure du carnet de sortie.

 """Exemple de colle pour enregistrer les valeurs des données"""importer un album en tant que sbsb.glue("hello", "world")sb.glue("number", 123)sb.glue("some_list", [1, 3, 5])sb.glue("some_dict", {"a": 1, "b": 2})sb.glue("non_json", df, 'flèche')

La bibliothèque Scrapbook peut être utilisée ultérieurement pour récupérer scraps du carnet de sortie :

 # lire un cahier et récupérer les fragments précédemment enregistrésnb = sb.read_notebook('notebook.ipynb')nb.scraps

scrapbook impliquera le format de stockage par le type de valeur de tous les encodeurs de données enregistrés. Alternativement, le format de codage implicite peut être écrasé en définissant l'argument encoder sur le nom enregistré (par exemple "json" ) d'un encodeur particulier.

Ces données sont conservées en générant une sortie d'affichage avec un type de média spécial identifiant le format de codage du contenu et les données. Ces sorties ne sont pas toujours visibles dans le rendu du notebook mais existent toujours dans le document. Scrapbook peut ensuite réhydrater les données associées au bloc-notes à l'avenir en lisant ces sorties de cellule.

Avec sortie d'affichage

Pour afficher un scrap nommé avec des sorties d'affichage visibles, vous devez indiquer que le scrap est directement rendu.

Cela peut être fait en basculant l'argument display .

 # enregistre un message d'interface utilisateur avec la chaîne d'entrée sb.glue("hello", "Hello World", display=True)

L'appel sauvegardera les données et les attributs d'affichage de l'objet Scrap, le rendant visible ainsi que l'encodage des données d'origine. Cela s'appuie sur la fonction IPython.core.formatters.format_display_data pour traduire l'objet de données en un dictionnaire d'affichage et de métadonnées que le noyau du notebook doit analyser.

Un autre modèle qui peut être utilisé consiste à spécifier que seules les données d'affichage doivent être enregistrées, et non l'objet d'origine. Ceci est réalisé en réglant l'encodeur pour qu'il soit display .

 # enregistrer une image sans les objets d'entrée d'origineb.glue("shareable_png", IPython.display.Image(filename="shareable.png"), encoder='display')

Enfin, les types de médias générés peuvent être contrôlés en passant un objet liste, tuple ou dict comme argument d'affichage.

 sb.glue("media_as_text_only", media_obj, encoder='display', display=('text/plain',) # Cela passe [text/plain] à l'argument d'inclusion de format_display_data)sb.glue("media_without_text", media_obj, encoder ='display', display={'exclude': 'text/plain'} # transférer vers format_display_data kwargs)

Comme les fragments de données, ceux-ci peuvent être récupérés ultérieurement en accédant à l'attribut display du fragment. Bien que l'on utilise généralement simplement la méthode reglue de Notebook (décrite ci-dessous).

read_notebook lit un cahier

Lit un objet Notebook chargé à partir de l'emplacement spécifié dans path . Vous avez déjà vu comment cette fonction est utilisée dans les exemples d'appels d'API ci-dessus, mais cela fournit essentiellement un mince wrapper sur un NotebookNode d' nbformat avec la possibilité d'extraire des fragments d'album.

 nb = sb.read_notebook('notebook.ipynb')

Cet objet Notebook adhère au schéma json de nbformat, permettant d'accéder à ses champs obligatoires.

 nb.cells # Les cellules du notebooknb.metadatanb.nbformatnb.nbformat_minor

Quelques méthodes supplémentaires sont proposées, dont la plupart sont décrites plus en détail ci-dessous :

 nb.scrapsnb.reglue

L'abstraction rend également le contenu enregistré disponible sous forme de trame de données référençant chaque clé et source. D'autres de ces méthodes seront disponibles dans les versions ultérieures.

 # Produit un bloc de données avec ["name", "data", "encoder", "display", "filename"] comme columnsnb.scrap_dataframe # Attention : cela peut être un objet volumineux si les données ou l'affichage sont volumineux

L'objet Notebook possède également quelques fonctions héritées pour une compatibilité ascendante avec le modèle objet Notebook de Papermill. En conséquence, il peut être utilisé pour lire les statistiques d’exécution des usines de papier ainsi que les abstractions des albums :

 nb.cell_timing # Liste des timings d'exécution des cellules dans l'ordre des cellulesnb.execution_counts # Liste des décomptes d'exécution des cellules dans l'ordre des cellulesnb.papermill_metrics # Dataframe du nombre et des temps d'exécution des cellulesnb.papermill_record_dataframe # Dataframe des enregistrements de cahier (rebuts avec uniquement des données)nb.parameter_dataframe # Dataframe des paramètres du notebooknb.papermill_dataframe # Dataframe des paramètres du notebook et des restes de cellules

Le lecteur de bloc-notes s'appuie sur le logiciel enregistré de Papermill pour permettre l'accès à une variété de sources telles que, sans toutefois s'y limiter, S3, Azure et Google Cloud.

scraps fournit un nom -> recherche de scraps

La méthode scraps permet d'accéder à toutes les notes d'un bloc-notes particulier.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # Imprime un dict de tous les fragments par nom

Cet objet dispose également de quelques méthodes supplémentaires pour une conversion et une exécution pratiques.

 nb.scraps.data_scraps # Filtre uniquement les fragments avec `data` associés à nb.scraps.data_dict # Mappe `data_scraps` à un `nom` -> `data` dictnb.scraps.display_scraps # Filtre uniquement les fragments avec `display` associé à nb. scraps.display_dict # Mappe `display_scraps` à un `nom` -> `display` dictnb.scraps.dataframe # Génère une trame de données avec ["name", "data", "encoder", "display"] comme colonnes

Ces méthodes permettent aux cas d'utilisation simples de ne pas nécessiter de fouiller dans les abstractions du modèle.

reglue copie un morceau dans le carnet actuel

En utilisant reglue vous pouvez prendre n'importe quel morceau de colle dans un cahier et le coller dans celui actuel.

 nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # Cela copie à la fois les données et affiche

Toutes les données ou informations d'affichage seront copiées textuellement dans le bloc-notes en cours d'exécution comme si l'utilisateur avait à nouveau appelé glue sur la source d'origine.

Il est également possible de renommer le scrap au cours du processus.

 nb.reglue("table_scrap", "old_table_scrap")

Et enfin, si l'on souhaite essayer de recoller sans vérifier l'existence, raise_on_missing peut être configuré pour afficher simplement un message en cas d'échec.

 nb.reglue("maybe_missing", raise_on_missing=False)# => "Aucun morceau trouvé avec le nom 'maybe_missing' dans ce carnet"

read_notebooks lit de nombreux cahiers

Lit tous les blocs-notes situés dans un path donné dans un objet Scrapbook.

 # créer un album nommé `book`book = sb.read_notebooks('path/to/notebook/collection/')# récupérer les cahiers sous-jacents sous forme de listbook.notebooks # Ou `book.values`

Le chemin réutilise iorw enregistré par Papermill pour répertorier et lire les fichiers provenant de diverses sources, de sorte que les URL non locales puissent charger des données.

 # créer un album nommé `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')

Le Scrapbook ( book dans cet exemple) peut être utilisé pour rappeler tous les fragments de la collection de cahiers :

 book.notebook_scraps # Dict de forme `notebook` -> (`name` -> `scrap`)book.scraps # dict fusionné de forme `name` -> `scrap`

scraps_report affiche un rapport sur les chutes collectées

La collection Scrapbook peut être utilisée pour générer un scraps_report sur tous les scraps de la collection sous forme de sortie structurée markdown.

 livre.scraps_report()

Cet affichage peut filtrer les noms de scrap et de notebook, ainsi qu'activer ou désactiver un en-tête global pour l'affichage.

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # correspond aux cahiers cheminés `/notebook/collections/result1.ipynb`
  en-tête=Faux)

Par défaut, le rapport ne sera rempli qu'avec des éléments visuels. Pour également créer un rapport sur les éléments de données, définissez include_data.

 book.scraps_report(include_data=True)

support de papeterie

Enfin, le scrapbook fournit deux fonctionnalités rétrocompatibles pour les capacités obsolètes papermill :

 livre.papermill_dataframebook.papermill_metrics

Encodeurs

Les encodeurs sont accessibles par noms de clé aux objets Encoder enregistrés auprès de l'objet encoders.registry . Pour enregistrer de nouveaux encodeurs de données, appelez simplement :

 à partir du registre d'importation de l'encodeur en tant que encoder_registry#, ajoutez l'encodeur au registreencoder_registry.register("custom_encoder_name", MyCustomEncoder())

La classe encode doit implémenter deux méthodes, encode et decode :

 class MyCustomEncoder(object):def encode(self, scrap):# scrap.data est n'importe quel type, généralement spécifique au nom de l'encodeur # Renvoie un `Scrap` avec le type `data` un des [Aucun, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data est l'un des [Aucun, list, dict, *six.integer_types, *six.string_types]pass # Renvoie un `Scrap` avec le type `data` comme n'importe quel type, généralement spécifique au nom de l'encodeur

Cela peut lire, transformer les fragments en un objet json représentant leur contenu ou leur emplacement et recharger ces chaînes dans les objets de données d'origine.

text

Un format de stockage de chaînes de base qui enregistre les données sous forme de chaînes Python.

 sb.glue("bonjour", "monde", "texte")

json

 sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")

pandas

 sb.glue("pandas_df",pd.DataFrame({'col1' : [1, 2], 'col2' : [3, 4]}), "pandas")

fonction record obsolète de Papermill

scrapbook fournit un schéma d'enregistrement robuste et flexible. Cette bibliothèque remplace la fonctionnalité record existante de Papermill.

La documentation relative au record de l'usine de papier existe sur ReadTheDocs. En bref, la fonction record obsolète :

pm.record(name, value) : permet de sauvegarder les valeurs avec le notebook [documentation API]

 pm.record("bonjour", "monde")pm.record("numéro", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "b": 2})

pm.read_notebook(notebook) : les pandas pourraient être utilisés plus tard pour récupérer les valeurs enregistrées en lisant le notebook de sortie dans une trame de données. Par exemple:

 nb = pm.read_notebook('notebook.ipynb')nb.dataframe

Justification de la dépréciation record de Papermill

La fonction record de Papermill est devenue obsolète en raison de ces limitations et défis :

• La fonction record ne suivait pas le modèle d'exécution linéaire d'un cahier de papier. Il était difficile de décrire record comme une fonctionnalité supplémentaire de Papermill, et c'était vraiment comme décrire une deuxième bibliothèque moins développée.

• L'enregistrement/lecture nécessitait la traduction des données en JSON pour tout. Il s'agit d'un processus fastidieux et douloureux pour les dataframes.

• La lecture des valeurs enregistrées dans une trame de données entraînerait des formes de trame de données peu intuitives.

• Moins de modularité et de flexibilité que les autres composants de papeterie où des opérateurs personnalisés peuvent être enregistrés.

Pour surmonter ces limitations dans Papermill, la décision a été prise de créer Scrapbook .