<div align="center">
[](https://badge.fury.io/py/pynblint)
[](https://github.com/collab-uniba/pynblint/actions/workflows/CI.yml)
[](https://pynblint.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/collab-uniba/pynblint)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
</div>
Many professional data scientists use Jupyter Notebook to accomplish their daily tasks, from preliminary data exploration to model prototyping. Notebooks' interactivity is particularly convenient for data-centric programming and their self-documenting nature provides excellent support for the communication of analytical results.
Nevertheless, Jupyter Notebook has been often criticized for inducing bad programming habits and scarcely supporting Software Engineering best practices. To really benefit from notebooks, users should be aware of their common pitfalls and learn how to prevent them.
In previous work (see ["Eliciting Best Practices for Collaboration with Computational Notebooks"](https://arxiv.org/abs/2202.07233) [\[1\]](#references)), we introduced a catalog of 17 empirically-validated guidelines for the collaborative use of notebooks in a professional context.
To foster the adoption of these best practices, we have created Pynblint, a static analysis tool for Jupyter notebooks written in Python. Pynblint reveals potential notebook defects and recommends corrective actions. It can be operated either as a standalone CLI application or as part of a CI/CD pipeline.
The core linting rules of Pynblint have been derived as operationalizations of the best practices from our catalog. Nonetheless, the plug-in architecture of Pynblint enables its users to easily extend the core set of checks with their own linting rules.
## Requirements
Python 3.7+.
## Installation
Pynblint can be installed with `pip` or another PyPI package manager:
```bash
pip install pynblint
```
After installation, we recommend exploring the command-line interface of the tool:
```bash
pynblint --help
```
<!-- To use Pynblint, clone this repository and install it with [Poetry](https://python-poetry.org):
```bash
poetry install --no-dev
```
To install Pynblint for development purposes, simply omit the `--no-dev` option:
```bash
poetry install
``` -->
## Usage
Pynblint can be used to analyze:
- a standalone notebook:
```bash
pynblint path/to/the/notebook.ipynb
```
- a code repository containing notebooks:
```bash
pynblint path/to/the/project/dir/
```
- (possibly also compressed as a `.zip` archive):
```bash
pynblint path/to/the/compressed/archive.zip
```
- a _public_ GitHub repository containing notebooks
(support for private repositories is on our roadmap 🙂):
```bash
pynblint --from-github https://github.com/collab-uniba/pynblint
```
For further information on the available options, please refer to the project [documentation](https://pynblint.readthedocs.io/en/latest/?badge=latest).
## Catalog of best practices
In the following, we report the catalog of empirically-validated best practices on which Pynblint is based [\[1\]](#references).
For each guideline, we specify the current state of implementation within Pynblint:
- :white_check_mark: = "implemented"
- :hourglass_flowing_sand: = "partially implemented / work in progress"
- :x: = "not on our roadmap"
| State | Best Practice from [\[1\]](#references) |
| ------------------------ | -------------------------------------------------------- |
| :white_check_mark: | Use version control |
| :white_check_mark: | Manage project dependencies |
| :hourglass_flowing_sand: | Use self-contained environments |
| :white_check_mark: | Put imports at the beginning |
| :white_check_mark: | Ensure re-executability (re-run notebooks top to bottom) |
| :hourglass_flowing_sand: | Modularize your code |
| :hourglass_flowing_sand: | Test your code |
| :white_check_mark: | Name your notebooks consistently |
| :hourglass_flowing_sand: | Stick to coding standards |
| :hourglass_flowing_sand: | Use relative paths |
| :white_check_mark: | Document your analysis |
| :white_check_mark: | Leverage Markdown headings to structure your notebook |
| :white_check_mark: | Keep your notebook clean |
| :white_check_mark: | Keep your notebook concise |
| :x: | Distinguish production and development artifacts |
| :hourglass_flowing_sand: | Make your notebooks available |
| :white_check_mark: | Make your data available |
## License
This project is licensed under the terms of the MIT license.
## References
[1] Luigi Quaranta, Fabio Calefato, and Filippo Lanubile. 2022. [Eliciting Best Practices for Collaboration with Computational Notebooks.](https://arxiv.org/abs/2202.07233) _Proc. ACM Hum.-Comput. Interact. 6_, CSCW1, Article 87 (April 2022), 41 pages. <https://doi.org/10.1145/3512934>
Raw data
{
"_id": null,
"home_page": "https://pynblint.readthedocs.io/en/latest/",
"name": "pynblint",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "Jupyter, notebook, lint, quality assurance, static analysis",
"author": "Luigi Quaranta",
"author_email": "luigi.quaranta@uniba.it",
"download_url": "https://files.pythonhosted.org/packages/9c/1d/85cb08bcb43446ec4c0237bb0718f705c91eae02ad3c729950db9afea20a/pynblint-0.1.6.tar.gz",
"platform": null,
"description": "\n\n<div align=\"center\">\n\n[](https://badge.fury.io/py/pynblint)\n\n\n[](https://github.com/collab-uniba/pynblint/actions/workflows/CI.yml)\n[](https://pynblint.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/collab-uniba/pynblint)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\n</div>\n\nMany professional data scientists use Jupyter Notebook to accomplish their daily tasks, from preliminary data exploration to model prototyping. Notebooks' interactivity is particularly convenient for data-centric programming and their self-documenting nature provides excellent support for the communication of analytical results.\n\nNevertheless, Jupyter Notebook has been often criticized for inducing bad programming habits and scarcely supporting Software Engineering best practices. To really benefit from notebooks, users should be aware of their common pitfalls and learn how to prevent them.\n\nIn previous work (see [\"Eliciting Best Practices for Collaboration with Computational Notebooks\"](https://arxiv.org/abs/2202.07233) [\\[1\\]](#references)), we introduced a catalog of 17 empirically-validated guidelines for the collaborative use of notebooks in a professional context.\n\nTo foster the adoption of these best practices, we have created Pynblint, a static analysis tool for Jupyter notebooks written in Python. Pynblint reveals potential notebook defects and recommends corrective actions. It can be operated either as a standalone CLI application or as part of a CI/CD pipeline.\n\n\n\nThe core linting rules of Pynblint have been derived as operationalizations of the best practices from our catalog. Nonetheless, the plug-in architecture of Pynblint enables its users to easily extend the core set of checks with their own linting rules.\n\n## Requirements\n\nPython 3.7+.\n\n## Installation\n\nPynblint can be installed with `pip` or another PyPI package manager:\n\n```bash\npip install pynblint\n```\n\nAfter installation, we recommend exploring the command-line interface of the tool:\n\n```bash\npynblint --help\n```\n\n<!-- To use Pynblint, clone this repository and install it with [Poetry](https://python-poetry.org):\n\n```bash\npoetry install --no-dev\n```\n\nTo install Pynblint for development purposes, simply omit the `--no-dev` option:\n\n```bash\npoetry install\n``` -->\n\n## Usage\n\nPynblint can be used to analyze:\n\n- a standalone notebook:\n\n ```bash\n pynblint path/to/the/notebook.ipynb\n ```\n\n- a code repository containing notebooks:\n\n ```bash\n pynblint path/to/the/project/dir/\n ```\n\n - (possibly also compressed as a `.zip` archive):\n\n ```bash\n pynblint path/to/the/compressed/archive.zip\n ```\n\n- a _public_ GitHub repository containing notebooks\n (support for private repositories is on our roadmap \ud83d\ude42):\n\n ```bash\n pynblint --from-github https://github.com/collab-uniba/pynblint\n ```\n\nFor further information on the available options, please refer to the project [documentation](https://pynblint.readthedocs.io/en/latest/?badge=latest).\n\n## Catalog of best practices\n\nIn the following, we report the catalog of empirically-validated best practices on which Pynblint is based [\\[1\\]](#references).\n\nFor each guideline, we specify the current state of implementation within Pynblint:\n\n- :white_check_mark: = \"implemented\"\n- :hourglass_flowing_sand: = \"partially implemented / work in progress\"\n- :x: = \"not on our roadmap\"\n\n| State | Best Practice from [\\[1\\]](#references) |\n| ------------------------ | -------------------------------------------------------- |\n| :white_check_mark: | Use version control |\n| :white_check_mark: | Manage project dependencies |\n| :hourglass_flowing_sand: | Use self-contained environments |\n| :white_check_mark: | Put imports at the beginning |\n| :white_check_mark: | Ensure re-executability (re-run notebooks top to bottom) |\n| :hourglass_flowing_sand: | Modularize your code |\n| :hourglass_flowing_sand: | Test your code |\n| :white_check_mark: | Name your notebooks consistently |\n| :hourglass_flowing_sand: | Stick to coding standards |\n| :hourglass_flowing_sand: | Use relative paths |\n| :white_check_mark: | Document your analysis |\n| :white_check_mark: | Leverage Markdown headings to structure your notebook |\n| :white_check_mark: | Keep your notebook clean |\n| :white_check_mark: | Keep your notebook concise |\n| :x: | Distinguish production and development artifacts |\n| :hourglass_flowing_sand: | Make your notebooks available |\n| :white_check_mark: | Make your data available |\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n## References\n\n[1] Luigi Quaranta, Fabio Calefato, and Filippo Lanubile. 2022. [Eliciting Best Practices for Collaboration with Computational Notebooks.](https://arxiv.org/abs/2202.07233) _Proc. ACM Hum.-Comput. Interact. 6_, CSCW1, Article 87 (April 2022), 41 pages. <https://doi.org/10.1145/3512934>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A linter for Jupyter notebooks written in Python.",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://pynblint.readthedocs.io/en/latest/",
"Repository": "https://github.com/collab-uniba/pynblint"
},
"split_keywords": [
"jupyter",
" notebook",
" lint",
" quality assurance",
" static analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86309bcd030408ae80e3a516da13834065d667798a622309fb891d50e77d30d6",
"md5": "774995888a600ccb8b6795cb453aa310",
"sha256": "8bb972696431144768ba6bf238a83f646c3faa4dac2810338ef87fb24d91742c"
},
"downloads": -1,
"filename": "pynblint-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "774995888a600ccb8b6795cb453aa310",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 24356,
"upload_time": "2024-08-12T08:53:20",
"upload_time_iso_8601": "2024-08-12T08:53:20.164728Z",
"url": "https://files.pythonhosted.org/packages/86/30/9bcd030408ae80e3a516da13834065d667798a622309fb891d50e77d30d6/pynblint-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c1d85cb08bcb43446ec4c0237bb0718f705c91eae02ad3c729950db9afea20a",
"md5": "72d70fbbf92e5405b4a5b096728177dd",
"sha256": "10853c0fc9bf84b85e9227c132f59f9af539771623a3aac99d0d6ababd45e601"
},
"downloads": -1,
"filename": "pynblint-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "72d70fbbf92e5405b4a5b096728177dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 21723,
"upload_time": "2024-08-12T08:53:21",
"upload_time_iso_8601": "2024-08-12T08:53:21.334932Z",
"url": "https://files.pythonhosted.org/packages/9c/1d/85cb08bcb43446ec4c0237bb0718f705c91eae02ad3c729950db9afea20a/pynblint-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 08:53:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "collab-uniba",
"github_project": "pynblint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pynblint"
}
JSON
