EVEMISSTechnology

Repository guide · source walkthrough · v1

psf / black · Source walkthrough

A four-stop reading order for the analyzed revision: six script files for orientation, one entrypoint module with five example bounded execution paths, the AI Frontier lab's library reading set of four src/black/ modules, and the strongly coupled report tests in tests/test_black.py, plus the static analysis's documented limits.

View on GitHub ↗ Analyzed revision 20622e1259c2 ↗ ← Overview
Original repository
psf/black
License
MIT · open-source license
Analyzed revision · last verified
20622e1259c29bda81831962ace1348ba1921c84 ·

Newer revision observed; parts of this guide may be outdated. The default branch moved to 5fe7881e6e40, checked 2026-10-03. The whole guide describes revision 20622e1259c2. A revision diff found changes in 6 code regions it cites (listed below); statements about those regions may not hold at the new revision and have not been rechecked yet.

  • src/black/linegen.py:110-735 · lines changed
  • action/main.py:51-99 · lines changed
  • src/black/linegen.py:1661-1839 · lines changed
  • src/black/__init__.py:554-776 · lines changed
  • src/black/comments.py:719-887 · lines changed
  • src/black/comments.py:429-547 · lines changed

psf/black source walkthrough: a guided reading order

Terms used on this page
Entrypoint record
A file the analyzer marks as a place where execution can start. When it carries a __main__ guard excerpt, the file contains an if __name__ == "__main__": block and the excerpt shows what that block calls; without an excerpt, the file was flagged by its name only.
Bounded static execution path
A call chain reconstructed from the source code without running it, stopped after a fixed number of steps. It shows how far the code can be followed on paper, not what happens at run time.
Unresolved boundary
Where a static path stops because the next call goes into an external library or cannot be resolved without running the code. It marks the edge of this analysis, not a defect in the repository.
Static relations
Calls and imports found in the source. "External or unresolved" relations point outside the analyzed files.
Module role
The analyzer's label for a file, inferred from how many calls go in and out (for example core, entry/orchestration, leaf). It describes a position in the call graph, not the authors' design.
Test-like files
Files whose names or locations look like tests. This analysis counts them; it does not run them.
Observed · inferred · author-claimed · unresolved
How each statement is supported: read directly from the analyzed files; derived by the analyzer from them; stated by the repository's authors (metadata, README); or not established by this analysis.
Verified
Two uses on these pages. In an analyzer record ("verified provenance", "a verified entrypoint") it means the record was read directly from the analyzed files, which these guides call observed; for an entrypoint, the __main__ guard text is present. Since the analyzer fix of 2026-10-04, a file that only has an entrypoint-like name such as cli.py or main.py is recorded as inferred; guides analyzed before that still call such a file verified, and it is still only a guess about how the file is used. It does not mean the code was run or tested. "Last verified" is the date the guide last passed the lab's checks against the analysis record of the stated revision; it is not a review of the repository itself.

How to use this walkthrough

This asset is a reading order, not a code listing or a tutorial. It follows the analyzer's suggested order — start with landmarks and important symbols, trace bounded execution paths, inspect unresolved boundaries before changing code — presented as four stops plus this introduction and a limits section. A block is the analyzer's line-addressable unit; its description and confidence are the analyzer's inference, and every line range below is written path:start-end from the block's exact recorded lines value for the analyzed revision, never computed or widened.

Stop 1 — Orientation: file-level blocks in scripts/

The orientation lesson collects six file-level blocks, all in scripts/ and none flagged by the analyzer as library code; it describes each as the file-level container for the analyzed code in that file. Each of the six files also carries a parser-verified __main__ entrypoint guard.

  • scripts/check_pre_commit_rev_in_example.py:1-63 — module, symbol scripts/check_pre_commit_rev_in_example.py; the analyzer's file-level container for the analyzed code (confidence 0.76).
  • scripts/check_version_in_basics_example.py:1-54 — module, symbol scripts/check_version_in_basics_example.py; file-level container for the analyzed code (confidence 0.76).
  • scripts/diff_shades_gha_helper.py:1-231 — module, symbol scripts/diff_shades_gha_helper.py; file-level container for the analyzed code (confidence 0.76).
  • scripts/fuzz.py:1-73 — module, symbol scripts/fuzz.py; file-level container for the analyzed code (confidence 0.76).
  • scripts/generate_schema.py:1-75 — module, symbol scripts/generate_schema.py; file-level container for the analyzed code (confidence 0.9).
  • scripts/make_width_table.py:1-66 — module, symbol scripts/make_width_table.py; file-level container for the analyzed code (confidence 0.9).

