Skip to content

Data files

vfy reads and writes Coverage.py schema-7 SQLite files. The default file is .coverage. COVERAGE_FILE, --data-file, or run:data_file selects another basename.

Stored information

The database stores measured paths, packed line numbers or branch arcs, static and dynamic contexts, file-tracer plug-in names, collection mode, and schema metadata. Writes retain the recorded collection mode.

Semantic tables

A decision-enabled run (--cov-decisions, vfy coverage run --decisions, or [tool.vfy.run] decisions = true) adds these tables to the same schema-7 database:

Table Contents
vfy_decision Stable decision key, canonical path, source digest, kind, expression, Boolean logic, condition lines, and source range
vfy_condition Atomic condition index and source range for each decision
vfy_observation Context, tri-state runtime vector, and decision outcome, deduplicated by identity
vfy_path_decision Named decision identity and source range for match, exception dispatch (including except*), cancellation, and value selection
vfy_path_outcome Ordered typed outcomes, source ranges, and handler body ranges
vfy_path_observation Context and observed named outcome, deduplicated by identity

The Boolean and path tables share a source digest for each measured path; a file can have either or both families. Reading or combining different digests for one path fails even when the revisions define different families. A table is written only when its decision definitions are present. A Coverage.py reader ignores these tables and reads file, line_bits, arc, context, and tracer as usual.

vfy commits ordinary coverage and semantic data in one replacement transaction. It validates the full dataset before replacing the file, so a failed validation leaves the previous file in place.

Compatibility with Coverage.py

Schema 7 is Coverage.py's internal database format, not a public interchange standard. vfy rejects other schema versions instead of guessing.

vfy reads and reports Coverage.py schema-7 data. Interchange is tested against Coverage.py 7.15.4; a matching schema number alone does not establish compatibility with another release. See the compatibility matrix.

Parallel shards

Parallel files use the configured basename plus a process-specific suffix, such as .coverage.hostname.pid.token.

vfy coverage combine checks the schema, mode, and tracer of every shard before it writes anything, then replaces the output atomically. Line and branch data can't be merged.

Shards are removed only after the output is replaced. If cleanup fails, the output is still valid and the command reports the leftover shard. --keep skips cleanup.

[paths] groups and the controller/worker root pair share one path remapper. It tries groups in order and applies a mapping only when the mapped local file exists. Local shards and remote pytest-xdist payloads follow the same rules.

Private serialized bytes

CoverageData.dumps() writes a vfy-only format for moving data between matching vfy builds. It is not Coverage.py's dumps format and doesn't replace schema-7 interchange. A round trip preserves coverage and semantic data. An invalid payload leaves the destination unchanged.

CoverageData.update() validates the complete merge before changing its destination. Measurements for paths mapped to the same filename are merged when compatible. See CoverageData for in-memory mutation and query methods.

Corruption and schema errors

Malformed SQLite, missing schema metadata, unsupported schema versions, conflicting tracers, and mixed line and branch shards raise explicit data errors. A failed validation never partly replaces the output file.