{"id":2276,"library":"scrapbook","title":"Scrapbook","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/nteract/scrapbook/","tags":["jupyter","notebook","nteract","data serialization","workflow","data sharing"],"install":[{"cmd":"pip install scrapbook","lang":"bash","label":"Base Installation"},{"cmd":"pip install scrapbook[all]","lang":"bash","label":"With All Optional I/O Dependencies (e.g., S3, Azure)"}],"dependencies":[{"reason":"Core dependency for notebook object structure and manipulation.","package":"nbformat"},{"reason":"Used for efficient serialization (e.g., Parquet for pandas DataFrames), optional but highly recommended for data-intensive use cases.","package":"pyarrow","optional":true},{"reason":"Abstract filesystem interface used by optional I/O dependencies for cloud storage.","package":"fsspec","optional":true},{"reason":"Enables S3 storage backend for notebooks (requires `scrapbook[s3]`).","package":"s3fs","optional":true}],"imports":[{"symbol":"scrapbook","correct":"import scrapbook as sb"},{"note":"Records data into the current notebook's cell output.","symbol":"glue","correct":"sb.glue('my_data', {'key': 'value'})"},{"note":"Reads a single notebook file and returns a Notebook object.","symbol":"read_notebook","correct":"notebook = sb.read_notebook('path/to/output.ipynb')"},{"note":"Reads multiple notebooks from a directory and returns a Scrapbook object.","symbol":"read_notebooks","correct":"scrapbook_collection = sb.read_notebooks('path/to/directory')"},{"note":"Represents a collection of Notebook objects.","symbol":"Scrapbook","correct":"from scrapbook.models import Scrapbook"}],"quickstart":{"code":"import scrapbook as sb\nimport os\n\n# --- Part 1: Write data to a dummy notebook (simulating execution) ---\n# This part would typically run inside a Jupyter/nteract notebook cell.\n# For demonstration, we'll create a dummy output file.\n\n# In a real notebook, you'd just call sb.glue directly.\n# Here, we simulate it by writing to a temporary file.\nnotebook_content_template = '''{\n \"cells\": [\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": 1,\n   \"metadata\": {},\n   \"outputs\": [\n    {\n     \"data\": {\n      \"application/scrapbook+json\": {\n       \"data\": {}, \n       \"encoder\": \"json\", \n       \"name\": \"my_string\", \n       \"display\": null\n      }\n     },\n     \"metadata\": {},\n     \"output_type\": \"display_data\"\n    }\n   ],\n   \"source\": [\"import scrapbook as sb\\n\", \"sb.glue('my_string', 'Hello Scrapbook!')\"]\n  },\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": 2,\n   \"metadata\": {},\n   \"outputs\": [\n    {\n     \"data\": {\n      \"application/scrapbook+json\": {\n       \"data\": 12345, \n       \"encoder\": \"json\", \n       \"name\": \"my_number\", \n       \"display\": null\n      }\n     },\n     \"metadata\": {},\n     \"output_type\": \"display_data\"\n    }\n   ],\n   \"source\": [\"sb.glue('my_number', 12345)\"]\n  }\n ],\n \"metadata\": {\n  \"kernelspec\": {\n   \"display_name\": \"Python 3\",\n   \"language\": \"python\",\n   \"name\": \"python3\"\n  },\n  \"language_info\": {\n   \"codemirror_mode\": {\n    \"name\": \"ipython\",\n    \"version\": 3\n   },\n   \"file_extension\": \".py\",\n   \"mimetype\": \"text/x-python\",\n   \"name\": \"python\",\n   \"nbconvert_exporter\": \"python\",\n   \"pygments_lexer\": \"ipython3\",\n   \"version\": \"3.9.7\"\n  }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 4\n}'''\n\n# Manually inject the data for the example since we're not running a live kernel\n# In a real scenario, these outputs would be generated by `sb.glue` calls\nimport json\nnb_dict = json.loads(notebook_content_template)\n# Update the 'my_string' scrap\nnb_dict['cells'][0]['outputs'][0]['data']['application/scrapbook+json']['data'] = 'Hello Scrapbook!'\n# Update the 'my_number' scrap\nnb_dict['cells'][1]['outputs'][0]['data']['application/scrapbook+json']['data'] = 12345\n\noutput_notebook_path = 'output_test_notebook.ipynb'\nwith open(output_notebook_path, 'w') as f:\n    json.dump(nb_dict, f, indent=4)\n\nprint(f\"Created dummy notebook: {output_notebook_path}\")\n\n# --- Part 2: Read data from the notebook --- \n# This part can run in a separate script or notebook.\n\n# Read the notebook containing the 'scraps'\nnb = sb.read_notebook(output_notebook_path)\n\n# Access a specific scrap by name\nmy_string_scrap = nb.scraps.my_string\nmy_number_scrap = nb.scraps.my_number\n\nprint(f\"\\nRetrieved string scrap: {my_string_scrap.data}\")\nprint(f\"Retrieved number scrap: {my_number_scrap.data}\")\n\n# You can also get all scraps as a dictionary\nall_scraps = nb.scraps.to_dict()\nprint(f\"\\nAll scraps: {all_scraps}\")\n\n# Clean up the dummy file\nos.remove(output_notebook_path)\nprint(f\"Cleaned up {output_notebook_path}\")\n","lang":"python","description":"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'."},"warnings":[{"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`.","message":"The `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`.","severity":"breaking","affected_versions":"<0.5.0"},{"fix":"Replace `papermill.record()` calls with `scrapbook.glue()`. Utilize `scrapbook.read_notebook()` for accessing recorded data, rather than `papermill`'s older retrieval methods.","message":"Scrapbook 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.","severity":"deprecated","affected_versions":"0.3.0+"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"0.4.0+"},{"fix":"Ensure your project runs on Python 3.6 or newer. Upgrade your Python environment if currently using an older version.","message":"Python 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.","severity":"breaking","affected_versions":"0.4.0+"},{"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.","message":"Calling `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.","severity":"gotcha","affected_versions":"0.3.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}