Black

Black is a PEP 8 compliant code formatter for Python that reformats entire files in place, deliberately offering very few configuration knobs. By ceding control over formatting minutiae, teams get speed, determinism, and freedom from line-by-line style bikeshedding: any two developers running Black on the same code produce byte-identical output. It’s one of the most widely adopted developer tools in the Python ecosystem, maintained under the Python Software Foundation and used as the reference formatter for CPython itself and countless open-source and commercial Python codebases.

What You Get

• A black CLI that reformats files, directories, or stdin, with --check/--diff modes for CI enforcement without mutating files
• blackd, an HTTP daemon exposing the formatter as a service to avoid per-invocation startup cost in editor integrations
• A minimal, deliberately opinionated configuration surface (pyproject.toml [tool.black]) covering line length, target Python versions, and a small set of preview/stable style toggles
• Jupyter Notebook formatting support (including magic-cell handling) via the black[jupyter] extra
• First-class editor and CI integrations, including an official GitHub Action (psf/black@stable) and pre-commit hook

Common Use Cases

• Enforcing a single, non-negotiable Python code style across a team or open-source project without formatting debates in code review
• Running Black in CI (--check) to fail builds on unformatted code, or as a pre-commit/git hook to auto-format on commit
• Formatting Jupyter Notebooks as part of a data-science team’s code quality pipeline
• Migrating a legacy codebase to a consistent style in one pass, then relying on Black to keep it that way going forward

Under The Hood

Architecture Black’s pipeline runs source through blib2to3 (src/blib2to3, a maintained fork of lib2to3’s grammar/parser) to build a lossless concrete syntax tree, then src/black/linegen.py walks that tree to produce a sequence of Line objects (src/black/lines.py) representing logical output lines, which src/black/__init__.py’s top-level format_str/format_file_contents functions assemble into final text; src/black/brackets.py and nodes.py handle bracket-depth tracking and node classification that drive line-splitting decisions, while src/black/mode.py centralizes the (intentionally small) set of style parameters. src/blackd wraps the same formatting core in an aiohttp-based HTTP daemon for low-latency repeated calls from editors. Tech Stack Pure Python 3.10+, packaged with Hatchling and hatch-vcs for version derivation from git tags; the CLI is built on Click, and blackd adds aiohttp as an optional dependency. The project maintains its own CPython grammar fork rather than depending on the standard library’s ast module, so it can format both current and near-future Python syntax. Code Quality The tests/ directory contains 276 test files, including an extensive tests/data corpus of before/after fixture pairs covering edge cases across Python grammar versions, plus idempotency tests (formatting twice produces no further change) and a self-hosting check (Black formats its own source). CI covers multiple OSes and Python versions, and the project publishes a public change log with strict semantic-versioning-like discipline given unstable/preview style flags for staged rollout of new formatting rules. API Design The CLI surface is minimal and stable (black [path], --check, --diff, --line-length), reflecting the project’s philosophy of near-zero configuration; the small pyproject.toml [tool.black] surface means most users never need to read documentation beyond the README to get value, though power users wanting incremental style migrations must learn the preview/unstable flag semantics.