# psf/black architecture

> Architecture diagram of the GitHub repository psf/black, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psf/black
- Repository: https://github.com/psf/black

## Overview

#### 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: [`src/black/__main__.py`](https://github.com/psf/black/blob/main/src/black/__main__.py) (Black CLI), [`src/black/__init__.py`](https://github.com/psf/black/blob/main/src/black/__init__.py) (Formatter API and safety), [`src/black/linegen.py`](https://github.com/psf/black/blob/main/src/black/linegen.py) (Line generation), [`src/black/parsing.py`](https://github.com/psf/black/blob/main/src/black/parsing.py) (Parsing boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Black CLI<br/>Python entry point<br/>[__main__.py]"]
end

subgraph group_orchestration["CLI and work control"]
  node_mode["Mode and options<br/>state models<br/>[mode.py]"]
  node_report["Reporting<br/>[report.py]"]
  node_files["Discovery and config<br/>filesystem boundary<br/>[files.py]"]
  node_schema["Configuration schema<br/>JSON schema<br/>[black.schema.json]"]
  node_cache[("Formatting cache<br/>incremental state<br/>[cache.py]")]
  node_concurrency["Parallel scheduler<br/>work scheduler<br/>[concurrency.py]"]
end

subgraph group_engine["Formatting engine"]
  node_formatter["Formatter API and safety<br/>Python module<br/>[__init__.py]"]
  node_linegen["Line generation<br/>formatting stage<br/>[linegen.py]"]
  node_lines["Line layout model<br/>[lines.py]"]
  node_trans["Split and merge transforms<br/>layout transforms<br/>[trans.py]"]
  node_brackets["Bracket analysis<br/>delimiter analysis<br/>[brackets.py]"]
  node_comments_strings["Comments and strings<br/>normalization<br/>[comments.py]"]
  node_ranges["Partial formatting ranges<br/>range selection<br/>[ranges.py]"]
end

subgraph group_syntax["Syntax model"]
  node_parsing["Parsing boundary<br/>parser-facing formatter<br/>[parsing.py]"]
  node_grammar["Grammar definitions<br/>vendored grammar<br/>[pygram.py]"]
  node_driver["Parser driver<br/>vendored parser<br/>[driver.py]"]
  node_cst["Concrete syntax tree<br/>syntax nodes<br/>[pytree.py]"]
end

subgraph group_adapters["Service and input adapters"]
  node_blackd["blackd HTTP daemon<br/>service entry point<br/>[__main__.py]"]
  node_middleware["HTTP middleware<br/>service middleware<br/>[middlewares.py]"]
  node_ipynb["Notebook adapter<br/>optional input adapter"]
  node_action["GitHub Action<br/>automation entry point<br/>[main.py]"]
end

node_cli -->|"builds"| node_mode
node_cli -->|"discovers sources"| node_files
node_files -->|"validates project config"| node_schema
node_cli -->|"checks incrementality"| node_cache
node_cli -->|"schedules files"| node_concurrency
node_concurrency -->|"formats work items"| node_formatter
node_cli -->|"formats direct input"| node_formatter
node_formatter -->|"parses and verifies"| node_parsing
node_parsing -->|"uses"| node_grammar
node_parsing -->|"invokes"| node_driver
node_driver -->|"produces"| node_cst
node_formatter -->|"formats CST"| node_linegen
node_linegen -->|"generates"| node_lines
node_linegen -->|"analyzes delimiters"| node_brackets
node_linegen -->|"normalizes"| node_comments_strings
node_linegen -->|"applies layout transforms"| node_trans
node_formatter -->|"limits partial formatting"| node_ranges
node_cli -->|"reports outcomes"| node_report
node_blackd -->|"serves requests through"| node_middleware
node_blackd -->|"uses shared engine"| node_formatter
node_ipynb -->|"formats code cells with"| node_formatter
node_action -->|"runs"| node_cli