Stop 2 — Execution story: one module and bounded paths

The execution-story lesson's only block is the file-level module action/main.py:1-201. The analyzer's entrypoint records list action/main.py as an entrypoint with verified provenance.

  • action/main.py:1-201 — module, symbol action/main.py; the analyzer says it provides the file-level container for the analyzed code (confidence 0.76).
  • The packet lists five example bounded execution paths from this module, each terminating at an unresolved boundary: calls into os.getenv or Path, marked external_or_unresolved.
  • These five are examples, not the total: the architecture reconstruction counts 176 bounded execution paths and 18 entrypoints.

Stop 3 — Core code: the lab's library reading set

The analyzer's core-code lesson has 8 blocks and 0 of them lie in library code — they sit in action/main.py, docs/conf.py and scripts/check_pre_commit_rev_in_example.py — so they appear once as a group below, followed by the lab-selected library reading set. The library reading set is not an analyzer lesson: it is the AI Frontier lab's deterministic selection of the four most connected modules by static call degree outside tests, docs, examples, scripts, benchmarks and CI files.

  • Core-code lesson blocks (none in library code): action/main.py:29-48 determine_version_specifier (function; 3 downstream relations), action/main.py:51-99 read_version_specifier_from_pyproject (function; 20), action/main.py:102-123 find_black_version_in_array (function; 9), docs/conf.py:26-32 make_pypi_svg (function; 8), docs/conf.py:35-37 replace_pr_numbers_with_links (function; 1), docs/conf.py:40-48 handle_include_read (function; 1), docs/conf.py:51-53 setup (function; 1), scripts/check_pre_commit_rev_in_example.py:20-46 main (function; 11) — each described by the analyzer as an encapsulated operation with that many downstream call or import relations.
  • src/black/linegen.py — analyzer role: service/core candidate (79 incoming / 79 outgoing calls).
    • src/black/linegen.py:110-735 — class LineGenerator, signature class LineGenerator(Visitor[Line]):; class-boundary grouping (confidence 0.99).
    • src/black/linegen.py:1661-1839 — function normalize_invisible_parens; 48 downstream call or import relations (confidence 0.76).
  • src/black/trans.py — analyzer role: service/core candidate (66 incoming / 66 outgoing calls).
    • src/black/trans.py:1429-1962 — class StringSplitter, signature class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):; class-boundary grouping (confidence 0.99).
    • src/black/trans.py:411-898 — class StringMerger, signature class StringMerger(StringTransformer, CustomSplitMapMixin):; class-boundary grouping (confidence 0.99).
  • src/black/__init__.py — analyzer role: entry/orchestration candidate (42 incoming / 42 outgoing calls).
    • src/black/__init__.py:554-776 — function main; 61 downstream call or import relations (confidence 0.76).
    • src/black/__init__.py:1380-1547 — function get_features_used; 38 downstream call or import relations (confidence 0.76).
  • src/black/comments.py — analyzer role: service/core candidate (37 incoming / 37 outgoing calls).
    • src/black/comments.py:719-887 — function _generate_ignored_nodes_from_fmt_skip; 24 downstream call or import relations (confidence 0.76).
    • src/black/comments.py:429-547 — function _handle_regular_fmt_block; 32 downstream call or import relations (confidence 0.76).

Stop 4 — Where changes ripple: the change-guide lesson

All six change-guide blocks sit in tests/test_black.py, outside library code, so the coupling signal here comes from test code; the analyzer also rates that module a service/core candidate with 104 incoming and 177 outgoing calls.

  • tests/test_black.py:550-650 — function BlackTestCase.test_report_verbose; 99 downstream call or import relations (confidence 0.76).
  • tests/test_black.py:561-650 — with block, symbol BlackTestCase.test_report_verbose; scopes operations under a context manager visible in the source (confidence 0.76).
  • tests/test_black.py:746-841 — function BlackTestCase.test_report_normal; 96 downstream call or import relations (confidence 0.76).
  • tests/test_black.py:757-841 — with block, symbol BlackTestCase.test_report_normal; scopes operations under a context manager (confidence 0.76).
  • tests/test_black.py:652-744 — function BlackTestCase.test_report_quiet; 93 downstream call or import relations (confidence 0.76).
  • tests/test_black.py:663-744 — with block, symbol BlackTestCase.test_report_quiet; scopes operations under a context manager (confidence 0.76).

