scrapbook

Sammelalbum

Die Scrapbook- Bibliothek zeichnet die Datenwerte eines Notebooks und generierte visuelle Inhalte als „Scraps“ auf. Aufgezeichnete Texte können zu einem späteren Zeitpunkt gelesen werden.

Weitere Informationen zur Verwendung von Scrapbook finden Sie in der Scrapbook-Dokumentation.

Anwendungsfälle

Notebook-Benutzer möchten möglicherweise Daten aufzeichnen, die während der Ausführung eines Notebooks entstehen. Diese aufgezeichneten Daten, Scraps , können zu einem späteren Zeitpunkt verwendet oder in einem Workflow als Eingabe an ein anderes Notebook übergeben werden.

Mit Scrapbook können Sie nämlich:

• Behalten Sie die Anzeige von Daten und visuellen Inhalten in einem Notizbuch als Auszüge bei

• Erinnern Sie sich an alle gespeicherten Datenfetzen

• Fassen Sie Sammlungen von Notizbüchern zusammen

Unterstützung der Python-Version

Das langfristige Supportziel dieser Bibliothek ist Python 3.6+. Derzeit wird auch Python 2.7 unterstützt, bis Python 2 im Jahr 2020 das Ende seiner Lebensdauer erreicht. Nach diesem Datum wird die Unterstützung für Python 2 eingestellt und es werden nur noch 3.x-Versionen beibehalten.

Installation

Mit pip installieren:

pip install scrapbook

Für die Installation optionaler E/A-Abhängigkeiten können Sie einzelne Store-Bundles wie s3 oder azure angeben:

pip install scrapbook[s3]

oder all verwenden:

pip install scrapbook[all]

---

Modelle und Terminologie

Scrapbook definiert die folgenden Elemente:

• Scraps : serialisierbare Datenwerte und Visualisierungen wie Zeichenfolgen, Objektlisten, Pandas-Datenrahmen, Diagramme, Bilder oder Datenreferenzen.

• Notebook : Ein umschlossenes Notebook-Objekt im NB-Format mit zusätzlichen Methoden für die Interaktion mit Scraps.

• Sammelalbum : eine Sammlung von Notizbüchern mit einer Schnittstelle zum Stellen von Fragen zur Sammlung.

• Encoder : ein registrierter Übersetzer von Daten in/von Notebook-Speicherformaten.

scrap

Das scrap -Modell enthält einige Schlüsselattribute in einem Tupel, darunter:

• name : Der Name des Scraps

• Daten : Alle vom Scrapbook-API-Aufruf erfassten Daten

• Encoder : Der Name des Encoders, der zum Codieren/Decodieren von Daten zum/vom Notebook verwendet wird

• display : Alle Anzeigedaten, die IPython zum Anzeigen visueller Inhalte verwendet

---

API

Scrapbook fügt einige grundlegende API-Befehle hinzu, die das Speichern und Abrufen von Daten ermöglichen, darunter:

• glue um Reste mit oder ohne Display-Ausgabe bestehen zu lassen

• read_notebook liest ein Notizbuch

• scraps bietet ein durchsuchbares Wörterbuch aller Scraps nach Namen

• reglue das einen Ausschnitt aus einem anderen Notizbuch in das aktuelle Notizbuch kopiert

• read_notebooks liest viele Notizbücher aus einem bestimmten Pfad

• scraps_report zeigt einen Bericht über gesammelte Scraps an

• papermill_dataframe und papermill_metrics für Abwärtskompatibilität für zwei veraltete Papiermühlenfunktionen

In den folgenden Abschnitten finden Sie weitere Einzelheiten zu diesen API-Befehlen.

glue um Reste bestehen zu lassen

Zeichnet einen scrap (Daten- oder Anzeigewert) in der angegebenen Notebook-Zelle auf.

Der scrap (aufgezeichneter Wert) kann bei einer späteren Überprüfung des Ausgabenotizbuchs abgerufen werden.

 """glue-Beispiel zum Aufzeichnen von Datenwerten"""import scrapbook as 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, 'arrow')