click node_cli "https://github.com/psf/black/blob/main/src/black/__main__.py"
click node_formatter "https://github.com/psf/black/blob/main/src/black/__init__.py"
click node_mode "https://github.com/psf/black/blob/main/src/black/mode.py"
click node_report "https://github.com/psf/black/blob/main/src/black/report.py"
click node_files "https://github.com/psf/black/blob/main/src/black/files.py"
click node_schema "https://github.com/psf/black/blob/main/src/black/resources/black.schema.json"
click node_cache "https://github.com/psf/black/blob/main/src/black/cache.py"
click node_concurrency "https://github.com/psf/black/blob/main/src/black/concurrency.py"
click node_parsing "https://github.com/psf/black/blob/main/src/black/parsing.py"
click node_grammar "https://github.com/psf/black/blob/main/src/blib2to3/pygram.py"
click node_driver "https://github.com/psf/black/blob/main/src/blib2to3/pgen2/driver.py"
click node_cst "https://github.com/psf/black/blob/main/src/blib2to3/pytree.py"
click node_linegen "https://github.com/psf/black/blob/main/src/black/linegen.py"
click node_lines "https://github.com/psf/black/blob/main/src/black/lines.py"
click node_trans "https://github.com/psf/black/blob/main/src/black/trans.py"
click node_brackets "https://github.com/psf/black/blob/main/src/black/brackets.py"
click node_comments_strings "https://github.com/psf/black/blob/main/src/black/comments.py"
click node_ranges "https://github.com/psf/black/blob/main/src/black/ranges.py"
click node_blackd "https://github.com/psf/black/blob/main/src/blackd/__main__.py"
click node_middleware "https://github.com/psf/black/blob/main/src/blackd/middlewares.py"
click node_ipynb "https://github.com/psf/black/blob/main/src/black/handle_ipynb_magics.py"
click node_action "https://github.com/psf/black/blob/main/action/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_mode,node_report,node_files,node_schema,node_cache,node_concurrency toneAmber
class node_formatter,node_linegen,node_lines,node_trans,node_brackets,node_comments_strings,node_ranges toneMint
class node_parsing,node_grammar,node_driver,node_cst toneRose
class node_blackd,node_middleware,node_ipynb,node_action toneIndigo
```

## Components

### Entry points

- [Black CLI](https://github.com/psf/black/blob/main/src/black/__main__.py): Python entry point · Discovers inputs, builds options, and reports formatting outcomes. · `src/black/__main__.py`

### CLI and work control

- [Mode and options](https://github.com/psf/black/blob/main/src/black/mode.py): state models · `src/black/mode.py`
- [Reporting](https://github.com/psf/black/blob/main/src/black/report.py): result reporting · `src/black/report.py`
- [Discovery and config](https://github.com/psf/black/blob/main/src/black/files.py): filesystem boundary · Selects sources using project configuration, filters, and .gitignore rules. · `src/black/files.py`
- [Configuration schema](https://github.com/psf/black/blob/main/src/black/resources/black.schema.json): JSON schema · `src/black/resources/black.schema.json`
- [Formatting cache](https://github.com/psf/black/blob/main/src/black/cache.py): incremental state · Avoids reformatting unchanged files. · `src/black/cache.py`
- [Parallel scheduler](https://github.com/psf/black/blob/main/src/black/concurrency.py): work scheduler · `src/black/concurrency.py`

### Formatting engine

- [Formatter API and safety](https://github.com/psf/black/blob/main/src/black/__init__.py): Python module · Coordinates whole-file formatting and AST-equivalence checks. · `src/black/__init__.py`
- [Line generation](https://github.com/psf/black/blob/main/src/black/linegen.py): formatting stage · Transforms CST structure into normalized logical and physical lines. · `src/black/linegen.py`
- [Line layout model](https://github.com/psf/black/blob/main/src/black/lines.py): layout model · `src/black/lines.py`
- [Split and merge transforms](https://github.com/psf/black/blob/main/src/black/trans.py): layout transforms · `src/black/trans.py`
- [Bracket analysis](https://github.com/psf/black/blob/main/src/black/brackets.py): delimiter analysis · `src/black/brackets.py`
- [Comments and strings](https://github.com/psf/black/blob/main/src/black/comments.py): normalization · Normalizes comments and string literals during formatting. · `src/black/comments.py`
- [Partial formatting ranges](https://github.com/psf/black/blob/main/src/black/ranges.py): range selection · `src/black/ranges.py`

### Syntax model

- [Parsing boundary](https://github.com/psf/black/blob/main/src/black/parsing.py): parser-facing formatter · Converts source text to and from the formatting CST. · `src/black/parsing.py`
- [Grammar definitions](https://github.com/psf/black/blob/main/src/blib2to3/pygram.py): vendored grammar · `src/blib2to3/pygram.py`
- [Parser driver](https://github.com/psf/black/blob/main/src/blib2to3/pgen2/driver.py): vendored parser · `src/blib2to3/pgen2/driver.py`
- [Concrete syntax tree](https://github.com/psf/black/blob/main/src/blib2to3/pytree.py): syntax nodes · Retains formatting-relevant structure and comments. · `src/blib2to3/pytree.py`

### Service and input adapters

- [blackd HTTP daemon](https://github.com/psf/black/blob/main/src/blackd/__main__.py): service entry point · Exposes the shared formatter as an HTTP service. · `src/blackd/__main__.py`
- [HTTP middleware](https://github.com/psf/black/blob/main/src/blackd/middlewares.py): service middleware · `src/blackd/middlewares.py`
- [Notebook adapter](https://github.com/psf/black/blob/main/src/black/handle_ipynb_magics.py): optional input adapter · Formats Python cells while preserving notebook structure. · `src/black/handle_ipynb_magics.py`
- [GitHub Action](https://github.com/psf/black/blob/main/action/main.py): automation entry point · `action/main.py`

## Connections

- 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