What this walkthrough cannot show

  • Static analysis only: reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring and dynamic dispatch are not resolved by this analysis.
  • Install, run and build inference is partial and installation commands are not verified, so this asset contains no commands.
  • Dependency records come only from requirements-style manifests (pyproject.toml dependency tables are not parsed); README claim extraction is line-based, so README-derived claims are author_claimed at best; the manifest's capability fields describe the analyzer, not the analyzed repository.
  • A teaching claim states that static analysis cannot establish all dynamic dispatch, reflection, generated-code or runtime framework behavior.
  • A teaching claim also says no bounded static execution path is available, which conflicts with the five example path records listed above; runtime flow stays unresolved in this asset.

What this analysis could not establish

The writing model's own notes on the analysis record. Identifiers such as lim_3, exec_* or claim_… name records of that analysis; the claims table cites the same records.

  • The uncertainties lesson lists no blocks of its own; the limits here come from the packet's limitation records and unresolved teaching claims.
  • The packet reports 8487 static relations as external or unresolved, but that count is not attached to a citable ID, so this asset does not state it as a claim.
  • The five listed execution paths resolve only to external or unresolved targets, so they support no deeper runtime story.
  • Confidence values quoted (for example 0.76 and 0.99) are the analyzer's own annotations, not independent verification.
  • The packet's teaching claim of no bounded static execution path conflicts with its five listed example path records; this asset treats both as unresolved for runtime behavior.
Claims and evidence — 39 claims, 39 supported by an independent verifier

Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.

