Previous Next

scrapbook package

Submodules

scrapbook.api module

api.py

Provides the base API calls for scrapbook

scrapbook.api.glue(name, scrap, storage=None)

Records a scrap (data value) in the given notebook cell.

The scrap (recorded value) can be retrieved during later inspection of the output notebook.

The storage format of the scraps is implied by the value type any registered data translators, but can be overwritten by setting the storage argument to a particular translator’s registered name (e.g. “json”).

This data is persisted by generating a display output with a special media type identifying the content storage format and data. These outputs are not visible in notebook rendering but still exist in the document. Scrapbook then can rehydrate the data associated with the notebook in the future by reading these cell outputs.

Example

sb.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’)

The scrapbook library can be used later to recover scraps (recorded values) from the output notebook

nb = sb.read_notebook(‘notebook.ipynb’) nb.scraps

Parameters:

• name (str) – Name of the value to record.
• scrap (any) – The value to record.
• storage (str (optional)) – The data protocol name to respect in persisting data

scrapbook.api.read_notebook(path)

Returns a Notebook object loaded from the location specified at path.

Parameters:path (str) – Path to a notebook .ipynb file. Returns:notebook – A Notebook object. Return type:object

scrapbook.api.read_notebooks(path)

Returns a Scrapbook including the notebooks read from the directory specified by path.

Parameters:path (str) – Path to directory containing notebook .ipynb files. Returns:scrapbook – A Scrapbook object. Return type:object

scrapbook.api.sketch(name, obj)

Display a named snap (visible display output) in a retrievable manner. Unlike glue this is intended to generate a snap for notebook interfaces to render.

Example

sb.sketch(“hello”, “Hello World”) sb.sketch(“sharable_png”, IPython.display.Image(filename=get_fixture_path(“sharable.png”)))

Like scraps these can be retrieved at a later time, though they don’t cary any actual data, just the display result of some object.

nb = sb.read_notebook(‘notebook.ipynb’) nb.snaps

More usefully, you can copy snaps from earlier executions to re-display the object in the current notebook.

nb = sb.read_notebook(‘notebook.ipynb’) nb.resketch(“sharable_png”)

Parameters:

• name (str) – Name of the output.
• obj (object) – An object that can be displayed in the notebook.

scrapbook.exceptions module

exception scrapbook.exceptions.ScrapbookException

Bases: ValueError

Raised when an exception is encountered when operating on a notebook.

scrapbook.log module

scrapbook.models module

notebook.py

Provides the Notebook wrapper objects for scrapbook

class scrapbook.models.Notebook(node_or_path, translators=None)

Bases: object

Representation of a notebook.

Parameters:node (nbformat.NotebookNode, str) – a notebook object, or a path to a notebook object

cell_timing

list – a list of cell execution timings in cell order

directory

str – directory name found for a notebook (nb)

execution_counts

list – a list of cell execution counts in cell order

filename

str – filename found a the specified path

papermill_dataframe

pandas dataframe – dataframe of notebook parameters and cell scraps

papermill_metrics

pandas dataframe – dataframe of cell execution counts and times

parameter_dataframe

pandas dataframe – dataframe of notebook parameters

parameters

dict – parameters stored in the notebook metadata

resketch(name, raise_error=True)

Display output from a named source of the notebook.

Parameters:

• name (str) – name of sketched (snap) object
• raise_error (bool) – indicator for if the resketch should print a message or error on missing snaps

scrap_dataframe

pandas dataframe – dataframe of cell scraps

scraps

dict – a dictionary of data found in the notebook

snaps

dict – a dictionary of the notebook display outputs.

class scrapbook.models.Scrapbook

Bases: collections.abc.MutableMapping

A collection of notebooks represented as a dictionary of notebooks

display(snaps=None, keys=None, header=True, raise_error=False)

Display snaps as markdown structed outputs.

Parameters:

• snaps (str or iterable[str] (optional)) – the snaps to display as outputs
• keys (str or iterable[str] (optional)) – notebook keys to use in framing the scrapbook displays
• header (bool (default: True)) – indicator for if the snaps should have headers
• raise_error (bool (default: False)) – flag for if errors should be raised on missing output_names

flat_scraps

dict – a dictionary of the merged notebook scraps.

flat_snaps

dict – a dictionary of the merged notebook snap outputs.

notebooks

list – a sorted list of associated notebooks.

papermill_dataframe

list – a list of data names from a collection of notebooks

papermill_metrics

list – a list of metrics from a collection of notebooks

scraps

dict – a dictionary of the notebook scraps by key.

snaps

dict – a dictionary of the notebook snap outputs by key.

scrapbook.models.merge_dicts(dicts)

scrapbook.translators module

notebook.py

Provides the translators for various data types to be persistable

class scrapbook.translators.ArrowDataframeTranslator

Bases: object

load(scrap)

translate(scrap)

class scrapbook.translators.DataTranslatorRegistry

Bases: collections.abc.MutableMapping

deregister(storage_type)

Removes a particular translator from the registry

Parameters:storage_type (str) – Name of the mime subtype parsed by the translator.

load_data(storage_type, scrap)

Finds the register for the given storage_type and loads the scrap into a JSON or string object.

Parameters:

• storage_type (str) – Name of the mime subtype parsed by the translator.
• scrap (obj) – Object to be converted from JSON or string format to the original value.

register(storage_type, translator)

Registers a new storage_type to a particular translator

Parameters:

• storage_type (str) – Name of the mime subtype parsed by the translator.
• translator (obj) – The object which implements the required functions.

reset()

Resets the registry to have no translators.

translate_data(storage_type, scrap)

Finds the register for the given storage_type and translates the scrap into an object of the translator output type.

Parameters:

• storage_type (str) – Name of the mime subtype parsed by the translator.
• scrap (obj) – Object to be converted to JSON or string format for storage in an output

class scrapbook.translators.JsonTranslator

Bases: object

load(scrap)

translate(scrap)

class scrapbook.translators.UnicodeTranslator

Bases: object

load(scrap)

translate(scrap)

Module contents

Reference scrapbook.tests package