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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 4.190s · 556.1MB
glibcpy 3.10–3.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}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scrapbook'
The 'scrapbook' library is not installed in your current Python environment.
TypeError: glue() missing 1 required positional argument: 'data'
The `scrapbook.glue()` function was called without providing the mandatory `data` argument.
fiximport 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()`.
fixUse `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.
fixVerify 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]`).