Die Scrapbook-Bibliothek kann später verwendet werden, um scraps aus dem Ausgabenotizbuch wiederherzustellen:

 # Ein Notizbuch lesen und zuvor aufgezeichnete Scrapsnb = sb.read_notebook('notebook.ipynb')nb.scraps abrufen

scrapbook gibt das Speicherformat anhand des Werttyps aller registrierten Datenencoder an. Alternativ kann das implizite Codierungsformat überschrieben werden, indem das encoder Argument auf den registrierten Namen (z. B. "json" ) eines bestimmten Encoders gesetzt wird.

Diese Daten werden beibehalten, indem eine Anzeigeausgabe mit einem speziellen Medientyp generiert wird, der das Inhaltskodierungsformat und die Daten identifiziert. Diese Ausgaben sind beim Notebook-Rendering nicht immer sichtbar, aber dennoch im Dokument vorhanden. Scrapbook kann die mit dem Notebook verknüpften Daten dann in Zukunft durch Lesen dieser Zellausgaben wiederherstellen.

Mit Display-Ausgabe

Um einen benannten Ausschnitt mit sichtbaren Anzeigeausgaben anzuzeigen, müssen Sie angeben, dass der Ausschnitt direkt renderbar ist.

Dies kann durch Umschalten des display erfolgen.

 # eine UI-Nachricht zusammen mit der Eingabe aufzeichnen stringsb.glue("hello", "Hello World", display=True)

Der Aufruf speichert die Daten und die Anzeigeattribute des Scrap-Objekts, macht es sichtbar und kodiert die Originaldaten. Dies basiert auf der Funktion IPython.core.formatters.format_display_data um das Datenobjekt in ein Anzeige- und Metadaten-Dikt zu übersetzen, das der Notebook-Kernel analysieren kann.

Ein anderes Muster, das verwendet werden kann, besteht darin, anzugeben, dass nur die Anzeigedaten und nicht das Originalobjekt gespeichert werden sollen. Dies wird erreicht, indem der Encoder auf display eingestellt wird.

 # ein Bild ohne die ursprünglichen Eingabeobjekte aufzeichnenb.glue("sharable_png", IPython.display.Image(filename="sharable.png"), Encoder='display')

