jupyter-black

master:

dev:

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
• 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 blacken 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

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:

$ 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 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
• 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

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

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

☕️

Changelog

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.