<p align="left">
<a href="https://badge.fury.io/py/enforce-notebook-run-order">
<img src="https://badge.fury.io/py/enforce-notebook-run-order@2x.png" alt="PyPI version" height="20">
</a>
<a href="https://codecov.io/gh/christopher-hacker/enforce-notebook-run-order" >
<img src="https://codecov.io/gh/christopher-hacker/enforce-notebook-run-order/branch/main/graph/badge.svg?token=019MXVQYN5"/>
</a>
<a href="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/test.yaml">
<img src="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/test.yaml/badge.svg" alt="Run tests">
</a>
<a href="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/auto-tag.yml">
<img src="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/auto-tag.yml/badge.svg" alt="Create a tag if version changed">
</a>
<a href="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/publish-pypi.yaml">
<img src="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/publish-pypi.yaml/badge.svg" alt="Publish to PyPi">
</a>
<a href="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/docs.yml">
<img src="https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/docs.yml/badge.svg" alt="Build docs">
</a>
</p>
enforce-notebook-run-order
==========================
Enforce the run order of Jupyter notebooks.
Jupyter notebooks are great for interactive data analysis. However, when
they can encourage a bad habit: running cells out of order. This can
lead to notebooks being committed to the repository in a state where
they don\'t run from top to bottom, and other collaborators may receive
different results when running the notebook from top to bottom.
`enforce-notebook-run-order` enforces the run order of a notebook by
raising an exception if any cells are run out of order.
Installation
------------
`enforce-notebook-run-order` can be installed via pip:
``` {.sourceCode .bash}
pip install enforce-notebook-run-order
```
It can also be set up as a [pre-commit hook](https://pre-commit.com/).
See the [pre-commit hook](#pre-commit-hook) section for more details.
Usage
-----
`enforce-notebook-run-order` can be used as a standalone script, or as a
[pre-commit hook](https://pre-commit.com/).
### Standalone
To use `enforce-notebook-run-order` as a standalone script, simply run
it with the path to the notebook(s) you want to check:
``` {.sourceCode .bash}
nbcheck my_notebook.ipynb my_other_notebook.ipynb
```
Or point it to a directory to check all notebooks in that directory:
``` {.sourceCode .bash}
nbcheck my_notebooks/
```
If no paths are specified, `nbcheck` will check all notebooks in the
current directory.
You can also use the full `enforce-notebook-run-order` command, but the
`nbcheck` command is provided as a convenience.
### pre-commit hook
To use `enforce_notebook_run_order` as a pre-commit hook, add the
following to your `.pre-commit-config.yaml`:
``` {.sourceCode .yaml}
repos:
- repo: https://github.com/christopher-hacker/enforce-notebook-run-order
rev: 1.4.1
hooks:
- id: enforce-notebook-run-order
```
### disabling output checks
By default, `enforce-notebook-run-order` will check that the output of
each cell matches the output of the previous run. This will catch cases
where a cell is run out of order, but the execution count is still
sequential. However, this can be problematic if the output of a cell
changes between runs, such as when using random numbers. It can also be
problematic if the notebook runs for a long time.
There are three ways to disable output checks:
1. Disabling running all notebooks using the `--no-run` flag:
``` {.sourceCode .bash}
nbcheck --no-run my_notebook.ipynb
```
2. Disabling running a single notebook using the `no-run` marker **in
the first cell of the notebook**:
> ``` {.sourceCode .python}
> # no-run
> print("This notebook will not be run")
> ```
3. Disabling output checks for a single cell using the
`no-check-output` marker:
> ``` {.sourceCode .python}
> # no-check-output
> print("This cell will be run, but its output will not be checked")
> ```
Raw data
{
"_id": null,
"home_page": null,
"name": "enforce-notebook-run-order",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Chris Hacker",
"author_email": "49451910+christopher-hacker@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/82/99/50be1d50ba8a819232396114e7e20dc03b5b1ce9efad2f033fe07d6ab12b/enforce_notebook_run_order-1.5.0.tar.gz",
"platform": null,
"description": "<p align=\"left\">\n <a href=\"https://badge.fury.io/py/enforce-notebook-run-order\">\n <img src=\"https://badge.fury.io/py/enforce-notebook-run-order@2x.png\" alt=\"PyPI version\" height=\"20\">\n </a>\n <a href=\"https://codecov.io/gh/christopher-hacker/enforce-notebook-run-order\" > \n <img src=\"https://codecov.io/gh/christopher-hacker/enforce-notebook-run-order/branch/main/graph/badge.svg?token=019MXVQYN5\"/> \n </a>\n <a href=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/test.yaml\">\n <img src=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/test.yaml/badge.svg\" alt=\"Run tests\">\n </a>\n <a href=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/auto-tag.yml\">\n <img src=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/auto-tag.yml/badge.svg\" alt=\"Create a tag if version changed\">\n </a>\n <a href=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/publish-pypi.yaml\">\n <img src=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/publish-pypi.yaml/badge.svg\" alt=\"Publish to PyPi\">\n </a>\n <a href=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/docs.yml\">\n <img src=\"https://github.com/christopher-hacker/enforce-notebook-run-order/actions/workflows/docs.yml/badge.svg\" alt=\"Build docs\">\n </a>\n</p>\n\nenforce-notebook-run-order\n==========================\n\nEnforce the run order of Jupyter notebooks.\n\nJupyter notebooks are great for interactive data analysis. However, when\nthey can encourage a bad habit: running cells out of order. This can\nlead to notebooks being committed to the repository in a state where\nthey don\\'t run from top to bottom, and other collaborators may receive\ndifferent results when running the notebook from top to bottom.\n\n`enforce-notebook-run-order` enforces the run order of a notebook by\nraising an exception if any cells are run out of order.\n\nInstallation\n------------\n\n`enforce-notebook-run-order` can be installed via pip:\n\n``` {.sourceCode .bash}\npip install enforce-notebook-run-order\n```\n\nIt can also be set up as a [pre-commit hook](https://pre-commit.com/).\nSee the [pre-commit hook](#pre-commit-hook) section for more details.\n\nUsage\n-----\n\n`enforce-notebook-run-order` can be used as a standalone script, or as a\n[pre-commit hook](https://pre-commit.com/).\n\n### Standalone\n\nTo use `enforce-notebook-run-order` as a standalone script, simply run\nit with the path to the notebook(s) you want to check:\n\n``` {.sourceCode .bash}\nnbcheck my_notebook.ipynb my_other_notebook.ipynb\n```\n\nOr point it to a directory to check all notebooks in that directory:\n\n``` {.sourceCode .bash}\nnbcheck my_notebooks/\n```\n\nIf no paths are specified, `nbcheck` will check all notebooks in the\ncurrent directory.\n\nYou can also use the full `enforce-notebook-run-order` command, but the\n`nbcheck` command is provided as a convenience.\n\n### pre-commit hook\n\nTo use `enforce_notebook_run_order` as a pre-commit hook, add the\nfollowing to your `.pre-commit-config.yaml`:\n\n``` {.sourceCode .yaml}\nrepos:\n- repo: https://github.com/christopher-hacker/enforce-notebook-run-order\n rev: 1.4.1\n hooks:\n - id: enforce-notebook-run-order\n```\n\n### disabling output checks\n\nBy default, `enforce-notebook-run-order` will check that the output of\neach cell matches the output of the previous run. This will catch cases\nwhere a cell is run out of order, but the execution count is still\nsequential. However, this can be problematic if the output of a cell\nchanges between runs, such as when using random numbers. It can also be\nproblematic if the notebook runs for a long time.\n\nThere are three ways to disable output checks:\n\n1. Disabling running all notebooks using the `--no-run` flag:\n\n ``` {.sourceCode .bash}\n nbcheck --no-run my_notebook.ipynb\n ```\n\n2. Disabling running a single notebook using the `no-run` marker **in\n the first cell of the notebook**:\n\n > ``` {.sourceCode .python}\n > # no-run\n > print(\"This notebook will not be run\")\n > ```\n\n3. Disabling output checks for a single cell using the\n `no-check-output` marker:\n\n > ``` {.sourceCode .python}\n > # no-check-output\n > print(\"This cell will be run, but its output will not be checked\")\n > ```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "1.5.0",
"project_urls": {
"homepage": "https://github.com/christopher-hacker/enforce-notebook-run-order"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8448ebec6069fcd906fd8df45ad42e9f6609eb805e9b9a9bec576d45bc4ad58",
"md5": "b18fcee55c8d648f8577ed0b5e977e01",
"sha256": "4bd62dbaf1f7972cb4a27f52abe46398a0d4067fe14dbb8de7f98537c8af9380"
},
"downloads": -1,
"filename": "enforce_notebook_run_order-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b18fcee55c8d648f8577ed0b5e977e01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 7866,
"upload_time": "2024-04-17T00:20:46",
"upload_time_iso_8601": "2024-04-17T00:20:46.614650Z",
"url": "https://files.pythonhosted.org/packages/f8/44/8ebec6069fcd906fd8df45ad42e9f6609eb805e9b9a9bec576d45bc4ad58/enforce_notebook_run_order-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "829950be1d50ba8a819232396114e7e20dc03b5b1ce9efad2f033fe07d6ab12b",
"md5": "c376db0f1051025e6ac079b1a82a1397",
"sha256": "16fb8ce55478ec4af4275958e6923756326729db352e7e2f2d9ebdc705afdeea"
},
"downloads": -1,
"filename": "enforce_notebook_run_order-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "c376db0f1051025e6ac079b1a82a1397",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 5871,
"upload_time": "2024-04-17T00:20:48",
"upload_time_iso_8601": "2024-04-17T00:20:48.115012Z",
"url": "https://files.pythonhosted.org/packages/82/99/50be1d50ba8a819232396114e7e20dc03b5b1ce9efad2f033fe07d6ab12b/enforce_notebook_run_order-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-17 00:20:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "christopher-hacker",
"github_project": "enforce-notebook-run-order",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "enforce-notebook-run-order"
}
JSON
