Registry / data / scrapbook

scrapbook

JSON →
library0.5.0pypypi✓ verified 24d ago

Scrapbook is a Python library for recording and reading data in Jupyter and nteract Notebooks. It allows users to persist data values and generated visual content (referred to as 'scraps') directly within the notebook file's output. These recorded scraps can then be recalled, read, or summarized programmatically for later use or for building robust notebook workflows. It aims to replace existing record functionality in libraries like Papermill. The library is actively maintained by the nteract team.

pip install scrapbook
INSTALL
IMPORT
SIG · SCRAPBOOK
S
scrapbook
datapythonv0.5.0
Install
22.1s avg
Import
3882ms
Disk
534MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 4.190s · 556.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 22.1s · import 3.573s · 519MB
534MB installed
● package 534MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

scrapbook
import scrapbook as sb
glue
sb.glue('my_data', {'key': 'value'})
Records data into the current notebook's cell output.
read_notebook
notebook = sb.read_notebook('path/to/output.ipynb')
Reads a single notebook file and returns a Notebook object.
read_notebooks
scrapbook_collection = sb.read_notebooks('path/to/directory')
Reads multiple notebooks from a directory and returns a Scrapbook object.
Scrapbook
from scrapbook.models import Scrapbook
Represents a collection of Notebook objects.

This quickstart demonstrates how to 'glue' (record) data into a notebook's output and then 'read' it back. The `sb.glue()` function is used within a notebook cell to store data. Subsequently, `sb.read_notebook()` can be used to load the notebook and access the stored 'scraps' by name. For demonstration purposes outside a live kernel, the example simulates the creation of an output notebook file containing 'scraps'.

