| Name | jupyter-black JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | A simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code automatically using Black. Fork of dnanhkhoa/nb_black. |
| upload_time | 2024-08-30 20:01:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT |
| keywords |
jupyter-black
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# jupyter-black
master: [](https://github.com/n8henrie/jupyter-black/actions/workflows/python-package.yml)
dev: [](https://github.com/n8henrie/jupyter-black/actions/workflows/python-package.yml)
A simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code
automatically using Black. Fork of
[dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black) with a few minor
modifications:
## Features
Once loaded, automatically format syntactically correct `jupyter` cells with
`black` once they are run.
Enhancements compared to [dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black):
- Configurability:
- Try to read black config from `pyproject.toml` if available
- Override settings such as line length and `black.TargetVersion` if
desired
- Uses `black.format_cell` to greatly simplify the codebase
- Adds tests
- Slightly more responsive (no longer requires `setTimeout` and a delay)
- Free software: MIT
## Introduction
[`black`][black] is an extremely popular python formatter. [Jupyter][jupyter] is an
awesome way to run python. This extension helps you automatically `black`en
your `jupyter`.
## Dependencies
- Python >= 3.7
- See `setup.cfg`
## Quickstart
```
python3 -m venv .venv && source ./.venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install jupyter-black jupyter
python3 -m jupyter notebook
```
From here, there are two ways to load the extension:
### Configurable (recommended):
```python
import jupyter_black
jupyter_black.load()
```
To look at configuration options:
```python
jupyter_black.load??
```
For example:
```python
import black
import jupyter_black
jupyter_black.load(
lab=False,
line_length=79,
verbosity="DEBUG",
target_version=black.TargetVersion.PY310,
)
```
### The other way:
```python
%load_ext jupyter_black
```
This will load the extension using your defaults from `pyproject.toml` if
available, or use the `black` defaults. Please note that this defaults to
`lab=True`, since moving to lab instead of standalone notebook installations
seems to be the direction of the jupyter project; this means this method of
loading will only work in JupyterLab, not in a standard notebook. For now,
users running a standalone notebook (instead of lab) need to use the
recommended (configurable) loading approach above.
### Development Setup
1. Clone the repo: `git clone https://github.com/n8henrie/jupyter-black && cd
jupyter-black`
2. Make a virtualenv: `python3 -m venv .venv`
3. Activate venv, update pip, and install editable test/dev version:
```console
$ source ./.venv/bin/activate
$ ./.venv/bin/python -m pip install --upgrade pip
$ ./.venv/bin/python -m pip install -e .[test,dev]
```
Notes:
- Tests use [playwright][playwright]
- You'll need to run this command (once) prior to running the tests:
- `python -m playwright install --with-deps firefox`
- `tox` will automatically run these installation steps (helpful for CI)
- If desired, pass the `--no-headless` flag to `pytest` for local debugging
## TODO
Contribution ideas:
- [ ] More tests, currently very basic
- Ensure config is overridden in unsurprising ways
- Ensure other config options are properly passed to `black`
- Ensure that `pyproject.toml` is searched for properly
- [x] Write tests for jupyter lab, currently only tested for notebook
- [x] I think the fixture could easily be modularized to also work for `lab`,
but haven't done the work yet
## Contributing
Please see `CONTRIBUTING.md` and `TODO`.
## Troubleshooting / FAQ
- How can I install an older / specific version of [jupyter black](jupyter-black)?
- Install from a tag:
- pip install git+git://github.com/n8henrie/jupyter-black.git@v0.1.0
- Install from a specific commit:
- pip install git+git://github.com/n8henrie/jupyter-black.git@aabc123def456ghi789
[black]: https://github.com/psf/black
[jupyter]: https://jupyter.org/
[playwright]: https://playwright.dev/python/
## Acknowledgements
Many thanks to [dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black) for
the original version!
And of course many thanks to the [black][black] and [jupyter][jupyter] teams.
Also, after establishing the repo and reserving the name on PyPI, I noticed
there is another library of the same name:
[drillan/jupyter-black](https://github.com/drillan/jupyter-black). It looks
like there have been no commits in the last 2 years, and it was never put in
PyPI, so I think at this point I'll continue with this name. Sorry if this
causes any trouble or confusion. I'll note that @drillan's library probably
does things the *right* way by installing as an `nbextension`.
## Buy Me a Coffee
[☕️](https://n8henrie.com/donate)
# [Changelog](https://keepachangelog.com)
## 0.4.0 :: 2024-08-30
- Drop support for python 3.7
- Remove functionality for old-style jupyter notebook
- Modern versions of `lab` and `notebook` both work the same way -- a much better way -- reducing the amount of code maintenance
- Users that are stuck on old versions of `notebook` (<7) will need to pin an older version of jupyter-black
- Add some nix stuff
- Update dependencies
## 0.3.4 :: 2023-04-27
- Only pass to `black.Mode` options from `pyproject.toml` that are valid for
`black.Mode`. Thanks @rldotai, https://github.com/n8henrie/jupyter-black/issues/7
## 0.3.2, 0.3.3 :: 2022-11-20
- Remove version constraints (thanks: @JakobGM, https://github.com/n8henrie/jupyter-black/issues/6)
- Update CI to ensure publishing should work
## 0.3.1 :: 2022-03-08
- Fix description (thanks: @bryanwweber)
- Version bump for PyPI
## 0.3.0 :: 2022-03-06
- Default to `lab=True`
- Add warning popup for users that load in notebook with `lab=True`
(including via `%load_ext`)
- Fix tests for the above
- Might as well minor version bump since this changes the API, even if
still `0.x`
## 0.2.1 :: 20220-03-04
- Python 3.10 support
- Black 22 support
## 0.2.0 :: 2021-11-14
- Breaking change: default to `lab=True`; `%load_ext jupyter_black` will now
work in jupyterlab and no longer work in a standalone notebook
## 0.1.1 :: 2021-09-28
- Unload the proper event
## 0.1.0 :: 2021-09-28
- First release on PyPI.
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyter-black",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "jupyter-black",
"author": null,
"author_email": "Nathan Henrie <nate@n8henrie.com>",
"download_url": "https://files.pythonhosted.org/packages/0c/a1/bdcefe44555914f4acf7bb65c97cf40749f56834fc5a6fb9c052e557075c/jupyter_black-0.4.0.tar.gz",
"platform": null,
"description": "# jupyter-black\n\nmaster: [](https://github.com/n8henrie/jupyter-black/actions/workflows/python-package.yml)\n\ndev: [](https://github.com/n8henrie/jupyter-black/actions/workflows/python-package.yml)\n\nA simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code\nautomatically using Black. Fork of\n[dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black) with a few minor\nmodifications:\n\n## Features\n\nOnce loaded, automatically format syntactically correct `jupyter` cells with\n`black` once they are run.\n\nEnhancements compared to [dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black):\n\n- Configurability:\n - Try to read black config from `pyproject.toml` if available\n - Override settings such as line length and `black.TargetVersion` if\n desired\n- Uses `black.format_cell` to greatly simplify the codebase\n- Adds tests\n- Slightly more responsive (no longer requires `setTimeout` and a delay)\n- Free software: MIT\n\n## Introduction\n\n[`black`][black] is an extremely popular python formatter. [Jupyter][jupyter] is an\nawesome way to run python. This extension helps you automatically `black`en\nyour `jupyter`.\n\n## Dependencies\n\n- Python >= 3.7\n- See `setup.cfg`\n\n## Quickstart\n\n```\npython3 -m venv .venv && source ./.venv/bin/activate\npython3 -m pip install --upgrade pip\npython3 -m pip install jupyter-black jupyter\npython3 -m jupyter notebook\n```\n\nFrom here, there are two ways to load the extension:\n\n### Configurable (recommended):\n\n```python\nimport jupyter_black\n\njupyter_black.load()\n```\n\nTo look at configuration options:\n\n```python\njupyter_black.load??\n```\n\nFor example:\n\n```python\nimport black\nimport jupyter_black\n\njupyter_black.load(\n lab=False,\n line_length=79,\n verbosity=\"DEBUG\",\n target_version=black.TargetVersion.PY310,\n)\n```\n\n### The other way:\n\n```python\n%load_ext jupyter_black\n```\n\nThis will load the extension using your defaults from `pyproject.toml` if\navailable, or use the `black` defaults. Please note that this defaults to\n`lab=True`, since moving to lab instead of standalone notebook installations\nseems to be the direction of the jupyter project; this means this method of\nloading will only work in JupyterLab, not in a standard notebook. For now,\nusers running a standalone notebook (instead of lab) need to use the\nrecommended (configurable) loading approach above.\n\n### Development Setup\n\n1. Clone the repo: `git clone https://github.com/n8henrie/jupyter-black && cd\n jupyter-black`\n2. Make a virtualenv: `python3 -m venv .venv`\n3. Activate venv, update pip, and install editable test/dev version:\n\n```console\n$ source ./.venv/bin/activate\n$ ./.venv/bin/python -m pip install --upgrade pip\n$ ./.venv/bin/python -m pip install -e .[test,dev]\n```\n\nNotes:\n\n- Tests use [playwright][playwright]\n- You'll need to run this command (once) prior to running the tests:\n - `python -m playwright install --with-deps firefox`\n- `tox` will automatically run these installation steps (helpful for CI)\n- If desired, pass the `--no-headless` flag to `pytest` for local debugging\n\n## TODO\n\nContribution ideas:\n\n- [ ] More tests, currently very basic\n - Ensure config is overridden in unsurprising ways\n - Ensure other config options are properly passed to `black`\n - Ensure that `pyproject.toml` is searched for properly\n- [x] Write tests for jupyter lab, currently only tested for notebook\n - [x] I think the fixture could easily be modularized to also work for `lab`,\n but haven't done the work yet\n\n## Contributing\n\nPlease see `CONTRIBUTING.md` and `TODO`.\n\n## Troubleshooting / FAQ\n\n- How can I install an older / specific version of [jupyter black](jupyter-black)?\n - Install from a tag:\n - pip install git+git://github.com/n8henrie/jupyter-black.git@v0.1.0\n - Install from a specific commit:\n - pip install git+git://github.com/n8henrie/jupyter-black.git@aabc123def456ghi789\n\n\n[black]: https://github.com/psf/black\n[jupyter]: https://jupyter.org/\n[playwright]: https://playwright.dev/python/\n\n\n## Acknowledgements\n\nMany thanks to [dnanhkhoa/nb_black](https://github.com/dnanhkhoa/nb_black) for\nthe original version!\n\nAnd of course many thanks to the [black][black] and [jupyter][jupyter] teams.\n\nAlso, after establishing the repo and reserving the name on PyPI, I noticed\nthere is another library of the same name:\n[drillan/jupyter-black](https://github.com/drillan/jupyter-black). It looks\nlike there have been no commits in the last 2 years, and it was never put in\nPyPI, so I think at this point I'll continue with this name. Sorry if this\ncauses any trouble or confusion. I'll note that @drillan's library probably\ndoes things the *right* way by installing as an `nbextension`.\n\n## Buy Me a Coffee\n\n[\u2615\ufe0f](https://n8henrie.com/donate)\n\n# [Changelog](https://keepachangelog.com)\n\n## 0.4.0 :: 2024-08-30\n\n- Drop support for python 3.7\n- Remove functionality for old-style jupyter notebook\n - Modern versions of `lab` and `notebook` both work the same way -- a much better way -- reducing the amount of code maintenance\n - Users that are stuck on old versions of `notebook` (<7) will need to pin an older version of jupyter-black\n- Add some nix stuff\n- Update dependencies\n\n## 0.3.4 :: 2023-04-27\n\n- Only pass to `black.Mode` options from `pyproject.toml` that are valid for\n `black.Mode`. Thanks @rldotai, https://github.com/n8henrie/jupyter-black/issues/7\n\n## 0.3.2, 0.3.3 :: 2022-11-20\n\n- Remove version constraints (thanks: @JakobGM, https://github.com/n8henrie/jupyter-black/issues/6)\n- Update CI to ensure publishing should work\n\n## 0.3.1 :: 2022-03-08\n\n- Fix description (thanks: @bryanwweber)\n- Version bump for PyPI\n\n## 0.3.0 :: 2022-03-06\n\n- Default to `lab=True`\n - Add warning popup for users that load in notebook with `lab=True`\n (including via `%load_ext`)\n - Fix tests for the above\n - Might as well minor version bump since this changes the API, even if\n still `0.x`\n\n## 0.2.1 :: 20220-03-04\n\n- Python 3.10 support\n- Black 22 support\n\n## 0.2.0 :: 2021-11-14\n\n- Breaking change: default to `lab=True`; `%load_ext jupyter_black` will now\n work in jupyterlab and no longer work in a standalone notebook\n\n## 0.1.1 :: 2021-09-28\n\n- Unload the proper event\n\n## 0.1.0 :: 2021-09-28\n\n- First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code automatically using Black. Fork of dnanhkhoa/nb_black.",
"version": "0.4.0",
"project_urls": {
"homepage": "https://github.com/n8henrie/jupyter-black"
},
"split_keywords": [
"jupyter-black"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc480b90a8d75f0baf494cacd0c23d4007639faf5089293744755dbbf5154ded",
"md5": "61c3127b7f91e63839fc7d1a5c613972",
"sha256": "aa4166786ad213e8863e2ea11e94cde4096c3b8d2734b2f64e0c4aab470beecc"
},
"downloads": -1,
"filename": "jupyter_black-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61c3127b7f91e63839fc7d1a5c613972",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7555,
"upload_time": "2024-08-30T20:01:18",
"upload_time_iso_8601": "2024-08-30T20:01:18.913137Z",
"url": "https://files.pythonhosted.org/packages/bc/48/0b90a8d75f0baf494cacd0c23d4007639faf5089293744755dbbf5154ded/jupyter_black-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ca1bdcefe44555914f4acf7bb65c97cf40749f56834fc5a6fb9c052e557075c",
"md5": "c14307cc0d41489019ab3e31fd279c50",
"sha256": "c88e01eff670d933f96bdf0dbc84bb71880b8a2ef38efca08a0fe6cfd6296db4"
},
"downloads": -1,
"filename": "jupyter_black-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "c14307cc0d41489019ab3e31fd279c50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22096,
"upload_time": "2024-08-30T20:01:20",
"upload_time_iso_8601": "2024-08-30T20:01:20.255177Z",
"url": "https://files.pythonhosted.org/packages/0c/a1/bdcefe44555914f4acf7bb65c97cf40749f56834fc5a6fb9c052e557075c/jupyter_black-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-30 20:01:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "n8henrie",
"github_project": "jupyter-black",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jupyter-black"
}