Claim Epistemic status Verifier Grounding (global IDs)
c1 This asset is a reading order presented as four stops plus an introduction and a limits section; it follows the analyzer's suggested order to start with landmarks and important symbols, trace bounded execution paths, and inspect unresolved boundaries before changing code. inferred supported analysis_f07f1c5b3429400e:claim_e56db45165bf
c2 A block is the analyzer's line-addressable unit; its description and confidence are the analyzer's inference, and every line range in this asset is a block's exact recorded 'lines' value for the analyzed revision, never computed or widened. inferred supported analysis_f07f1c5b3429400e:block_928a4dc4966269, analysis_f07f1c5b3429400e:block_be5e5749330e5a
c3 The orientation lesson's six file-level blocks all sit in scripts/ and none is flagged as library code; the analyzer describes each as the file-level container for the analyzed code in its file. inferred supported analysis_f07f1c5b3429400e:block_6b468ea061bf8f, analysis_f07f1c5b3429400e:block_3d54d5de1febfb, analysis_f07f1c5b3429400e:block_4abfed3270675b, analysis_f07f1c5b3429400e:block_717c987586b822, analysis_f07f1c5b3429400e:block_a549659c90d023, analysis_f07f1c5b3429400e:block_9fbc34cc77c120
c4 Each of the six orientation script files carries a parser-verified __main__ entrypoint guard. observed supported analysis_f07f1c5b3429400e:py_entry_6375211a42e2, analysis_f07f1c5b3429400e:py_entry_49b6285f03c4, analysis_f07f1c5b3429400e:py_entry_a7be1b170db3, analysis_f07f1c5b3429400e:py_entry_45e63aec2981, analysis_f07f1c5b3429400e:py_entry_2d43f7cb959d, analysis_f07f1c5b3429400e:py_entry_078791731a33
c5 scripts/check_pre_commit_rev_in_example.py:1-63 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_6b468ea061bf8f
c6 scripts/check_version_in_basics_example.py:1-54 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_3d54d5de1febfb
c7 scripts/diff_shades_gha_helper.py:1-231 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_4abfed3270675b
c8 scripts/fuzz.py:1-73 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_717c987586b822
c9 scripts/generate_schema.py:1-75 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.9). inferred supported analysis_f07f1c5b3429400e:block_a549659c90d023
c10 scripts/make_width_table.py:1-66 is a module block that the analyzer describes as the file-level container for the analyzed code in that file (confidence 0.9). inferred supported analysis_f07f1c5b3429400e:block_9fbc34cc77c120
c11 The execution-story lesson's only block is the file-level module action/main.py:1-201. inferred supported analysis_f07f1c5b3429400e:block_be5e5749330e5a
c12 The analyzer's entrypoint records list action/main.py as an entrypoint with verified provenance. observed supported analysis_f07f1c5b3429400e:entry_1
c13 action/main.py:1-201 is a module block (symbol action/main.py) that the analyzer says provides the file-level container for the analyzed code in this file (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_be5e5749330e5a
c14 The packet lists five example bounded execution paths from action/main.py, each terminating at an unresolved boundary: calls into os.getenv or Path marked external_or_unresolved. inferred supported analysis_f07f1c5b3429400e:exec_bfd58df29904, analysis_f07f1c5b3429400e:exec_5daffbde25d6, analysis_f07f1c5b3429400e:exec_12046e1e9958, analysis_f07f1c5b3429400e:exec_dbb7510ec43e, analysis_f07f1c5b3429400e:exec_73307b610151
c15 These five paths are examples, not the total: the architecture reconstruction counts 176 bounded execution paths and 18 entrypoints. inferred supported analysis_f07f1c5b3429400e:claim_31723c5d9328
c16 The core-code lesson's 8 blocks include 0 in library code; they sit in action/main.py, docs/conf.py and scripts/check_pre_commit_rev_in_example.py, so they appear once as a group before the library reading set. inferred supported analysis_f07f1c5b3429400e:block_36d096303a8822, analysis_f07f1c5b3429400e:block_8c1eaaf0bbe3d0, analysis_f07f1c5b3429400e:block_539eed16fd7e7b, analysis_f07f1c5b3429400e:block_86c307a9565f52, analysis_f07f1c5b3429400e:block_306e681c823d11, analysis_f07f1c5b3429400e:block_71b27f1a18ca65, analysis_f07f1c5b3429400e:block_1df5723c06d644, analysis_f07f1c5b3429400e:block_075ee9ff233c0d
c17 The lesson's action/main.py blocks are determine_version_specifier (action/main.py:29-48; 3 downstream call or import relations), read_version_specifier_from_pyproject (action/main.py:51-99; 20) and find_black_version_in_array (action/main.py:102-123; 9), all functions the analyzer says encapsulate operations. inferred supported analysis_f07f1c5b3429400e:block_36d096303a8822, analysis_f07f1c5b3429400e:block_8c1eaaf0bbe3d0, analysis_f07f1c5b3429400e:block_539eed16fd7e7b
c18 The lesson's docs/conf.py blocks are make_pypi_svg (docs/conf.py:26-32; 8 relations), replace_pr_numbers_with_links (docs/conf.py:35-37; 1), handle_include_read (docs/conf.py:40-48; 1) and setup (docs/conf.py:51-53; 1), plus main in scripts/check_pre_commit_rev_in_example.py (scripts/check_pre_commit_rev_in_example.py:20-46; 11). inferred supported analysis_f07f1c5b3429400e:block_86c307a9565f52, analysis_f07f1c5b3429400e:block_306e681c823d11, analysis_f07f1c5b3429400e:block_71b27f1a18ca65, analysis_f07f1c5b3429400e:block_1df5723c06d644, analysis_f07f1c5b3429400e:block_075ee9ff233c0d
c19 The library reading set is not an analyzer lesson: it is the AI Frontier lab's deterministic selection of the four most connected modules by static call degree outside tests, docs, examples, scripts, benchmarks and CI files. inferred supported analysis_f07f1c5b3429400e:role_19, analysis_f07f1c5b3429400e:role_27, analysis_f07f1c5b3429400e:role_11, analysis_f07f1c5b3429400e:role_14
c20 The analyzer infers the role 'service/core candidate' for src/black/linegen.py with 79 incoming and 79 outgoing static calls. inferred supported analysis_f07f1c5b3429400e:role_19
c21 linegen.py's two reading-set blocks are the class LineGenerator (src/black/linegen.py:110-735; class-boundary grouping, confidence 0.99) and the function normalize_invisible_parens (src/black/linegen.py:1661-1839; 48 downstream call or import relations, confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_928a4dc4966269, analysis_f07f1c5b3429400e:block_d3d40b182b88ca, analysis_f07f1c5b3429400e:py_class_b0018f23e219, analysis_f07f1c5b3429400e:py_func_360115cdb01c
c22 The analyzer infers the role 'service/core candidate' for src/black/trans.py with 66 incoming and 66 outgoing static calls. inferred supported analysis_f07f1c5b3429400e:role_27
c23 trans.py's two reading-set blocks are the class StringSplitter (src/black/trans.py:1429-1962) and the class StringMerger (src/black/trans.py:411-898), both class-boundary groupings at confidence 0.99. inferred supported analysis_f07f1c5b3429400e:block_031bc2a6f13933, analysis_f07f1c5b3429400e:block_e7a3ac757ad14b, analysis_f07f1c5b3429400e:py_class_ccf9a04fb373, analysis_f07f1c5b3429400e:py_class_55b06baae3f0
c24 The analyzer infers the role 'entry/orchestration candidate' for src/black/__init__.py with 42 incoming and 42 outgoing static calls. inferred supported analysis_f07f1c5b3429400e:role_11
c25 __init__.py's two reading-set blocks are the function main (src/black/__init__.py:554-776; 61 downstream call or import relations) and the function get_features_used (src/black/__init__.py:1380-1547; 38), both confidence 0.76. inferred supported analysis_f07f1c5b3429400e:block_381ad71298313d, analysis_f07f1c5b3429400e:block_2121e9e99f5afe, analysis_f07f1c5b3429400e:py_func_e9acdca9deb3, analysis_f07f1c5b3429400e:py_func_f643fdae7142
c26 The analyzer infers the role 'service/core candidate' for src/black/comments.py with 37 incoming and 37 outgoing static calls. inferred supported analysis_f07f1c5b3429400e:role_14
c27 comments.py's two reading-set blocks are the function _generate_ignored_nodes_from_fmt_skip (src/black/comments.py:719-887; 24 downstream call or import relations) and the function _handle_regular_fmt_block (src/black/comments.py:429-547; 32), both confidence 0.76. inferred supported analysis_f07f1c5b3429400e:block_78f207b5645419, analysis_f07f1c5b3429400e:block_4ed1c5d9623233, analysis_f07f1c5b3429400e:py_func_5744fbc4a6df, analysis_f07f1c5b3429400e:py_func_36f5030fe23a
c28 All six change-guide blocks sit in tests/test_black.py outside library code, so the coupling signal there comes from test code; the analyzer also rates that module a service/core candidate with 104 incoming and 177 outgoing calls. inferred supported analysis_f07f1c5b3429400e:block_fb2d92e7708708, analysis_f07f1c5b3429400e:block_1e0f6e6104e99b, analysis_f07f1c5b3429400e:block_6e1461bc5541d0, analysis_f07f1c5b3429400e:block_d98a40768eea2e, analysis_f07f1c5b3429400e:block_55b037423ce4dc, analysis_f07f1c5b3429400e:block_7feaf3019dd3c4, analysis_f07f1c5b3429400e:role_48
c29 tests/test_black.py:550-650 is the function BlackTestCase.test_report_verbose, which the analyzer says connects to 99 downstream call or import relations (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_fb2d92e7708708
c30 tests/test_black.py:561-650 is a with block with symbol BlackTestCase.test_report_verbose that scopes operations under a context manager visible in the source (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_1e0f6e6104e99b
c31 tests/test_black.py:746-841 is the function BlackTestCase.test_report_normal with 96 downstream call or import relations (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_6e1461bc5541d0
c32 tests/test_black.py:757-841 is a with block with symbol BlackTestCase.test_report_normal scoping operations under a context manager (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_d98a40768eea2e
c33 tests/test_black.py:652-744 is the function BlackTestCase.test_report_quiet with 93 downstream call or import relations (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_55b037423ce4dc
c34 tests/test_black.py:663-744 is a with block with symbol BlackTestCase.test_report_quiet scoping operations under a context manager (confidence 0.76). inferred supported analysis_f07f1c5b3429400e:block_7feaf3019dd3c4
c35 The analysis is static only: reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring and dynamic dispatch are not resolved. observed supported analysis_f07f1c5b3429400e:lim_1
c36 Install, run and build inference is partial and installation commands are not verified, so this asset contains no commands. observed supported analysis_f07f1c5b3429400e:lim_2
c37 Dependency records come only from requirements-style manifests (pyproject.toml dependency tables are not parsed); README claim extraction is line-based, so README-derived claims are author_claimed at best; the manifest's capability fields describe the analyzer, not the analyzed repository. observed supported analysis_f07f1c5b3429400e:lim_3, analysis_f07f1c5b3429400e:lim_4, analysis_f07f1c5b3429400e:lim_5
c38 A teaching claim states that static analysis cannot establish all dynamic dispatch, reflection, generated-code or runtime framework behavior. unresolved supported analysis_f07f1c5b3429400e:claim_7c9925f9c8f4
c39 A teaching claim also says no bounded static execution path is available, which conflicts with the five example path records listed; runtime flow stays unresolved in this asset. unresolved supported analysis_f07f1c5b3429400e:claim_4d30ade3e21e

Sources, rights and disclosure · attribution-license-templates/v0.1

Rights notice. Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.

Platform notice. GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.

How this page is produced. This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.

AI-assisted analysis. Reviewed by EVEMISS Technology through human–AI collaborative review. · Report a rights concern · Back to the overview