# jupyter-cache
[![Github-CI][github-ci]][github-link]
[![Coverage Status][codecov-badge]][codecov-link]
[![Documentation Status][rtd-badge]][rtd-link]
[![Code style: black][black-badge]][black-link]
[![PyPI][pypi-badge]][pypi-link]
A defined interface for working with a cache of jupyter notebooks.
## Why use jupyter-cache?
If you have a number of notebooks whose execution outputs you want to ensure are kept up to date, without having to re-execute them every time (particularly for long running code, or text-based formats that do not store the outputs).
The notebooks must have deterministic execution outputs:
- You use the same environment to run them (e.g. the same installed packages)
- They run no non-deterministic code (e.g. random numbers)
- They do not depend on external resources (e.g. files or network connections) that change over time
For example, it is utilised by [jupyter-book](https://jupyterbook.org/content/execute.html#caching-the-notebook-execution), to allow for fast document re-builds.
## Install
```bash
pip install jupyter-cache
```
For development:
```bash
git clone https://github.com/executablebooks/jupyter-cache
cd jupyter-cache
git checkout develop
pip install -e .[cli,code_style,testing]
```
See the documentation for usage.
## Development
Some desired requirements (not yet all implemented):
- Persistent
- Separates out "edits to content" from "edits to code cells". Cell
rearranges and code cell changes should require a re-execution. Content changes should not.
- Allow parallel access to notebooks (for execution)
- Store execution statistics/reports
- Store external assets: Notebooks being executed often require external assets: importing scripts/data/etc. These are prepared by the users.
- Store execution artefacts: created during execution
- A transparent and robust cache invalidation: imagine the user updating an external dependency or a Python module, or checking out a different git branch.
## Contributing
jupyter-cache follows the [Executable Book Contribution Guide](https://executablebooks.org/en/latest/contributing.html). We'd love your help!
### Code Style
Code style is tested using [flake8](http://flake8.pycqa.org),
with the configuration set in `.flake8`,
and code formatted with [black](https://github.com/ambv/black).
Installing with `jupyter-cache[code_style]` makes the [pre-commit](https://pre-commit.com/)
package available, which will ensure this style is met before commits are submitted, by reformatting the code
and testing for lint errors.
It can be setup by:
```shell
>> cd jupyter-cache
>> pre-commit install
```
Optionally you can run `black` and `flake8` separately:
```shell
>> black .
>> flake8 .
```
Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
[github-ci]: https://github.com/executablebooks/jupyter-cache/workflows/continuous-integration/badge.svg?branch=master
[github-link]: https://github.com/executablebooks/jupyter-cache
[codecov-badge]: https://codecov.io/gh/executablebooks/jupyter-cache/branch/master/graph/badge.svg
[codecov-link]: https://codecov.io/gh/executablebooks/jupyter-cache
[rtd-badge]: https://readthedocs.org/projects/jupyter-cache/badge/?version=latest
[rtd-link]: https://jupyter-cache.readthedocs.io/en/latest/?badge=latest
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[pypi-badge]: https://img.shields.io/pypi/v/jupyter-cache.svg
[pypi-link]: https://pypi.org/project/jupyter-cache
[black-link]: https://github.com/ambv/black
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyter-cache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "sphinx extension material design web components",
"author": null,
"author_email": "Chris Sewell <chrisj_sewell@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/f7/3627358075f183956e8c4974603232b03afd4ddc7baf72c2bc9fff522291/jupyter_cache-1.0.1.tar.gz",
"platform": null,
"description": "# jupyter-cache\n\n[![Github-CI][github-ci]][github-link]\n[![Coverage Status][codecov-badge]][codecov-link]\n[![Documentation Status][rtd-badge]][rtd-link]\n[![Code style: black][black-badge]][black-link]\n[![PyPI][pypi-badge]][pypi-link]\n\nA defined interface for working with a cache of jupyter notebooks.\n\n## Why use jupyter-cache?\n\nIf you have a number of notebooks whose execution outputs you want to ensure are kept up to date, without having to re-execute them every time (particularly for long running code, or text-based formats that do not store the outputs).\n\nThe notebooks must have deterministic execution outputs:\n\n- You use the same environment to run them (e.g. the same installed packages)\n- They run no non-deterministic code (e.g. random numbers)\n- They do not depend on external resources (e.g. files or network connections) that change over time\n\nFor example, it is utilised by [jupyter-book](https://jupyterbook.org/content/execute.html#caching-the-notebook-execution), to allow for fast document re-builds.\n\n## Install\n\n```bash\npip install jupyter-cache\n```\n\nFor development:\n\n```bash\ngit clone https://github.com/executablebooks/jupyter-cache\ncd jupyter-cache\ngit checkout develop\npip install -e .[cli,code_style,testing]\n```\n\nSee the documentation for usage.\n\n## Development\n\nSome desired requirements (not yet all implemented):\n\n- Persistent\n- Separates out \"edits to content\" from \"edits to code cells\". Cell\n rearranges and code cell changes should require a re-execution. Content changes should not.\n- Allow parallel access to notebooks (for execution)\n- Store execution statistics/reports\n- Store external assets: Notebooks being executed often require external assets: importing scripts/data/etc. These are prepared by the users.\n- Store execution artefacts: created during execution\n- A transparent and robust cache invalidation: imagine the user updating an external dependency or a Python module, or checking out a different git branch.\n\n## Contributing\n\njupyter-cache follows the [Executable Book Contribution Guide](https://executablebooks.org/en/latest/contributing.html). We'd love your help!\n\n### Code Style\n\nCode style is tested using [flake8](http://flake8.pycqa.org),\nwith the configuration set in `.flake8`,\nand code formatted with [black](https://github.com/ambv/black).\n\nInstalling with `jupyter-cache[code_style]` makes the [pre-commit](https://pre-commit.com/)\npackage available, which will ensure this style is met before commits are submitted, by reformatting the code\nand testing for lint errors.\nIt can be setup by:\n\n```shell\n>> cd jupyter-cache\n>> pre-commit install\n```\n\nOptionally you can run `black` and `flake8` separately:\n\n```shell\n>> black .\n>> flake8 .\n```\n\nEditors like VS Code also have automatic code reformat utilities, which can adhere to this standard.\n\n[github-ci]: https://github.com/executablebooks/jupyter-cache/workflows/continuous-integration/badge.svg?branch=master\n[github-link]: https://github.com/executablebooks/jupyter-cache\n[codecov-badge]: https://codecov.io/gh/executablebooks/jupyter-cache/branch/master/graph/badge.svg\n[codecov-link]: https://codecov.io/gh/executablebooks/jupyter-cache\n[rtd-badge]: https://readthedocs.org/projects/jupyter-cache/badge/?version=latest\n[rtd-link]: https://jupyter-cache.readthedocs.io/en/latest/?badge=latest\n[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg\n[pypi-badge]: https://img.shields.io/pypi/v/jupyter-cache.svg\n[pypi-link]: https://pypi.org/project/jupyter-cache\n[black-link]: https://github.com/ambv/black\n",
"bugtrack_url": null,
"license": null,
"summary": "A defined interface for working with a cache of jupyter notebooks.",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://jupyter-cache.readthedocs.io",
"Homepage": "https://github.com/executablebooks/jupyter-cache"
},
"split_keywords": [
"sphinx",
"extension",
"material",
"design",
"web",
"components"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "646b67b87da9d36bff9df7d0efbd1a325fa372a43be7158effaf43ed7b22341d",
"md5": "881db71b0410814059e91621c2cf7cc2",
"sha256": "9c3cafd825ba7da8b5830485343091143dff903e4d8c69db9349b728b140abf6"
},
"downloads": -1,
"filename": "jupyter_cache-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "881db71b0410814059e91621c2cf7cc2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 33907,
"upload_time": "2024-11-15T16:03:54",
"upload_time_iso_8601": "2024-11-15T16:03:54.021085Z",
"url": "https://files.pythonhosted.org/packages/64/6b/67b87da9d36bff9df7d0efbd1a325fa372a43be7158effaf43ed7b22341d/jupyter_cache-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bbf73627358075f183956e8c4974603232b03afd4ddc7baf72c2bc9fff522291",
"md5": "bab5a2086a85ea3a386115eab5ad6f3a",
"sha256": "16e808eb19e3fb67a223db906e131ea6e01f03aa27f49a7214ce6a5fec186fb9"
},
"downloads": -1,
"filename": "jupyter_cache-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "bab5a2086a85ea3a386115eab5ad6f3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32048,
"upload_time": "2024-11-15T16:03:55",
"upload_time_iso_8601": "2024-11-15T16:03:55.322534Z",
"url": "https://files.pythonhosted.org/packages/bb/f7/3627358075f183956e8c4974603232b03afd4ddc7baf72c2bc9fff522291/jupyter_cache-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 16:03:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "executablebooks",
"github_project": "jupyter-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jupyter-cache"
}
JSON
