A package that does some stuff]: A simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code automatically using Black. Fork of dnanhkhoa/nb_black.
Project description
jupyter-black
A simple extension for Jupyter Notebook and Jupyter Lab to beautify Python code automatically using Black. Fork of 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:
- Configurability:
- Try to read black config from
pyproject.toml
if available - Override settings such as line length and
black.TargetVersion
if desired
- Try to read black config from
- 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
is an extremely popular python formatter. 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):
import jupyter_black
jupyter_black.load()
To look at configuration options:
jupyter_black.load??
For example:
import black
import jupyter_black
jupyter_black.load(
lab=False,
line_length=79,
verbosity="DEBUG",
target_version=black.TargetVersion.PY310,
)
The other way:
%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
- Clone the repo:
git clone https://github.com/n8henrie/jupyter-black && cd jupyter-black
- Make a virtualenv:
python3 -m venv .venv
- Activate venv, update pip, and install editable test/dev version:
$ 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
- 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 topytest
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
- Write tests for jupyter lab, currently only tested for notebook
- I think the fixture could easily be modularized to also work for
lab
, but haven't done the work yet
- I think the fixture could easily be modularized to also work for
Contributing
Please see CONTRIBUTING.md
and TODO
.
Troubleshooting / FAQ
- How can I install an older / specific version of 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
- Install from a tag:
Acknowledgements
Many thanks to dnanhkhoa/nb_black for the original version!
And of course many thanks to the black and 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. 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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jupyter_black-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9df37b269a2f3685ca60aa8747b5e231d89c9aa27f2599393d574e113b7c5227 |
|
MD5 | e6d9a42ea28fcb1ff9c093df855581fd |
|
BLAKE2b-256 | f081107d885eb6903e0151e80fb57d445b4e83d7b8eea656a49cb7f058cf2887 |