psf/black
56.2
Adequate · 14 November 2026
102.6k
lines of production code
Python
primary language
7
measurements over time
What this system is
Features
Add JSON Schema for pyproject.toml configuration validation
A new JSON Schema file (black.schema.json) has been added to the resources directory, defining the structure and valid values for the \[tool.black\] section in pyproject.toml. This enables editors and validation tools to provide autocomplete and error checking for Black's configuration options, such as line-length, target-version, and various preview/unstable features.
src/black/resources · high confidence
Initial release of the Vim plugin (v1.2)
Adds the \plugin/black.vim\ file, introducing the official Vim integration for Black. This plugin provides commands (\Black\, \BlackUpgrade\, \BlackVersion\) to format Python files, supports configuration via Vim variables (such as \g:black\_virtualenv\, \g:black\_fast\, \g:black\_linelength\, and \g:black\_preview\), and includes tab-completion for target Python versions (py310 through py315). It requires Vim 7.0+ with Python 3 support and defaults to using a virtual environment for the Black executable.
plugin · high confidence
Introduce blackd as a standalone package with client and CORS middleware
The blackd HTTP server is now distributed as a structured package under src/blackd, containing the main server entry point (\_\init\\_.py), a dedicated client library (client.py) for programmatic access, and a custom CORS middleware (middlewares.py). This change enables users to run blackd as a package, provides a Python client for integrating black formatting into other applications, and implements explicit CORS handling to control cross-origin access to the server.
src/blackd · high confidence
New scripts for CI, fuzzing, schema generation, and release automation
The \scripts/\ directory now contains several new tools: \diff\_shades\_gha\_helper.py\ automates the diff-shades GitHub Actions integration to measure formatting impact on PRs; \fuzz.py\ adds property-based fuzzing using Hypothesis and Hypothesmith to test Black's idempotency; \generate\_schema.py\ creates JSON schemas for Black's CLI options (including SchemaStore format); \make\_width\_table.py\ generates the Unicode width table for character handling; and \release.py\ along with \release\_tests.py\ automates the release process, including version calculation and documentation updates.
scripts · high confidence
Removals
Removal of blib2to3 pgen2 parser and tokenizer components
The \blib2to3.pgen2\ module has been completely removed, including the driver, grammar, parser, token constants, and tokenizer implementations along with their Python 3.6 type stubs. This eliminates the internal 2to3 parser engine and its associated utilities from the library.
blib2to3/pgen2 · high confidence
Removal of bundled blib2to3 grammar and source files
The \blib2to3\ directory has been stripped of its core implementation files, including \Grammar.txt\, \pygram.py\, \pytree.pyi\, and the package stubs. This change removes the local copy of the Python 2/3 grammar definitions and parsing infrastructure that were previously maintained in this location, likely shifting reliance to an external or standard library version of \lib2to3\.
blib2to3 · high confidence
Architecture
Black source code is reorganized into a src/ package structure
The Black codebase has been refactored from a flat layout into a structured \src/black/\ package. This change moves the main entry point and core logic into \src/black/\_\init\\.py\, introduces a dedicated \src/black/\\main\\_.py\ for CLI execution, and splits internal modules (such as \cache\, \comments\, \concurrency\, \files\, \brackets\, and \linegen\) into their own files within the \src/black/\ directory. This improves modularity and aligns with modern Python packaging standards.
src/black · high confidence
Behavioural changes
GitHub Action now supports reading Black version from pyproject.toml and dependency-groups
The GitHub Action for Black has been updated to allow users to specify the Black version via the \pyproject.toml\ file when the \use-pyproject\ input is enabled. The action now parses \tool.black.required-version\ or searches for the \black\ dependency within \dependency-groups\, \project.dependencies\, and \optional-dependencies\ to determine the version specifier. This change also introduces mutual exclusivity between the \version\ and \use-pyproject\ inputs, requires Python 3.11+ for pyproject parsing, and adds support for outputting logs to a file via the \output-file\ input.
action · high confidence
Introduction of Black version type stub
A new type stub file (\_black\_version.pyi) has been added to the source directory, defining a 'version' string variable. This change provides type hints for the Black version identifier, supporting static type checking for the library's version attribute.
src · medium confidence
Parser engine refactored for performance and modern Python support
The \blib2to3.pgen2\ parser module has been significantly refactored to improve performance and support modern Python syntax features. The tokenizer now leverages the external \pytokens\ library, enabling faster tokenization and native support for f-strings and t-strings. The parser engine itself has been optimized to eliminate quadratic behavior in token lookaheads, ensuring stable performance even with files containing many soft-keyword lookaheads (such as \match\/\case\ blocks). Additionally, the grammar handling has been updated to include explicit support for soft keywords and async keywords, and the codebase has been migrated to use modern Python typing and dataclasses.
src/blib2to3/pgen2 · high confidence
Profiling data files moved to dedicated profiling directory
Large synthetic data files used for performance profiling (dict\_big.py, dict\_huge.py, list\_big.py, list\_huge.py, mix\_big.py) have been relocated from the tests/data directory into a new profiling directory. This change organizes these large configuration structures, which define complex mappings and sets for benchmarking, into a dedicated location separate from unit test data.
profiling · high confidence
Repo-wide formatting and maintenance updates
This change applies a large-scale update across the repository, incorporating 1504 commits that include 254 fixes. The diff reflects extensive maintenance activities such as CI configuration updates (Travis, pre-commit, GitHub Actions), dependency version bumps (mypy, aiohttp, regex), and documentation improvements. It also includes numerous behavioral fixes and formatting adjustments to the codebase itself, ensuring stability and compliance with current standards.
(repo-wide) · low confidence
Vim plugin now uses an embedded Python environment for Black
The Vim plugin has been rewritten to use an embedded Python script (via \python3 \<\< EndPython3\) instead of calling the system \black\ executable. This change introduces automatic virtualenv management: the plugin can now create and manage its own virtual environment (controlled by \g:black\_use\_virtualenv\) to install and run Black, ensuring consistent behavior regardless of the user's system Python setup. It also adds support for new configuration flags like \preview\ and \skip\_magic\_trailing\_comma\, and improves Python version detection within virtual environments.
autoload · high confidence
blib2to3 parser updated to support modern Python syntax and refactored for performance
The blib2to3 parser has been significantly updated to support modern Python features, including pattern matching (match/case), type parameters (PEP 695), type aliases (PEP 696), f-string debugging (PEP 701), and various walrus operator placements. The grammar file (Grammar.txt) and symbol definitions (pygram.py) have been expanded to include these new constructs. Additionally, the parser's internal tree manipulation (pytree.py) has been optimized to avoid quadratic performance issues during node replacement and sibling map updates, and the module structure has been refactored to support mypyc compilation and explicit grammar initialization.
src/blib2to3 · high confidence
Test coverage
Add test infrastructure and data for gitignore, Jupyter notebooks, and optional markers; Added miscellaneous test fixtures for code formatting edge cases; Added regression and style test cases for Black formatting behavior; Added test fixtures for invalid .gitignore patterns; Added test fixtures for line-range formatting edge cases.
Dependencies
Migrate build system to Hatchling and drop Pipenv
The project has switched its build backend from setuptools to Hatchling, defined in the new \pyproject.toml\ which also specifies Python 3.10+ as the minimum supported version. To support this transition, the legacy \Pipfile\ and \Pipfile.lock\ have been removed in favor of standard \pip\ and \virtualenv\ workflows, and the dependency on the \attrs\ library has been dropped in favor of standard library \dataclasses\.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 54 → 56 (+1.6)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 67 → 87 (+19.1)
- Architecture 100 → 97 (-2.7)
- Maturity 57 → 58 (+1.1)
- Readiness 59 → 59 (+0.0)
- Security 43 → 43 (+0.0)
- Performance 100 → 100 (+0.0)
Resolved (8)
- Documentation: no project overview (docs/the_black_code_style/index.md)
- Hotspot: src/black/strings.py (src/black/strings.py)
- LineGenerator.visit_default (cognitive 20) (src/black/linegen.py)
- No ADRs found
- Orphaned file (src/blackd/client.py)
- Redundant assertion/checking operations. assert_stable and assert_equivalent are thin wrappers or aliases for check_stability_and_equivalence (or its underlying logic). They expose the same intent (verifying formatting correctness) with different names and slightly different signatures (one takes a single src and dst, the other takes src_contents and dst_contents but implies the same comparison). assert_stable likely checks idempotency, while assert_equivalent checks semantic equivalence, but they are closely related verification steps often used together.
- comments._should_keep_compound_statement_inline (cognitive 16) (src/black/comments.py)
- main.read_version_specifier_from_pyproject (cognitive 17) (action/main.py)
New (14)
- Edited copy of a member (10 corresponding lines) (src/black/linegen.py)
- Edited copy of a member (11 corresponding lines) (src/black/linegen.py)
- Edited copy of a member (17 corresponding lines) (src/black/linegen.py)
- Edited copy of a member (19 corresponding lines) (scripts/release.py)
- Edited copy of a member (22 corresponding lines) (src/black/trans.py)
- Edited copy of a member (42 corresponding lines) (src/black/trans.py)
- Hotspot: src/black/ranges.py (src/black/ranges.py)
- LineGenerator.visit_STANDALONE_COMMENT (cognitive 19) (src/black/linegen.py)
- LineGenerator.visit_comp_for (cognitive 18) (src/black/linegen.py)
- No ADRs found (pyproject.toml)
- Scattered collaborators
- comments._handle_comment_only_fmt_block (cyclomatic 18) (src/black/comments.py)
- comments._is_kept_as_text (cognitive 22) (src/black/comments.py)
- comments.generate_ignored_nodes (cyclomatic 19) (src/black/comments.py)
Changes since last survey
- 59 commits — 34 feature/other, 25 fixes
By area
- (root) — 38 commits
- src/black — 7 commits
- tests/data — 6 commits
- .github/workflows — 5 commits
- docs/contributing — 1 commit
- docs/faq.md — 1 commit
- docs/usage_and_configuration — 1 commit
Notable commits
- fix: Fix --line-ranges crash on clauses with their body on the same line (#5635)
- fix: Fix --line-ranges not removing selected trailing blank lines (#5654)
- fix: Fix --line-ranges producing invalid code for stacked decorators in 2-space or tab-indented code (#5672)
- fix: Fix B045 loop variable shadowing in _iter_nameescape_slices (#5639)
- fix: Fix # fmt: skip combined with # fmt: off / # yapf: disable in the same comment (#5665)
- fix: Fix # fmt: skip on a semicolon-separated body on its own line (#5674)
- fix: Fix # fmt: skip on the last line of a multi-line conditional expression in brackets (#5647)
- fix: Fix async statements dropped after a comment-only fmt: off/on block (#5678)
- fix: Fix blackd client encoding for custom Content-Type charsets (#5645)
- fix: Fix blackd startup on Windows with more than 61 logical CPUs (#5667)
- fix: Fix crash on # fmt: off before the trailing comma in brackets (#5651)
- fix: Fix crash on # fmt: off in an f-string with = or a t-string (#5653)
- fix: Fix crash on # fmt: skip on a nested bracket after with or yield (#5620)
- fix: Fix crash on # fmt: skip on several one-line clauses of a statement (#5675)
- fix: Fix crash on a commented parenthesized assignment target (#5662)
- fix: Fix crash on a multi-line parenthesized tuple target (#5621)
- fix: Fix crash on a skipped async def header with a ... body (#5671)
- fix: Fix crash on a type: ignore chain with another comment between the ignores (#5618)
- fix: Fix crash on backslash-only lines in code Black leaves as is (#5681)
- fix: Fix crash on fmt: skip after the last base of a skipped class header (#5633)
- …and 39 more
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
psf/black was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit ca3def85254274624c2e3909c9e36f832bb0cd05 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-36d4cd83012f.