Skip to main content

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

master: master branch build status

dev: dev branch build status

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

0.3.2, 0.3.3 :: 2022-11-20

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.

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

jupyter-black-0.3.4.tar.gz (18.8 kB view hashes)

Uploaded source

Built Distribution

jupyter_black-0.3.4-py3-none-any.whl (8.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page