Skip to content
CAI
Software that uses CAICheck a score

psf/black

56.2

Adequate · 14 November 2026

102.6k

lines of production code

Python

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

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.