Schließlich können die generierten Medientypen gesteuert werden, indem ein Listen-, Tupel- oder Diktatobjekt als Anzeigeargument übergeben wird.

 sb.glue("media_as_text_only", media_obj, Encoder='display', Display=('text/plain',) # Dies übergibt [text/plain] an das Include-Argument von format_display_data)sb.glue("media_without_text", media_obj, Encoder ='display', display={'exclude': 'text/plain'} # weiter zu den Kwargs von format_display_data)

Ebenso wie Datenschnipsel können diese zu einem späteren Zeitpunkt abgerufen werden, indem auf das Anzeigeattribut des Schrotts zugegriffen display . Normalerweise verwendet man jedoch einfach reglue -Methode von Notebook (unten beschrieben).

read_notebook liest ein Notizbuch

Liest ein Notebook-Objekt, das von dem unter path angegebenen Speicherort geladen wurde. Sie haben bereits gesehen, wie diese Funktion in den obigen Beispielen für API-Aufrufe verwendet wird, aber im Wesentlichen stellt dies einen dünnen Wrapper über dem NotebookNode eines nbformat bereit, mit der Möglichkeit, Scrapbook-Abfälle zu extrahieren.

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

Dieses Notebook-Objekt entspricht dem JSON-Schema des nbformats und ermöglicht den Zugriff auf die erforderlichen Felder.

 nb.cells # Die Zellen aus dem Notebooknb.metadatanb.nbformatnb.nbformat_minor

Es stehen einige zusätzliche Methoden zur Verfügung, von denen die meisten im Folgenden ausführlicher beschrieben werden:

 nb.scrapsnb.reglue

Die Abstraktion stellt außerdem gespeicherte Inhalte als Datenrahmen zur Verfügung, der auf jeden Schlüssel und jede Quelle verweist. Weitere dieser Methoden werden in späteren Versionen verfügbar sein.

 # Erzeugt einen Datenrahmen mit [„Name“, „Daten“, „Encoder“, „Anzeige“, „Dateiname“] als columnsnb.scrap_dataframe. # Warnung: Dies kann ein großes Objekt sein, wenn die Daten oder die Anzeige groß sind

Das Notebook-Objekt verfügt außerdem über einige Legacy-Funktionen für die Abwärtskompatibilität mit dem Notebook-Objektmodell von Papermill. Daher kann es zum Lesen von Ausführungsstatistiken von Papierfabriken sowie von Scrapbook-Abstraktionen verwendet werden:

 nb.cell_timing # Liste der Zellausführungszeiten in der Zellreihenfolgenb.execution_counts # Liste der Zellausführungszahlen in der Zellreihenfolgenb.papermill_metrics # Datenrahmen der Zellausführungszahlen und -zeitennb.papermill_record_dataframe # Datenrahmen der Notebook-Datensätze (Ausschüsse nur mit Daten)nb.parameter_dataframe # Datenrahmen der Notebook-Parameternb.papermill_dataframe # Datenrahmen der Notebook-Parameter und Zellreste

Der Notebook-Reader verlässt sich auf das registrierte IORW von Papermill, um den Zugriff auf eine Vielzahl von Quellen wie – aber nicht beschränkt auf – S3, Azure und Google Cloud zu ermöglichen.

scraps bietet einen Namen -> Scrap-Suche

Die scraps -Methode ermöglicht den Zugriff auf alle Scraps in einem bestimmten Notizbuch.

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # Druckt ein Diktat aller Scraps nach Namen

Dieses Objekt verfügt außerdem über einige zusätzliche Methoden zur bequemen Konvertierung und Ausführung.

 nb.scraps.data_scraps # Filtert nur nach Scraps, denen „data“ zugeordnet ist. nb.scraps.data_dict # Ordnet „data_scraps“ einem „Namen“ zu -> „data“ dictnb.scraps.display_scraps # Filtert nur nach Scraps, denen „display“ zugeordnet ist. scraps.display_dict # Ordnet „display_scraps“ einem „Namen“ -> „Anzeige“ zu dictnb.scraps.dataframe # Erzeugt einen Datenrahmen mit [„Name“, „Daten“, „Encoder“, „Anzeige“] als Spalten

Diese Methoden ermöglichen einfache Anwendungsfälle, sodass kein Durchforsten von Modellabstraktionen erforderlich ist.

reglue kopiert einen Ausschnitt in das aktuelle Notizbuch

Mit reglue kann man alle in ein Notizbuch geklebten Reste nehmen und in das aktuelle einkleben.

 nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # Dadurch werden sowohl Daten als auch Anzeigen kopiert

Alle Daten oder Anzeigeinformationen werden wörtlich in das aktuell ausgeführte Notebook kopiert, als ob der Benutzer erneut glue auf der Originalquelle aufgerufen hätte.

Es ist auch möglich, den Ausschuss dabei umzubenennen.

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

Und schließlich, wenn man versuchen möchte, erneut zu kleben, ohne die Existenz zu prüfen, kann raise_on_missing so eingestellt werden, dass bei einem Fehler nur eine Meldung angezeigt wird.

 nb.reglue("maybe_missing", raise_on_missing=False)# => "Kein Eintrag mit dem Namen 'maybe_missing' in diesem Notizbuch gefunden"

read_notebooks liest viele Notizbücher

Liest alle Notizbücher, die sich in einem bestimmten path befinden, in ein Scrapbook-Objekt.

 # Erstellen Sie ein Sammelalbum mit dem Namen „book“book = sb.read_notebooks('path/to/notebook/collection/')# Holen Sie sich die zugrunde liegenden Notizbücher als listbook.notebooks # Oder „book.values“.

Der Pfad verwendet das registrierte iorw von Papermill wieder, um Dateien aus verschiedenen Quellen aufzulisten und zu lesen, sodass nicht-lokale URLs Daten laden können.

 # Erstellen Sie ein Sammelalbum mit dem Namen „book“book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')

Das Sammelalbum (in diesem Beispiel book “) kann verwendet werden, um alle Fetzen in der Sammlung von Notizbüchern abzurufen:

 book.notebook_scraps # Diktat der Form „Notebook“ -> („Name“ -> „Scrap“)book.scraps # zusammengeführtes Diktat der Form „Name“ -> „Scrap“.

scraps_report zeigt einen Bericht über gesammelte Scraps an

Die Scrapbook-Sammlung kann verwendet werden, um einen scraps_report über alle Scraps aus der Sammlung als strukturierte Markdown-Ausgabe zu erstellen.

 book.scraps_report()

Diese Anzeige kann nach Scrap- und Notebook-Namen filtern sowie eine Gesamtkopfzeile für die Anzeige aktivieren oder deaktivieren.

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # entspricht „/notebook/collections/result1.ipynb“-Notizbüchern mit Pfad
  header=False)

