psf/black

This system is the Black Python code formatter, a tool that parses and rewrites Python source code to enforce a consistent style. It provides core formatting capabilities via a command-line interface, an HTTP server (blackd), and integrations for Vim and GitHub Actions. The system handles modern Python syntax, configuration validation, and automated release processes to ensure reliable code standardization.

7 changes.

The project migrated its build system to Hatchling, dropping Pipenv and setting Python 3.10+ as the minimum version, while removing the bundled blib2to3 parser infrastructure. This period also saw the initial release of the official Vim plugin and significant expansion of the test suite to cover new features and edge cases.

8 changes.

The project reorganized its codebase into a structured src/ package layout and modernized the blib2to3 parser to support new Python syntax features like pattern matching. Concurrently, infrastructure components such as the Vim plugin, GitHub Action, and release automation scripts were updated to improve integration, configuration handling, and deployment workflows.

5 changes.

This period focused on significantly expanding the test suite to cover complex Python syntax, formatting edge cases, and regression scenarios. It also introduced a JSON schema for pyproject.toml configuration validation and added type stubs to improve static type checking support.

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

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

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

The scripts directory now includes a comprehensive release tool (release.py) that automates changelog templating, version calculation, and documentation updates, along with dedicated validation scripts (check\_pre\_commit\_rev\_in\_example.py, check\_version\_in\_basics\_example.py) that ensure example code versions match the latest release. Additional utility scripts have been added to generate JSON schemas for configuration (generate\_schema.py), build Unicode width tables (make\_width\_table.py), and support CI-based diff analysis (diff\_shades\_gha\_helper.py), while fuzz testing (fuzz.py) and release logic tests (release\_tests.py) have been consolidated into this location.

scripts · high confidence

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

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

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

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

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

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

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

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

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

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

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 scenarios.

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 watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 50 → 69 (+19.0)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 89 → 100 (+11.1)
• Architecture 94 → 100 (+5.9)
• Maturity 56 → 58 (+2.3)
• Readiness 30 → 67 (+37.7)
• Security 69 → 78 (+9.1)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• Duplicated block (10 lines × 2) (tests/test_black.py)
• Duplicated block (11 lines × 2) (tests/test_black.py)
• Duplicated block (17 lines × 2) (tests/data/cases/composition.py)
• Duplicated block (18 lines × 2) (tests/data/cases/composition_no_trailing_comma.py)
• Duplicated block (7 lines × 2) (src/blib2to3/pgen2/conv.py)
• Duplicated block (8 lines × 2) (src/blib2to3/pgen2/conv.py)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Low IaC: DS-0026 (Dockerfile)
• Low: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• …and 11 more

• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Duplicated block (10 lines × 2) (src/black/parsing.py)
• Duplicated block (9 lines × 2) (src/black/linegen.py)
• FixmeComment (tests/data/cases/comments.py)
• FixmeComment (tests/data/cases/comments2.py)
• FixmeComment (tests/data/cases/comments2.py)
• Further orphaned files (smaller)
• HackComment (scripts/release_tests.py)
• HackComment (src/black/trans.py)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 27 more

• 43 commits — 34 feature/other, 9 fixes

• (root) — 21 commits
• src/black — 10 commits
• .github/workflows — 5 commits
• docs/contributing — 1 commit
• docs/faq.md — 1 commit
• docs/integrations — 1 commit
• docs/the_black_code_style — 1 commit
• scripts/migrate-black.py — 1 commit
• src/blib2to3 — 1 commit
• tests/test_black.py — 1 commit

• fix: Fix --line-ranges inserting a blank line after a docstring (#5312)
• fix: Fix a crash when # type: ignore is lost during formatting (#5329)
• fix: Fix crash on # fmt: skip in a decorated function group in stubs (#5430)
• fix: Fix git checkout command for Vundle in editor docs (#2781) (#5398)
• fix: Fix incorrect or redundant conditions (#5374)
• fix: Fix splitting stringified return annotations with parameters (#5427)
• fix: Fix unclosed file handles in Converter.parse_graminit_h/_c (#5432)
• fix: Fix unparseable output for # fmt: skip on compound header bracket (#5402) (#5405)
• fix: Support version specifiers in tool.black.required-version for GitHub Action (fixes #4406) (#5399)
• change: Avoid looking at class.name in run_transformer (#2432) (#5396)
• change: Bump docker/build-push-action from 7.3.0 to 7.4.0 (#5413)
• change: Bump docker/setup-buildx-action from 4.2.0 to 4.3.0 (#5325)
• change: Bump docker/setup-buildx-action from 4.3.0 to 4.4.1 (#5415)
• change: Bump mypy from 2.3.0 to 2.3.1 (#5384)
• change: Bump zizmorcore/zizmor-action from 0.6.2 to 0.6.3 (#5377)
• change: Bump zizmorcore/zizmor-action from 0.6.3 to 0.6.4 (#5394)
• change: Clarify project-root exclusion patterns (#5339)
• change: DOC: fix typo in docs/faq.md (#5313)
• change: Delete scripts/migrate-black.py (#5319)
• change: Don't require sys.stdout.buffer when writing formatted output or diffs (#5411)
• …and 23 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

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.