psf / black · Architecture

The analyzed inventory holds 482 files, concentrated in tests (326 files), src (48), docs (48), .github (22), and scripts (9), with 19 files at the root. Four subsystem records describe docs, scripts, src, and tests as top-level directories likely representing subsystems. Paths in entrypoint and role records show src/ containing the packages black (including __init__.py, linegen.py, trans.py, comments.py, nodes.py), blackd, and blib2to3 (pytree.py) with a pgen2 subpackage (driver.py). Role and entrypoint records also show test code such as tests/test_black.py and tests/util.py, plus case files under tests/data/cases/. Entrypoint excerpts show two doc-check scripts opening CHANGES.md and markdown under docs/integrations/ and docs/usage_and_configuration/.

The reconstruction counts 18 entrypoints and 176 bounded execution paths. Seventeen entrypoint records report a Python __main__ guard (if __name__ == "__main__":): eight in scripts/, five in src/ (black, blackd, and three blib2to3.pgen2 modules), and four in tests/ (tests/test_tokenize.py plus tests/data/cases/ files). An eighteenth record flags action/main.py as a likely executable by filename heuristic, and a teaching claim calls it a detected starting point. All ten listed bounded paths begin at action/main.py and end after one step at os.getenv (seven paths), re.compile (two), or Path (one), each with terminal reason 'unresolved_boundary', no detected cycle, and no truncation. None of the listed paths reaches the src/ tree. The repository summary separately names scripts/check_pre_commit_rev_in_example.py as the apparent main starting place.

Each role record lists its evidence basis as static resolved call degree and entrypoint membership, so these roles are inferred from call counts, not observed at runtime. Role records report tests/util.py at 118 incoming calls and tests/test_black.py at 104 incoming and 177 outgoing. In src/, they report src/black/linegen.py at 79 incoming and 79 outgoing calls and src/black/trans.py at 66 each. The analyzer labels linegen.py, trans.py, comments.py, nodes.py, and tests/test_black.py 'service/core candidate', while src/black/__init__.py, src/blackd/__init__.py, tests/test_tokenize.py, and scripts/diff_shades_gha_helper.py are 'entry/orchestration candidate'. In blib2to3, role records show src/blib2to3/pytree.py at 13 incoming calls and src/blib2to3/pgen2/driver.py at 10 incoming and 13 outgoing.

Every listed bounded path stops inside action/main.py, at os.getenv, re.compile, or Path calls labeled external_or_unresolved. Relation counts give 8,487 external_or_unresolved relations against 852 local ones out of 9,339 total. The analyzer does not resolve dynamic dispatch, dynamic imports, reflection, monkey-patching, generated code, or framework runtime wiring, which caps what any static path can show. One-file top-level directories named plugin and autoload appear in the inventory; none of the ten listed bounded paths links to them (all ten stay within action/main.py per the execution-path records), and the packet establishes no loading mechanism for them.

By type, the packet records 8,219 call relations and 1,120 imports among 9,339 static relations. The reconstruction separately reports 813 resolved static call relations across the 482 analyzed files. On manifest dependencies: dependency records in this analysis come only from requirements-style manifests, and pyproject.toml dependency tables are not parsed. Where internal calls concentrate, role records point to tests/util.py (118 incoming) and tests/test_black.py (177 outgoing, 104 incoming). Beyond these per-module degrees, specific cross-module dependency edges are not individually citable from this packet.

This asset rests on static analysis, which the analyzer documents as unable to resolve reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring, and dynamic dispatch. Install, run, and build inference is partial, and installation commands are not verified. README claim extraction is line-based and may capture code lines instead of prose, so README-derived statements are author_claimed at best. The manifest's capability fields describe the analyzer, not this repository, and are excluded from repository evidence. Finally, the inventory counts 326 test-like files, but how those suites behave when executed is not established here.

Start with README.md, pyproject.toml, and LICENSE, which the analyzer classifies as project-level important files. Then open action/main.py: the modify guide recommends beginning at that detected entrypoint and verifying downstream effects manually. For the core, read src/black/__init__.py, whose __main__ guard calls patched_main and whose role record is 'entry/orchestration candidate'. Continue with src/black/linegen.py and src/black/trans.py, the highest-degree src/ role records cited here, and use tests/test_black.py for behavior examples. Treat the 8,487 unresolved relations and the unresolved dynamic mechanisms as the edge of this map.