Registry / data / jupyter-cache

jupyter-cache

JSON →
library1.0.1pypypi✓ verified 22d ago

Jupyter Cache provides a defined interface for working with a cache of Jupyter notebooks. It enables execution and caching of notebooks, intelligently re-executing them only when code cells or related metadata have changed, rather than for every minor edit. The library offers both a Command-Line Interface (CLI) and a Python API for managing project notebooks, executing them, and retrieving detailed execution reports including timing statistics and exception tracebacks. It is utilized by projects like Jupyter Book to accelerate document builds by preventing unnecessary re-execution of unchanged notebook content. The current version is 1.0.1, with a release cadence driven by feature enhancements and dependency updates.

pip install jupyter-cache
INSTALL
IMPORT
SIG · JUPYTER-CACHE
J
jupyter-cache
datapythonv1.0.1
Install
6.1s avg
Import
Disk
63MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 65.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.1s · import 0.000s · 60MB
63MB installed
● package 63MB
Code
Verified usage

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

get_cache
from jupyter_cache import get_cache
Primary function to initialize the cache.
CacheBundleIn
from jupyter_cache.base import CacheBundleIn
Used for advanced caching operations.
load_executor
from jupyter_cache.executors import load_executor
Used to load different notebook execution strategies.

This quickstart demonstrates how to programmatically initialize a Jupyter Cache, add a notebook to a project, execute it using a local serial executor, and retrieve the executed notebook with its outputs. It first creates a dummy notebook file, then uses the `jupyter_cache` API to manage its lifecycle within the cache.

import os import pathlib import nbformat as nbf from jupyter_cache import get_cache # Define cache path (can be set via JUPYTERCACHE env var too) cache_path = pathlib.Path('./.my_notebook_cache') # Create a dummy notebook file nb_content = nbf.v4.new_notebook() nb_content.cells.append(nbf.v4.new_code_cell("a = 1\nb = 2\nprint(a + b)")) notebook_path = pathlib.Path('./example.ipynb') with open(notebook_path, 'w', encoding='utf8') as f: nbf.write(nb_content, f) try: # Initialize the cache cache = get_cache(cache_path) print(f"Cache initialized at: {cache.path}") # Clear cache for a clean start (optional) cache.clear_cache() # Add the notebook to the project # Note: 'notebook' is the current API, 'stage' was used in older versions cache.add_notebook_to_project(notebook_path) print(f"Notebook '{notebook_path.name}' added to project.") # Execute the notebooks in the project # 'local-serial' is one of the default executors cache.execute_project_notebooks(executor_name='local-serial') print("Notebooks executed.") # List project records to see status print("\nProject Records:") for record in cache.list_project_records(): print(f" ID: {record.pk}, URI: {record.uri}, Status: {record.status}") # Retrieve a merged notebook with outputs record_pk = cache.list_project_records()[0].pk merged_nb = cache.get_executed_notebook(record_pk) print(f"\nRetrieved executed notebook for PK {record_pk}, cells: {len(merged_nb.cells)}") # Clean up the generated notebook file notebook_path.unlink(missing_ok=True) # The cache directory can be cleared or deleted manually if needed # cache.clear_cache() except Exception as e: print(f"An error occurred: {e}") finally: # Clean up the dummy notebook file if an error occurred before unlinking notebook_path.unlink(missing_ok=True) # Consider adding cache_path.rmdir() or shutil.rmtree(cache_path) for full cleanup in tests # but be careful with production environments.
jcache --version
Debug
Known issues
breakingPython 3.7 support was dropped in v0.6.0. Projects using Python 3.7 must upgrade their Python version before updating to jupyter-cache v0.6.0 or later.
fix
Upgrade Python to 3.8 or newer. The current minimum required Python version is >=3.9.
affects: >=0.6.0
breakingA significant API/CLI re-write occurred in v0.5.0. Commands and Python API calls related to 'staging' notebooks were rephrased to 'notebook' or 'project'. For instance, 'stage add' became 'notebook add', and the Python API methods changed accordingly.
fix
Consult the official documentation for the updated CLI commands and Python API methods, specifically looking for 'notebook' and 'project' related functions instead of 'stage' or 'staging'.
affects: >=0.5.0
gotchaFor jupyter-cache to be effective, notebooks must exhibit deterministic execution outputs. This means they should run in a consistent environment, avoid non-deterministic code (e.g., random number generation without seeding), and not rely on external, changing resources.
fix
Ensure that your notebook's execution environment is stable, all dependencies are pinned, and any non-deterministic operations are controlled (e.g., seeding random number generators). Avoid external dependencies that might change between executions without explicit cache invalidation.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jupyter_cache'
The `jupyter-cache` library is not installed in the Python environment where Jupyter Notebook or your script is being run, or the environment's Python path does not include the library.
fix
Ensure the library is installed using `pip install jupyter-cache` or `conda install jupyter-cache`. If using a Jupyter Notebook, confirm the kernel is using the correct Python environment where `jupyter-cache` is installed.
jcache: command not found
The `jcache` command-line interface (CLI) entry point for `jupyter-cache` is not in your system's PATH, or the installation was incomplete/corrupted.
fix
Verify that `jupyter-cache` is installed correctly. This error often occurs if `pip install jupyter-cache` was run in an environment not activated in the current terminal, or if the `scripts` directory for your Python installation is not included in your system's PATH environment variable.
ipynb Validity Error: Expected cell 0 to have execution_count 1 not None
This error occurs when `jupyter-cache` attempts to validate a notebook but finds that a cell's `execution_count` metadata is not as expected (e.g., `None`), suggesting the notebook may not have been fully or correctly executed before caching.
fix
Manually execute the notebook completely to ensure all cells have an `execution_count`. Alternatively, when using the `jcache` CLI, you can use the option to skip validity checks (e.g., by answering 'y' to 'continue caching?' or checking for a `--force` or `--skip-validation` option if available).
Error when accessing the jupyter cache
The `jupyter-cache` system is failing to correctly locate or interact with its cache, potentially due to an incorrect cache path, permission issues, or internal inconsistencies, leading to unnecessary re-execution of notebooks.
fix
Check the configured cache path (default is `.jupyter_cache` in the project root) and ensure proper read/write permissions. You can specify the cache path with the `--cache-path` option or `JUPYTERCACHE` environment variable. If issues persist, consider clearing the cache with `jcache project clear` and re-adding/re-executing notebooks.
Upgrade
Version history
1.0.1latest on PyPI · released Nov 15, 2024
Audit
Dependencies
nbclientrequiredCore dependency for notebook execution, frequently updated.
SQLAlchemyrequiredUsed for database operations to manage the cache; compatibility fixes have been released.
nbformatrequiredUsed for working with notebook files programmatically.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources