Previous Next

scrapbook package

Submodules

scrapbook.api module

api.py

Provides the base API calls for scrapbook

scrapbook.api.glue(name, data, encoder=None, display=None)

Records a data value in the given notebook cell.

The recorded data value can be retrieved during later inspection of the output notebook.

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

This data is persisted by generating a display output with a special media type identifying the content storage encoder 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.
  • data (any) – The value to record. This must be an object for which an encoder’s encodable method returns True.
  • encoder (str (optional)) – The name of the handler to use in persisting data in the notebook.
  • display (any (optional)) – An indicator for persisting controlling displays for the named record.
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.encoders module

encoders.py

Provides the encoders for various data types to be persistable

class scrapbook.encoders.DataEncoderRegistry

Bases: collections.abc.MutableMapping

decode(scrap, **kwargs)

Finds the register for the given encoder and translates the scrap’s data from a string or JSON type to an object of the encoder output type.

Parameters:scrap (Scrap) – A partially filled in scrap with data that needs decoding
deregister(encoder)

Removes a particular encoder from the registry

Parameters:name (str) – Name of the mime subtype parsed by the encoder.
determine_encoder_name(data)

Determines the

encode(scrap, **kwargs)

Finds the register for the given encoder and translates the scrap’s data from an object of the encoder type to a JSON typed object.

Parameters:scrap (Scrap) – A partially filled in scrap with data that needs encoding
register(encoder)

Registers a new name to a particular encoder

Parameters:
  • name (str) – Name of the mime subtype parsed by the encoder.
  • encoder (obj) – The object which implements the required encoding functions.
reset()

Resets the registry to have no encoders.

class scrapbook.encoders.DisplayEncoder

Bases: object

ENCODER_NAME = 'display'
decode(scrap, **kwargs)
encodable(data)
encode(scrap, **kwargs)
name()
class scrapbook.encoders.JsonEncoder

Bases: object

ENCODER_NAME = 'json'
decode(scrap, **kwargs)
encodable(data)
encode(scrap, **kwargs)
name()
class scrapbook.encoders.PandasArrowDataframeEncoder

Bases: object

ENCODER_NAME = 'pandas'
decode(scrap, **kwargs)
encodable(data)
encode(scrap, **kwargs)
name()
class scrapbook.encoders.TextEncoder

Bases: object

ENCODER_NAME = 'text'
decode(scrap, **kwargs)
encodable(data)
encode(scrap, **kwargs)
name()

scrapbook.exceptions module

exception scrapbook.exceptions.ScrapbookDataException(message, data_errors=None)

Bases: scrapbook.exceptions.ScrapbookException

Raised when a data translation exception is encountered

exception scrapbook.exceptions.ScrapbookException

Bases: ValueError

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

exception scrapbook.exceptions.ScrapbookInvalidEncoder

Bases: scrapbook.exceptions.ScrapbookException

Raised when no encoder is found to tranforming data

exception scrapbook.exceptions.ScrapbookMissingEncoder

Bases: scrapbook.exceptions.ScrapbookException

Raised when no encoder is found to tranforming data

scrapbook.log module

scrapbook.models module

models.py

Provides the various model wrapper objects for scrapbook

class scrapbook.models.Notebook(node_or_path)

Bases: object

Representation of a notebook. This model is quasi-compatible with the nbformat NotebookNode object in that it support access to the v4 required fields from nbformat’s json schema. For complete access to normal nbformat operations, use the node attribute of this model.

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

a list of cell execution timings in cell order

Type:list
cells
copy()
directory

directory name found for a notebook (nb)

Type:str
execution_counts

a list of cell execution counts in cell order

Type:list
filename

filename found a the specified path

Type:str
metadata
metrics

dataframe of cell execution counts and times

Type:pandas dataframe
nbformat
nbformat_minor
papermill_dataframe

dataframe of notebook parameters and cell scraps

Type:pandas dataframe
papermill_metrics
papermill_record_dataframe

dataframe of cell scraps

Type:pandas dataframe
parameter_dataframe

dataframe of notebook parameters

Type:pandas dataframe
parameters

parameters stored in the notebook metadata

Type:dict
reglue(name, new_name=None, raise_on_missing=True, unattached=False)

Display output from a named source of the notebook.

Parameters:
  • name (str) – name of scrap object
  • new_name (str) – replacement name for scrap
  • raise_error (bool) – indicator for if the resketch should print a message or error on missing snaps
  • unattached (bool) – indicator for rendering without making the display recallable as scrapbook data
scrap_dataframe

dataframe of cell scraps

Type:pandas dataframe
scraps

a dictionary of data found in the notebook

Type:dict
class scrapbook.models.Scrapbook

Bases: collections.abc.MutableMapping

A collection of notebooks represented as a dictionary of notebooks

metrics

a list of metrics from a collection of notebooks

Type:list
notebook_scraps

a dictionary of the notebook scraps by key.

Type:dict
notebooks

a sorted list of associated notebooks.

Type:list
papermill_dataframe

a list of data names from a collection of notebooks

Type:list
papermill_metrics
scraps

a dictionary of the merged notebook scraps.

Type:dict
scraps_report(scrap_names=None, notebook_names=None, include_data=False, headers=True)

Display scraps as markdown structed outputs.

Parameters:
  • scrap_names (str or iterable[str] (optional)) – the scraps to display as reported outputs
  • notebook_names (str or iterable[str] (optional)) – notebook names to use in filtering on scraps to report
  • include_data (bool (default: False)) – indicator that data-only scraps should be reported
  • header (bool (default: True)) – indicator for if the scraps should render with a header
scrapbook.models.merge_dicts(dicts)

scrapbook.schemas module

schemas.py

Provides the json schema for various versions of scrapbook payloads

scrapbook.schemas.scrap_schema(version=1)

scrapbook.scraps module

scraps.py

Provides the Scrap and Scraps abstractions for housing data

class scrapbook.scraps.Scrap(name, data, encoder, display)

Bases: tuple

data

Alias for field number 1

display

Alias for field number 3

encoder

Alias for field number 2

name

Alias for field number 0

class scrapbook.scraps.Scraps(*args, **kwargs)

Bases: collections.OrderedDict

data_dict
data_scraps
dataframe

dataframe of cell scraps

Type:pandas dataframe
display_dict
display_scraps
scrapbook.scraps.payload_to_scrap(payload)

Translates data output format to a scrap

scrapbook.scraps.scrap_to_payload(scrap)

Translates scrap data to the output format

scrapbook.utils module

utils.py

Provides the utilities for scrapbook functions and operations.

scrapbook.utils.deprecated(version, replacement=None)

Warns the user that something is deprecated. Removal planned in version release.

scrapbook.utils.is_kernel()

Returns True if execution context is inside a kernel

scrapbook.utils.kernel_required(f)

scrapbook.version module

Module contents

scrapbook scrapbook.tests package