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, path_filter=None)

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

Parameters

  • path (str) – Path to directory containing notebook .ipynb files.

  • path_filter (Optional[Callable[str, bool]]) – Func used to filter the notebook by its filename: should return True if you want to read that notebook and False otherwise

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

property cell_timing

a list of cell execution timings in cell order

Type

list

property cells
copy()
property directory

directory name found for a notebook (nb)

Type

str

property execution_counts

a list of cell execution counts in cell order

Type

list

property filename

filename found a the specified path

Type

str

property metadata
property metrics

dataframe of cell execution counts and times

Type

pandas dataframe

property nbformat
property nbformat_minor
property papermill_dataframe

dataframe of notebook parameters and cell scraps

Type

pandas dataframe

property papermill_metrics
property papermill_record_dataframe

dataframe of cell scraps

Type

pandas dataframe

property parameter_dataframe

dataframe of notebook parameters

Type

pandas dataframe

property 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

property scrap_dataframe

dataframe of cell scraps

Type

pandas dataframe

property 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

property metrics

a list of metrics from a collection of notebooks

Type

list

property notebook_scraps

a dictionary of the notebook scraps by key.

Type

dict

property notebooks

a sorted list of associated notebooks.

Type

list

property papermill_dataframe

a list of data names from a collection of notebooks

Type

list

property papermill_metrics
property 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

property data_dict
property data_scraps
property dataframe

dataframe of cell scraps

Type

pandas dataframe

property display_dict
property 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