an.bench.paths#

Where the bench reads its corpus from and writes its ledger to.

One module owns every path so the “bench needs a source checkout” constraint is stated once, with a typed error, rather than surfacing as a FileNotFoundError from inside shutil.copytree.

Module Attributes

`LEDGER_DIRNAME`	Ledger rows live here, one file per (date, commit).
`GOLDEN_DIRNAME`	Golden frames (an#38 fills this; the path convention ships now so the cassette work and the corpus work do not have to agree on it later).

Functions

`git_state`([root])	`sha` / `branch` / `dirty` for the checkout, or ``None``s off-git.
`golden_dir`([root])	The golden-frame directory (an#38).
`golden_path`(scene, frame_key, chromium_build, *)	Where one golden frame lives.
`ledger_dir`([root])	The ledger directory, created if absent.
`ledger_path`(*[, root, git])	`<date>-<sha>[-dirty].json`.
`repo_root`()	The source checkout `an` was imported from.

Exceptions

BenchLayoutError

The bench was run somewhere it cannot find the corpus.

exception an.bench.paths.BenchLayoutError[source]#

Bases: RuntimeError

The bench was run somewhere it cannot find the corpus.

an.bench.paths.GOLDEN_DIRNAME: str = 'misc/bench/golden'#: Golden frames (an#38 fills this; the path convention ships now so the cassette work and the corpus work do not have to agree on it later).

an.bench.paths.LEDGER_DIRNAME: str = 'misc/bench/ledger'#: Ledger rows live here, one file per (date, commit). Append-only by convention: an existing row is evidence about a commit, and editing it rewrites history that an bench --compare (an#40) reads as fact.

an.bench.paths.git_state(root=None)[source]#

sha / branch / dirty for the checkout, or ``None``s off-git.

Return type:: dict

an.bench.paths.golden_dir(root=None)[source]#

The golden-frame directory (an#38).

Return type:: Path

an.bench.paths.golden_path(scene, frame_key, chromium_build, *, root=None)[source]#

Where one golden frame lives.

Keyed on the Chromium build alone — no platform or arch segment. The cross-architecture verdict measured those segments to be inert (zero differing pixels and zero differing PNG bytes across arm64 macOS, x86-64 Linux and arm64 Linux, across two different SwiftShader JIT backends), so carrying them would force one committed copy per platform for no information. What the convention keeps is its real benefit: a Playwright bump becomes a new path requiring a deliberate re-bless rather than a red test with no explanation.

Return type:: Path

>>> golden_path("s", "f0", "140.0.7339.16").name
'f0-chromium140.0.7339.16.png'

an.bench.paths.ledger_dir(root=None)[source]#

The ledger directory, created if absent.

Return type:: Path

an.bench.paths.ledger_path(*, root=None, git=None)[source]#

<date>-<sha>[-dirty].json.

The -dirty suffix is not decoration: a row measured against uncommitted edits describes no commit, and a filename that claims one would be read by an#40 as that commit’s evidence.

Return type:: Path

>>> ledger_path(git={"sha": "abc1234def", "dirty": True}).name.endswith("-dirty.json")
True

an.bench.paths.repo_root()[source]#

The source checkout an was imported from.

Raises rather than returning a plausible-but-wrong path, because the failure it guards is running the bench against an installed wheel: the corpus lives under misc/bench/, which is not packaged, so the first symptom would be a missing-fixture error three frames deep.

The checkout’s folder name is not asserted: a git worktree or a clone under another name is still a source checkout.

Return type:: Path

>>> (repo_root() / "an" / "bench" / "paths.py").is_file()
True