livery.extensions.coverage._format¶
livery.extensions.coverage._format ¶
The line format, version 3: what one measurer read of one unit, file by file.
A part holds what one measurer read for one unit on one machine: a package's suite, or the whole data a run left. Every measurer reduces to it, whatever language it measures: coverage.py's arcs, gcov's counts, llvm-cov's regions and a Cobertura report each become a part, and the coverage pages draw parts alone. A part is JSON:
{"format": 3, "unit": "packages/workshop",
"measurer": {"name": "coverage.py", "version": "7.16.2",
"runtime": "CPython 3.14", "counts": "presence",
"branches": "targets", "regions": ["function", "class"],
"judges": ["lines", "branches"], "columns": false},
"contexts": ["", "packages/workshop/tests/test_graph.py::test_walk"],
"files": {"packages/workshop/src/livery/workshop/_graph.py": {
"digest": "<the file's git blob id>",
"statements": "1-12,15,17-40", "hits": "1-9,15,17-30",
"excluded": "41-48", "spans": [[20, 23]],
"branches": [[12, 13, 0, 1, "line 12 didn't jump to line 13 ..."],
[12, 15, 1, 0, "line 12 didn't jump to line 15 ..."]],
"regions": [["function", "Graph.walk", 41, "42-60"]],
"reached": {"sets": ["0,0"], "lines": [[9, 0]]}}}}
A file is named by its path from the workspace root with forward
slashes, whichever platform measured it. A set of lines is a range
string, 1-12,15,17-40. Per file:
digest: the git blob id of the content measured, read as text: its bytes with each CRLF as LF, the blob git stores for a text file, so a checkout with CRLF line endings and one with LF give one digest. Empty when the measurer could not read the file.statements: the lines that can run.hits: the statements that ran, for a measurer whosecountsispresence;counts:[line, runs]pairs for one whosecountsiscounts, a statement left out having run no time.excluded: the lines the source excludes from measuring.spans:[first, last]for each statement written over lines.branches:[from, to, index, taken, why?].tois the line the branch jumps to, a negative number for the exit of the function that starts on that line, or null for a measurer that numbers a line's branches instead;indexis the branch's place among its line's;takenhow many times it ran;whythe sentence that says why the branch would not run, which a page shows while it never did, or a tag:waivedfor a branch the source waives, counted as taken,throwfor the path an exception takes. The sentence depends on the source alone, so every reading of one content gives a branch the same one.branch-counts:[line, branches, taken]for a measurer that counts a line's branches without naming them.regions:[kind, name, start, lines, calls?], a function or a class: its first line, the lines of its body, and how many times it was called when the measurer counts calls.ranges:[start line, start column, end line, end column, count]for a measurer whosecolumnsis true: each stretch of code it counts on its own, such as the two arms of anifwritten on one line, and how many times it ran. A column counts bytes from 1, and the end column is the one after the stretch's last. A measurer without columns leavesrangesout.reached: the contexts that reached each line, only where the measurer recorded them.setsare sets of indexes into the part'scontexts, each aspack_setwrites it: its first index, then for each next index how many indexes it skips past the one before, in decimal, comma-separated.0,0,297is the set of 0, 1 and 299, and the empty string is the empty set; each set has that one spelling.linespairs a line with the index of its set.
A set holds digits and commas alone, never a letter. A forge's push protection refuses a push whose text matches the shape of an access token, and every such shape holds letters. A part holds thousands of sets: written in an encoding with letters, such as base64, their text can match a token's shape by chance.
A part names each context once, and its contexts are its
numbering: a set holds a context by its place in the list. A record
keeps a unit's numbering from one reading to the next (numbering): a
context keeps its index whether or not the next reading names it
again, and a context the record has not numbered yet takes the next
index. Two readings of a unit a run apart then keep a line's set of
tests byte for byte wherever the same tests reached it, and git can
store the second as a small difference from the first; a numbering
sorted afresh would move the index of every context after a new
test's. renumbered moves a part
to another numbering.
A record keeps each part in its stored form, which stored writes and
from_stored reads back. A file's fixed facts, what its content and
its measurer decide whatever ran, move to a table of their own, named
by the git blob id of the table's JSON (facts_name) and kept once
however many parts name it. The file keeps its digest, that name, and
what ran:
{"digest": "<the file's git blob id>", "facts": "<the facts' name>",
"hits": "1-9,15,17-30", "taken": "1,3-5",
"reached": {"sets": ["0,0"], "lines": [[9, 0]]}}
The facts hold statements, excluded and spans as a part
holds them, and branches, branch-counts, regions and
ranges without the number each item ends in: a branch's taken,
a count's taken, a region's calls, a range's count. What
ran is hits or counts and reached as a part holds them,
and each item of the facts' lists by its place in the list, counted
from 1: taken, the branches that ran, a range string of places for
a measurer that reads presence and [place, taken] pairs for one
that counts; counted, [place, taken] for each count of a
line's branches with any taken; calls, [place, calls] for each
region whose calls are counted; and range-counts, [place,
count] for each range that ran.
livery.extensions.coverage._format.decode reads a part and refuses one off the format, naming where it came from and the key; livery.extensions.coverage._format.encode writes one. livery.extensions.coverage._format.merge combines parts across units and legs, carrying a reading of a file's earlier content across the change to its current one where it can, livery.extensions.coverage._format.numbers counts a file as coverage.py counts it, and livery.extensions.coverage._format.region_rows narrows a file to its functions or classes.
Classes:
| Name | Description |
|---|---|
PartError |
A part off the line format: the message names its source and the key. |
OtherVersion |
A part of another format version, which this reader does not read. |
Measurer |
Who read a part, and what the reading holds. |
Branch |
One branch of a line. |
Region |
A function or a class. |
Range |
A stretch of code a measurer that reads columns counts on its own. |
Entry |
What a measurer read of one file. |
Part |
One measurer's reading of one unit. |
Numbers |
A file's or a region's numbers as coverage.py counts them; they add up. |
Merged |
One file's readings, merged. |
Combined |
Parts merged across units and legs. |
Functions:
| Name | Description |
|---|---|
shown |
percent as coverage.py prints it, without the percent sign. |
numbers |
entry's numbers, as coverage.py counts a file. |
narrowed |
entry narrowed to the lines keep holds, as coverage.py narrows a region. |
region_rows |
entry narrowed to each region of kind, then to the lines outside them all. |
ranges |
lines as a range string: |
parse_ranges |
The lines a range string names. |
pack_set |
A set of indexes as the format writes it: |
unpack_set |
The indexes in text, a set as |
digest |
The git blob id of content as text: what a part's |
encode |
part as JSON holds it, every list in its one order. |
decode |
Read raw, a part as JSON loads it, refusing one off the format. |
numbering |
known, then each of contexts it lacks, sorted: a numbering that only appends. |
numbered |
raw, a part as JSON holds it or in its stored form, numbered to extend known. |
renumbered |
raw, a part as JSON or in its stored form, its contexts numbered by order. |
merge |
Merge parts: each file's readings at one content and by one measurer. |
unrun_columns |
The columns of each line its ranges say never ran, as |
check_ranges |
Refuse a range of entry outside text, the content it was measured at. |
facts_name |
The name of a file's fixed facts: the git blob id of |
facts_text |
facts as one JSON text: keys sorted, no space between items. |
stored |
part in its stored form, and the fixed facts it names, by name. |
facts_names |
The fixed facts a part in its stored form names, each with a file's digest. |
from_stored |
Read raw, a part in its stored form, its files' fixed facts read from facts. |
Attributes:
| Name | Type | Description |
|---|---|---|
FORMAT |
|
|
PRESENCE |
|
|
COUNTS |
|
|
TARGETS |
|
|
INDEXES |
|
|
NO_BRANCHES |
|
|
LINES |
|
|
BRANCHES |
|
|
WAIVED |
|
|
THROW |
|
|
Lines |
|
|
KeyPath |
|
PartError ¶
Bases: ValueError
A part off the line format: the message names its source and the key.
OtherVersion ¶
Measurer
dataclass
¶
Measurer(name: str, version: str = '', runtime: str = '', counts: str = PRESENCE, branches: str = NO_BRANCHES, regions: tuple[str, ...] = (), judges: tuple[str, ...] = (LINES,), columns: bool = False)
Who read a part, and what the reading holds.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The measurer: |
version |
str
|
Its version, |
runtime |
str
|
What it ran on, |
counts |
str
|
|
branches |
str
|
|
regions |
tuple[str, ...]
|
The kinds of region it names: |
judges |
tuple[str, ...]
|
What its figure judges: |
columns |
bool
|
Whether it reads columns, so its readings hold ranges: llvm-cov does; coverage.py and gcov do not. |
identity
property
¶
What two readings of one file share to merge: name, version, runtime minor.
Two Python minors read one source's statements and branches apart, so a reading under 3.11 and one under 3.14 never merge.
Branch
dataclass
¶
One branch of a line.
Attributes:
| Name | Type | Description |
|---|---|---|
source |
int
|
The line the branch leaves. |
target |
int | None
|
The line it jumps to, a negative number for the exit of the function that starts on that line, or None when the measurer numbers branches instead. |
index |
int
|
Its place among its line's branches, from 0. |
taken |
int
|
How many times it ran. |
why |
str
|
The sentence that says why it would not run, shown while
it never did, or a tag: |
Region
dataclass
¶
A function or a class.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
|
name |
str
|
Its qualified name: |
start |
int
|
The line it starts on, its |
lines |
Lines
|
The lines of its body; a nested function's are its own. |
calls |
int | None
|
How many times it was called, when the measurer counts calls. |
Range
dataclass
¶
A stretch of code a measurer that reads columns counts on its own.
A column counts bytes from 1, and the end column is the one after
the stretch's last: Range(6, 21, 6, 37, 0) is the 16 bytes of
line 6 from column 21, which never ran.
Attributes:
| Name | Type | Description |
|---|---|---|
start_line |
int
|
The line it starts on. |
start_column |
int
|
The column it starts at. |
end_line |
int
|
The line it ends on. |
end_column |
int
|
The column after its last. |
count |
int
|
How many times it ran. |
extent
property
¶
Where it is: its start line and column, then its end line and column.
Entry
dataclass
¶
Entry(digest: str, statements: Lines = frozenset(), counts: Mapping[int, int] = dict(), excluded: Lines = frozenset(), spans: tuple[tuple[int, int], ...] = (), branches: tuple[Branch, ...] = (), branch_counts: tuple[tuple[int, int, int], ...] = (), regions: tuple[Region, ...] = (), reached: Mapping[int, Lines] = dict(), ranges: tuple[Range, ...] = ())
What a measurer read of one file.
Attributes:
| Name | Type | Description |
|---|---|---|
digest |
str
|
The git blob id of the content measured, its CRLF line endings read as LF; empty when the measurer could not read the file. |
statements |
Lines
|
The lines that can run. |
counts |
Mapping[int, int]
|
How many times each statement ran, the ones that ran alone; a presence measurer's are 1. |
excluded |
Lines
|
The lines the source excludes from measuring. |
spans |
tuple[tuple[int, int], ...]
|
Each statement written over several lines, its first and last line. |
branches |
tuple[Branch, ...]
|
The branches the measurer names, in line order. |
branch_counts |
tuple[tuple[int, int, int], ...]
|
For a measurer that counts a line's branches without naming them: the line, its branches, and how many of them ran. |
regions |
tuple[Region, ...]
|
The functions and classes. |
reached |
Mapping[int, Lines]
|
The contexts that reached each line, as indexes into the part's contexts; empty where none were recorded. |
ranges |
tuple[Range, ...]
|
The stretches of code a measurer that reads columns counts on its own, in the order of where they are. |
Part
dataclass
¶
One measurer's reading of one unit.
Attributes:
| Name | Type | Description |
|---|---|---|
unit |
str
|
The unit read: a suite's path, or |
measurer |
Measurer
|
Who read it. |
files |
Mapping[str, Entry]
|
What it read of each file, by the file's path from the workspace root with forward slashes. |
contexts |
tuple[str, ...]
|
The contexts a line's |
Numbers
dataclass
¶
Numbers(files: int = 0, statements: int = 0, executed: int = 0, excluded: int = 0, branches: int = 0, taken: int = 0, partial: int = 0, covered: int = 0, coverable: int = 0)
A file's or a region's numbers as coverage.py counts them; they add up.
Attributes:
| Name | Type | Description |
|---|---|---|
files |
int
|
How many files they count. |
statements |
int
|
The statements. |
executed |
int
|
The statements that ran. |
excluded |
int
|
The excluded lines. |
branches |
int
|
The branches. |
taken |
int
|
The branches that ran, a waived one among them. |
partial |
int
|
The branches that never ran from a line that did. |
covered |
int
|
What the figure counts as covered: the statements that ran, and the branches taken where the measurer judges them. |
coverable |
int
|
What the figure counts in all. |
Methods:
| Name | Description |
|---|---|
__add__ |
The numbers of both, added field by field. |
percent
property
¶
percent: float
The figure: what is covered over what can be, 100 when nothing can.
statements_percent
property
¶
statements_percent: float
The statements that ran over the statements, 100 when there are none.
branches_percent
property
¶
branches_percent: float
The branches taken over the branches, 100 when there are none.
__add__ ¶
The numbers of both, added field by field.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
Merged
dataclass
¶
Combined
dataclass
¶
Combined(files: Mapping[str, Merged], contexts: tuple[str, ...], left_out: tuple[str, ...], carried: int = 0)
Parts merged across units and legs.
Attributes:
| Name | Type | Description |
|---|---|---|
files |
Mapping[str, Merged]
|
Each file's merged reading, by path. |
contexts |
tuple[str, ...]
|
The contexts the merged readings' |
left_out |
tuple[str, ...]
|
A line for each reading left out of its file's merge, one taken at other content or by another measurer, and one for each reading carried across a change into it, saying how many of its measured lines were kept and dropped. |
carried |
int
|
How many readings were carried across a change. |
shown ¶
percent as coverage.py prints it, without the percent sign.
Rounded to precision decimals, except that only nothing is 0 and only everything is 100: 99.7 at precision 0 prints 99, and 0.2 prints 1.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
numbers ¶
entry's numbers, as coverage.py counts a file.
A branch counts as taken when it ran or the source waives it; a partial branch is one never taken from a line that ran. The figure counts the branches only where the measurer judges them: a native measurer's figure is its lines alone, and its branches reach the pages, never the floors.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
narrowed ¶
entry narrowed to the lines keep holds, as coverage.py narrows a region.
A branch belongs to the line it leaves and a range to the line it starts on, so a region keeps the branches its own lines leave and the ranges they start; the regions themselves go.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
region_rows ¶
entry narrowed to each region of kind, then to the lines outside them all.
The regions in the order the measurer names them, then None
with the lines outside every region of kind: a def or
class line counts there, since a region holds its body's lines
alone.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
ranges ¶
lines as a range string: 1-12,15,17-40; empty for none.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
parse_ranges ¶
The lines a range string names.
Raises:
| Type | Description |
|---|---|
ValueError
|
when a piece is not a line or a range of lines, naming the piece. |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
pack_set ¶
A set of indexes as the format writes it: 0,0,297 for 0, 1 and 299.
It sorts the indexes and writes the first, then for each next one how many indexes it skips past the one before, each number in decimal, comma-separated. The empty set is the empty string. The text holds digits and commas alone, and each set has this one spelling.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
unpack_set ¶
The indexes in text, a set as pack_set writes it.
Raises:
| Type | Description |
|---|---|
ValueError
|
when text is not that spelling, naming it: a number that is empty, holds anything but the digits 0 to 9, or starts with a 0 and has more digits; or a negative number, which takes the set to an index at or below the one before it. |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
digest ¶
The git blob id of content as text: what a part's digest names.
Each CRLF in content counts as LF, so the digest is the blob id git stores for a text file whatever line endings a checkout gives it: Git for Windows checks text out with CRLF, and a file measured there has the digest of the same file measured on Linux.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
encode ¶
part as JSON holds it, every list in its one order.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
decode ¶
Read raw, a part as JSON loads it, refusing one off the format.
source names where the part came from in every refusal, beside
the key at fault: files["a.py"].branches[2].
Raises:
| Type | Description |
|---|---|
OtherVersion
|
when the part is of another format version. |
PartError
|
when the part is off the format. |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
numbering ¶
known, then each of contexts it lacks, sorted: a numbering that only appends.
A record numbers a unit's contexts this way at every write, known being the numbering of the unit's row before it: each context keeps its index, a test that is gone among them, and each new one takes the next.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
numbered ¶
raw, a part as JSON holds it or in its stored form, numbered to extend known.
Its contexts take numbering of known and its own, so every
context of known keeps its index and its own new ones follow.
Raises:
| Type | Description |
|---|---|
PartError
|
as |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
renumbered ¶
raw, a part as JSON or in its stored form, its contexts numbered by order.
Each set of each file's reached names the contexts it named
before, each now by its place in order; a context order adds
names no line, and nothing else in raw changes. order names
each context once and keeps every context of raw: a numbering
only appends, so one that drops a context is refused, never
guessed.
Raises:
| Type | Description |
|---|---|
PartError
|
when order repeats a context or drops one of
raw's, naming it; when a set names an index past raw's
contexts, naming the file and the set; and when the
contexts or a |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
merge ¶
merge(parts: Iterable[Part], current: Mapping[str, str] | None = None, *, contexts: bool = True, source: Callable[[str], str] | None = None) -> Combined
Merge parts: each file's readings at one content and by one measurer.
current maps a file to its digest in the checkout. A file merges
the readings that share its current digest and one measurer
identity (livery.extensions.coverage._format.Measurer.identity),
the identity most readings carry winning; without a reading at the
current digest, the digest and identity most readings share win.
Every reading left out is named in left_out.
The merge: statements and excluded lines are the union, hits are
or-ed and counts added, a branch is one by its line and index with
its runs added and its sentence kept, a count of a line's branches
keeps the most taken, a region is one by its kind, name and start
with its calls added, a range is one by where it is with its counts
added, and the contexts that reached a line are the union, by name.
With contexts false the merge leaves the contexts out, for a
reader that counts alone: no merged reading holds a reached,
and the result names no context.
source gives a digest's text, its line endings LF, or empty text
when that content is not at hand. With it, a reading of a file at
another digest is carried across the change instead of left out,
when the kept readings are at the checkout's digest, the reading's
measurer identity is theirs, and both texts are at hand. The diff
between the two texts maps each line the change left in place to
its line in the checkout's content, and the reading keeps at the
mapped lines alone: its counts and the contexts that reached them,
where the line is a statement of the current content; a branch
whose two ends map to a branch the current content has, with its
runs; and a count of a line's branches where the current content
counts as many. The statements, the excluded lines, the spans, the
regions and the ranges are the content's facts, which the kept
readings supply. A carried reading joins the merge and is named in
left_out with how many of its measured lines were kept and how
many dropped, so a reading on a line the change touched or removed
is dropped by name, never moved by guess. A reading the carry does
not apply to is left out and named as without source.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 | |
unrun_columns ¶
The columns of each line its ranges say never ran, as (start, end) pairs.
A column belongs to the innermost range that holds it, the one that starts last, and of two that start together the one that ends first, as llvm-cov draws its regions; a column no range holds is not judged. Columns count bytes from 1, and a stretch's end is the column after its last, or None when it runs to the end of the line. A line with no such stretch is left out.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
check_ranges ¶
Refuse a range of entry outside text, the content it was measured at.
text's lines are counted as the pages count them, a CRLF or a lone CR ending a line as LF does, and each line's columns are its bytes in UTF-8, the end column one past the last.
Raises:
| Type | Description |
|---|---|
PartError
|
when a range starts or ends beyond the file's lines, or beyond its line's columns, naming source and the range. |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
facts_name ¶
The name of a file's fixed facts: the git blob id of facts_text of them.
A record that keeps the facts as a file of that text keeps them under the name git gives the file.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
facts_text ¶
facts as one JSON text: keys sorted, no space between items.
stored ¶
part in its stored form, and the fixed facts it names, by name.
A file with no fixed facts, one the measurer could not read, names
none. A measurer that reads presence keeps its branches that ran as
a range string of places while none ran more than once, which its
readings never do; [place, taken] pairs keep the rest.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
facts_names ¶
The fixed facts a part in its stored form names, each with a file's digest.
Each name maps to the digest of the first file that names it, for a
refusal to name the content whose facts are missing. A value off
the stored form names nothing here; from_stored refuses it.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
from_stored ¶
Read raw, a part in its stored form, its files' fixed facts read from facts.
facts maps a facts' name to the facts. Every refusal names
source and the key at fault, as decode's do.
Raises:
| Type | Description |
|---|---|
OtherVersion
|
when the part is of another format version. |
PartError
|
when a file names fixed facts facts does not hold, naming the facts and the file's content; when a place names no item of its facts; or when the part, its facts joined in, is off the format. |