How psf/black works
Purpose and Entry Points
Black is an opinionated Python formatter: it discovers source files, reformats them deterministically, and validates semantic safety unless fast mode is selected. The primary CLI/package entry point is src/black/__main__.py, backed by the public formatter implementation in src/black/__init__.py. A separate HTTP formatter daemon starts at src/blackd/__main__.py; GitHub Action integration enters through action/main.py.
CLI Orchestration and Configuration
The CLI resolves command-line options and project defaults, constructs formatting mode/options, selects sources, and reports outcomes. Core option/state models are in src/black/mode.py; reporting is isolated in src/black/report.py. Configuration and discovery form a boundary between filesystem/project metadata and the formatter, principally src/black/files.py and schema assets at src/black/resources/black.schema.json.
Source Discovery, Filtering, and Incrementality
Input paths can be files, directories, or standard input. Discovery applies include/exclude rules, .gitignore behavior, and project configuration before work reaches parsing. src/black/files.py owns this selection boundary. src/black/cache.py persists formatting cache state to avoid unchanged work, while src/black/concurrency.py schedules independent file formatting in parallel.
Parsing and Syntax Model
Black parses Python using its vendored blib2to3 concrete-syntax-tree implementation rather than relying solely on the standard library parser. The parser-facing formatter layer is src/black/parsing.py; grammar, parser driver, and CST definitions reside in src/blib2to3/pygram.py, src/blib2to3/pgen2/driver.py, and src/blib2to3/pytree.py. This boundary converts source text into syntax nodes while retaining formatting-relevant structure and comments.
Formatting Pipeline
Formatting transforms a parsed CST into normalized logical and physical lines, then renders text. src/black/linegen.py generates lines and applies structural transformations; src/black/lines.py models line layout; src/black/trans.py performs split/merge transformations. Bracket analysis and delimiter decisions come from src/black/brackets.py, while comments and string normalization are handled by src/black/comments.py and src/black/strings.py. The output is whole-file formatting, not a general refactoring API.
Safety, Ranges, and Specialized Inputs
By default, Black checks that formatted code parses and is AST-equivalent to the original; this control flow is rooted in src/black/__init__.py with parsing support in src/black/parsing.py. Partial formatting is modeled in src/black/ranges.py. Jupyter notebook support is an optional input adapter that extracts/formats Python cells and preserves notebook structure, centered on src/black/handle_ipynb_magics.py.
Service and Distribution Boundaries
blackd exposes formatting as an HTTP service, separating request middleware and client concerns in src/blackd/middlewares.py and src/blackd/client.py from the shared Black engine. Runtime is Python 3.10+; notebook formatting requires the optional Jupyter dependency. Distribution targets include PyPI, Docker (Dockerfile), standalone binaries, GitHub Actions (action.yml), Vim integration (plugin/black.vim), and ReadTheDocs documentation (docs/conf.py).
Main entry points: __main__.py Black CLI · __init__.py Formatter API and safety · linegen.py Line generation · parsing.py Parsing boundary
Components 22
Entry points
- Black CLI · Discovers inputs, builds options, and reports formatting outcomes.
src/black/__main__.py
CLI and work control
- Mode and options
src/black/mode.py - Reporting
src/black/report.py - Discovery and config · Selects sources using project configuration, filters, and .gitignore rules.
src/black/files.py - Configuration schema
src/black/resources/black.schema.json - Formatting cache · Avoids reformatting unchanged files.
src/black/cache.py - Parallel scheduler
src/black/concurrency.py
Formatting engine
- Formatter API and safety · Coordinates whole-file formatting and AST-equivalence checks.
src/black/__init__.py - Line generation · Transforms CST structure into normalized logical and physical lines.
src/black/linegen.py - Line layout model
src/black/lines.py - Split and merge transforms
src/black/trans.py - Bracket analysis
src/black/brackets.py - Comments and strings · Normalizes comments and string literals during formatting.
src/black/comments.py - Partial formatting ranges
src/black/ranges.py
Syntax model
- Parsing boundary · Converts source text to and from the formatting CST.
src/black/parsing.py - Grammar definitions
src/blib2to3/pygram.py - Parser driver
src/blib2to3/pgen2/driver.py - Concrete syntax tree · Retains formatting-relevant structure and comments.
src/blib2to3/pytree.py
Service and input adapters
- blackd HTTP daemon · Exposes the shared formatter as an HTTP service.
src/blackd/__main__.py - HTTP middleware
src/blackd/middlewares.py - Notebook adapter · Formats Python cells while preserving notebook structure.
src/black/handle_ipynb_magics.py - GitHub Action
action/main.py
Connections 22
- Black CLI → Mode and options: builds
- Black CLI → Discovery and config: discovers sources
- Discovery and config → Configuration schema: validates project config
- Black CLI → Formatting cache: checks incrementality
- Black CLI → Parallel scheduler: schedules files
- Parallel scheduler → Formatter API and safety: formats work items
- Black CLI → Formatter API and safety: formats direct input
- Formatter API and safety → Parsing boundary: parses and verifies
- Parsing boundary → Grammar definitions: uses
- Parsing boundary → Parser driver: invokes
- Parser driver → Concrete syntax tree: produces
- Formatter API and safety → Line generation: formats CST
- Line generation → Line layout model: generates
- Line generation → Bracket analysis: analyzes delimiters
- Line generation → Comments and strings: normalizes
- Line generation → Split and merge transforms: applies layout transforms
- Formatter API and safety → Partial formatting ranges: limits partial formatting
- Black CLI → Reporting: reports outcomes
- blackd HTTP daemon → HTTP middleware: serves requests through
- blackd HTTP daemon → Formatter API and safety: uses shared engine
- Notebook adapter → Formatter API and safety: formats code cells with
- GitHub Action → Black CLI: runs