Jupyter Black

Common errors

• zsh: no matches found: black[jupyter]

  cause When installing Black with the Jupyter extra via pip in zsh, the brackets `[]` are interpreted by the shell and cause a 'no matches found' error.
  fix Escape the brackets with a backslash: `pip install black\[jupyter\]`. Note that `jupyter-black` (this library) is a separate project from Black's own Jupyter integration, and does not require this extra.

• SyntaxError: invalid syntax (when expecting formatting)

  cause If a Jupyter cell contains code with a `SyntaxError`, `jupyter-black` (like `black` itself) will not attempt to reformat it. It requires syntactically valid Python code to apply formatting.
  fix Correct any syntax errors in the cell. Once the code is syntactically valid, `jupyter-black` will format it on the next execution.

• Extension 'jupyter_black' could not be loaded.

  cause This error typically occurs if `jupyter-black` is not properly installed, or if there's a version mismatch between the extension and your Jupyter environment (e.g., trying to use it with very old Jupyter versions or incompatible Jupyter Server configurations).
  fix Ensure `jupyter-black` is installed in the correct environment (`pip install jupyter-black`). If issues persist, verify your JupyterLab/Notebook version meets the `jupyter-black` requirements (JupyterLab >=4 / Notebook >=7) or consider using an older `jupyter-black` version. Restarting the Jupyter kernel or server can also resolve transient loading issues.

Warnings

• breaking Jupyter Black version 0.4.0 and higher requires `jupyterlab >= 4` or `notebook >= 7`. If you are using older versions of Jupyter Notebook, you will encounter compatibility issues.
  Fix: Upgrade your JupyterLab to version 4+ or Jupyter Notebook to version 7+, or pin `jupyter-black` to an older version like `0.3.4` (e.g., `pip install jupyter-black==0.3.4`).
• gotcha Jupyter Black will not format cells containing IPython automagics (e.g., `%%timeit`), non-Python cell magics (e.g., `%%writefile`), multiline magics, or code with invalid Python syntax. These cells will be skipped without formatting.
  Fix: Ensure cells contain valid Python syntax for formatting. For cells with magics or mixed content, manual formatting may be required, or the magics should be placed on separate lines if possible.
• gotcha There are multiple Python packages or older projects with similar names (e.g., `nb_black`, `drillan/jupyter-black`). Ensure you are installing and using `n8henrie/jupyter-black` from PyPI.
  Fix: Always install using `pip install jupyter-black` (the pypi.org/project/jupyter-black package) and verify the GitHub repository `n8henrie/jupyter-black` for official documentation and updates.

Install

• pip install jupyter-black Install jupyter-black

Imports

• jupyter_black

  import jupyter_black

  The primary module to import for programmatic loading.

Quickstart

To enable jupyter-black, simply import the library and call `jupyter_black.load()` in a code cell. This can be customized with `line_length`, `verbosity`, and `target_version` arguments. Once loaded, code cells will be formatted automatically upon execution. Alternatively, you can use the IPython magic command `%load_ext jupyter_black` for default settings.

import jupyter_black
import black

# Load the extension with default settings or custom configurations
jupyter_black.load(
    line_length=88, # Default Black line length
    fast=True, # Optional: skip AST verification for speed
    target_version=black.TargetVersion.PY311 # Adjust to your Python version
)

# Code in subsequent cells will be automatically formatted on execution
def example_function ( arg1,  arg2 =  None ):
    '''
    A poorly formatted function.
    '''
    if  arg2  is None:
        return arg1
    else:    return arg1 + arg2