Models¶
A few new names for information are introduced in scrapbook:
- scraps: serializable data values and visualizations such as strings, lists of objects, pandas dataframes, charts, images, or data references.
- notebook: a wrapped nbformat notebook object with extra methods for interacting with scraps.
- scrapbook: a collection of notebooks with an interface for asking questions of the collection.
- encoders: a registered translator of data to/from notebook storage formats.
Scrap¶
The scrap model houses a few key attributes in a tuple. Namely:
- name: The name of the scrap
- data: Any data captured by the scrapbook api call
- encoder: The name of the encoder used to encode/decode data to/from the notebook
- display: Any display data used by IPython to display visual content
Notebook¶
The Notebook object adheres to the nbformat’s json schema, allowing for access to its required fields.
nb = sb.read_notebook('notebook.ipynb')
nb.cells # The cells from the notebook
nb.metadata
nb.nbformat
nb.nbformat_minor
There’s a few additional methods provided, outlined in the API page (read_notebook API)
Scrapbook¶
A collection of Notebooks is called a Scrapbook. It allows for access the underlying notebooks and to perform data collection from the group as a whole.
# create a scrapbook named `book`
book = sb.read_notebooks('path/to/notebook/collection/')
# get the underlying notebooks as a list
book.notebooks # Or `book.values`
There’s a additional methods provided, outlined in the API page (read_notebooks API)
Encoder¶
Encoders are accessible by key names to Encoder objects registered
against the encoders.registry object. To register new data encoders
simply call:
from scrapbook.encoders import registry as encoder_registry
# add encoder to the registry
encoder_registry.register("custom_encoder_name", MyCustomEncoder())
The encode class must implement two methods, encode and decode:
class MyCustomEncoder(object):
def encode(self, scrap):
# scrap.data is any type, usually specific to the encoder name
pass # Return a `Scrap` with `data` type one of [None, list, dict, *six.integer_types, *six.string_types]
def decode(self, scrap):
# scrap.data is one of [None, list, dict, *six.integer_types, *six.string_types]
pass # Return a `Scrap` with `data` type as any type, usually specific to the encoder name
This can read transform scraps into a json object representing their contents or location and load those strings back into the original data objects.
For example, here is the code for a custom encoder that can save Altair charts by converting the chart to a dictionary as a part of the encoding process.
from scrapbook.encoders import registry as encoder_registry
import altair as alt
class AltairEncoder(object):
def encode(self, scrap):
# Here we assume the input to `sb.glue` is an Altair chart.
scrap = scrap._replace(data=scrap.data.to_dict())
return scrap
def decode(self, scrap):
scrap = scrap._replace(data=alt.Chart.from_dict(scrap.data))
return scrap
# Register the encoder so that scrapbook can use it
encoder_registry.register("altair", AltairEncoder())
# Now we can use this encoder with `glue`
sb.glue('my_altair_chart', chart, 'altair')
text¶
A basic string storage format that saves data as python strings.
sb.glue("hello", "world", "text")
json¶
sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")
arrow¶
Implementation Pending!