import scrapbook as sb import os # --- Part 1: Write data to a dummy notebook (simulating execution) --- # This part would typically run inside a Jupyter/nteract notebook cell. # For demonstration, we'll create a dummy output file. # In a real notebook, you'd just call sb.glue directly. # Here, we simulate it by writing to a temporary file. notebook_content_template = '''{ "cells": [ { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "application/scrapbook+json": { "data": {}, "encoder": "json", "name": "my_string", "display": null } }, "metadata": {}, "output_type": "display_data" } ], "source": ["import scrapbook as sb\n", "sb.glue('my_string', 'Hello Scrapbook!')"] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "application/scrapbook+json": { "data": 12345, "encoder": "json", "name": "my_number", "display": null } }, "metadata": {}, "output_type": "display_data" } ], "source": ["sb.glue('my_number', 12345)"] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.7" } }, "nbformat": 4, "nbformat_minor": 4 }''' # Manually inject the data for the example since we're not running a live kernel # In a real scenario, these outputs would be generated by `sb.glue` calls import json nb_dict = json.loads(notebook_content_template) # Update the 'my_string' scrap nb_dict['cells'][0]['outputs'][0]['data']['application/scrapbook+json']['data'] = 'Hello Scrapbook!' # Update the 'my_number' scrap nb_dict['cells'][1]['outputs'][0]['data']['application/scrapbook+json']['data'] = 12345 output_notebook_path = 'output_test_notebook.ipynb' with open(output_notebook_path, 'w') as f: json.dump(nb_dict, f, indent=4) print(f"Created dummy notebook: {output_notebook_path}") # --- Part 2: Read data from the notebook --- # This part can run in a separate script or notebook. # Read the notebook containing the 'scraps' nb = sb.read_notebook(output_notebook_path) # Access a specific scrap by name my_string_scrap = nb.scraps.my_string my_number_scrap = nb.scraps.my_number print(f"\nRetrieved string scrap: {my_string_scrap.data}") print(f"Retrieved number scrap: {my_number_scrap.data}") # You can also get all scraps as a dictionary all_scraps = nb.scraps.to_dict() print(f"\nAll scraps: {all_scraps}") # Clean up the dummy file os.remove(output_notebook_path) print(f"Cleaned up {output_notebook_path}")
Debug
Known issues
breakingThe `scrapbook` package on PyPI was formerly published under the name `nteract-scrapbook`. With version 0.5.0, the package name changed to `scrapbook`. If you were installing `nteract-scrapbook`, you need to update your dependency to `scrapbook`.
fix
Update your `requirements.txt` or `setup.py` to use `scrapbook` instead of `nteract-scrapbook`. For older versions (e.g., 0.2.0), you must explicitly install `nteract-scrapbook==0.2.0`.
affects: <0.5.0
deprecatedScrapbook replaces `papermill`'s direct record functionality. While some backward compatibility exists (e.g., `nb.papermill_dataframe`), it is recommended to transition to Scrapbook's `glue` and `read_notebook` API for recording and retrieving data.
fix
Replace `papermill.record()` calls with `scrapbook.glue()`. Utilize `scrapbook.read_notebook()` for accessing recorded data, rather than `papermill`'s older retrieval methods.
affects: 0.3.0+
gotchaWhen using `sb.glue()` to store pandas DataFrames, `scrapbook` leverages `pyarrow` to convert the DataFrame to a base64 encoded Parquet file. This process can fail if the DataFrame contains certain complex nested objects (e.g., columns with dictionaries or sets directly within them), raising an `Arrow` exception.
fix
Ensure that pandas DataFrames intended for `sb.glue()` do not contain deeply nested, non-serializable objects like dicts or sets as direct column values. Flatten complex structures or convert them to more basic types if possible before gluing.
affects: 0.4.0+
breakingPython 2.7 support was officially dropped after 2020. Versions 0.4.0 and newer are Python 3 (3.5+) only. The documentation states Python 3.6+ is supported.
fix
Ensure your project runs on Python 3.6 or newer. Upgrade your Python environment if currently using an older version.
affects: 0.4.0+
gotchaCalling `sb.glue()` outside of an active Jupyter/nteract kernel context (e.g., in a plain Python script) may not correctly persist the data or could raise warnings. `scrapbook` relies on the kernel's display machinery to store 'scraps' in the notebook's output.
fix
Only use `sb.glue()` within a Jupyter or nteract notebook environment during execution. For external data storage outside a notebook, use standard file I/O or other serialization libraries.
affects: 0.3.0+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scrapbook'
The 'scrapbook' library is not installed in your current Python environment.
fix
pip install scrapbook
TypeError: glue() missing 1 required positional argument: 'data'
The `scrapbook.glue()` function was called without providing the mandatory `data` argument.
fix
import scrapbook as sb
my_variable = 'Hello Scrapbook'
sb.glue('my_key', my_variable)
AttributeError: 'Notebook' object has no attribute 'glue'
The `glue` function is used for recording data within the currently executing notebook, and is not a method available on a `scrapbook.Notebook` object returned by `scrapbook.read_notebook()`.
fix
Use `scrapbook.glue(key, data)` directly in a notebook cell to record data. If you've loaded a notebook with `nb = scrapbook.read_notebook(...)`, access recorded data via `nb.scraps['key'].data`.
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/non_existent_notebook.ipynb'
The path provided to `scrapbook.read_notebook()` does not point to an existing notebook file.
fix
Verify that the notebook file exists at the specified path and that the path is correct (relative or absolute).
Upgrade
Version history
0.5.0latest on PyPI · released Jan 6, 2021
Audit
Dependencies
nbformatrequiredCore dependency for notebook object structure and manipulation.
pyarrowoptionalUsed for efficient serialization (e.g., Parquet for pandas DataFrames), optional but highly recommended for data-intensive use cases.
fsspecoptionalAbstract filesystem interface used by optional I/O dependencies for cloud storage.
s3fsoptionalEnables S3 storage backend for notebooks (requires `scrapbook[s3]`).
Agent activity
10 hits · last 30 days
node
6
Amazon
1
OpenAI (training)
1
Resources