Standardmäßig wird der Bericht nur mit visuellen Elementen gefüllt. Um auch über Datenelemente zu berichten, legen Sie include_data fest.

 book.scraps_report(include_data=True)

Unterstützung der Papierfabrik

Schließlich bietet das Sammelalbum zwei abwärtskompatible Funktionen für veraltete Funktionen papermill :

 book.papermill_dataframebook.papermill_metrics

Encoder

Auf Encoder kann über Schlüsselnamen für Encoder-Objekte zugegriffen werden, die für das Objekt encoders.registry registriert sind. Um neue Datenencoder zu registrieren, rufen Sie einfach an:

 aus der Encoder-Import-Registrierung als Encoder_registry# Encoder zur Registry hinzufügenencoder_registry.register("custom_encoder_name", MyCustomEncoder())

Die Encode-Klasse muss zwei Methoden implementieren: encode und decode :

 class MyCustomEncoder(object):def encode(self, scrap):# scrap.data ist ein beliebiger Typ, normalerweise spezifisch für den Encoder-Namepass # Gibt einen „Scrap“ mit „data“ zurück, Typ eins von [None, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data ist einer von [None, list, dict, *six.integer_types, *six.string_types]pass # Gibt einen „Scrap“ mit dem Typ „data“ als beliebigen Typ zurück, normalerweise spezifisch für den Encodernamen

Dies kann Transformationsreste in ein JSON-Objekt lesen, das ihren Inhalt oder Speicherort darstellt, und diese Zeichenfolgen wieder in die ursprünglichen Datenobjekte laden.

text

Ein grundlegendes String-Speicherformat, das Daten als Python-Strings speichert.

 sb.glue("Hallo", "Welt", "Text")

json

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

pandas

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

Die veraltete record von papermill

scrapbook bietet ein robustes und flexibles Aufzeichnungsschema. Diese Bibliothek ersetzt die bestehende record von Papermill.

Die Dokumentation zum Papierfabrik- record ist auf ReadTheDocs verfügbar. Kurz gesagt, die veraltete record :

pm.record(name, value) : ermöglicht das Speichern von Werten mit dem Notebook [API-Dokumentation]

 pm.record("hello", "world")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "b": 2})

pm.read_notebook(notebook) : Pandas könnten später verwendet werden, um aufgezeichnete Werte wiederherzustellen, indem das Ausgabenotizbuch in einen Datenrahmen eingelesen wird. Zum Beispiel:

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

Begründung für die Einstellung des Papermill- record

Die record von Papermill wurde aufgrund dieser Einschränkungen und Herausforderungen veraltet:

• Die record folgte nicht dem Papermill-Muster der linearen Ausführung eines Notizbuchs. Es war umständlich, record als eine zusätzliche Funktion der Papierfabrik zu beschreiben, und es kam mir tatsächlich so vor, als würde man eine zweite, weniger entwickelte Bibliothek beschreiben.

• Aufzeichnen/Lesen der erforderlichen Datenübersetzung in JSON für alles. Dies ist ein langwieriger und schmerzhafter Prozess für Datenrahmen.

• Das Einlesen aufgezeichneter Werte in einen Datenrahmen würde zu nicht intuitiven Datenrahmenformen führen.

• Weniger Modularität und Flexibilität als andere Papierfabrikkomponenten, bei denen kundenspezifische Bediener registriert werden können.

Um diese Einschränkungen in Papermill zu überwinden, wurde beschlossen, Scrapbook zu erstellen.