Skip to content

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 whose counts is presence; counts: [line, runs] pairs for one whose counts is counts, 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?]. to is 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; index is the branch's place among its line's; taken how many times it ran; why the sentence that says why the branch would not run, which a page shows while it never did, or a tag: waived for a branch the source waives, counted as taken, throw for 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 whose columns is true: each stretch of code it counts on its own, such as the two arms of an if written 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 leaves ranges out.
  • reached: the contexts that reached each line, only where the measurer recorded them. sets are sets of indexes into the part's contexts, each as pack_set writes it: its first index, then for each next index how many indexes it skips past the one before, in decimal, comma-separated. 0,0,297 is the set of 0, 1 and 299, and the empty string is the empty set; each set has that one spelling. lines pairs 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: 1-12,15,17-40; empty for none.

parse_ranges

The lines a range string names.

pack_set

A set of indexes as the format writes it: 0,0,297 for 0, 1 and 299.

unpack_set

The indexes in text, a set as pack_set writes it.

digest

The git blob id of content as text: what a part's digest names.

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 (start, end) pairs.

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 of them.

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

FORMAT module-attribute

FORMAT = 3

PRESENCE module-attribute

PRESENCE = 'presence'

COUNTS module-attribute

COUNTS = 'counts'

TARGETS module-attribute

TARGETS = 'targets'

INDEXES module-attribute

INDEXES = 'indexes'

NO_BRANCHES module-attribute

NO_BRANCHES = 'none'

LINES module-attribute

LINES = 'lines'

BRANCHES module-attribute

BRANCHES = 'branches'

WAIVED module-attribute

WAIVED = 'waived'

THROW module-attribute

THROW = 'throw'

Lines module-attribute

Lines = frozenset[int]

KeyPath module-attribute

KeyPath = tuple[str | int, ...]

PartError

Bases: ValueError

A part off the line format: the message names its source and the key.

OtherVersion

OtherVersion(source: str, version: object)

Bases: PartError

A part of another format version, which this reader does not read.

Attributes:

Name Type Description
version

The version the part names.

Name source and the version it holds.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def __init__(self, source: str, version: object) -> None:
    """Name *source* and the *version* it holds."""
    self.version = version
    super().__init__(
        f"{source}: a part of format {version!r}; this workshop reads"
        f" format {FORMAT}"
    )

version instance-attribute

version = version

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: coverage.py, gcov.

version str

Its version, 7.16.2; empty when the reading does not say.

runtime str

What it ran on, CPython 3.14; empty for none.

counts str

presence when it reads whether a line ran, counts when it reads how many times.

branches str

targets when it names the line each branch jumps to, indexes when it numbers a line's branches, none when it reads no branch by name.

regions tuple[str, ...]

The kinds of region it names: function, class.

judges tuple[str, ...]

What its figure judges: lines, and branches as well for coverage.py.

columns bool

Whether it reads columns, so its readings hold ranges: llvm-cov does; coverage.py and gcov do not.

name instance-attribute

name: str

version class-attribute instance-attribute

version: str = ''

runtime class-attribute instance-attribute

runtime: str = ''

counts class-attribute instance-attribute

counts: str = PRESENCE

branches class-attribute instance-attribute

branches: str = NO_BRANCHES

regions class-attribute instance-attribute

regions: tuple[str, ...] = ()

judges class-attribute instance-attribute

judges: tuple[str, ...] = (LINES,)

columns class-attribute instance-attribute

columns: bool = False

identity property

identity: tuple[str, str, str]

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.

label property

label: str

The measurer as a page names it: coverage.py 7.16.2 on CPython 3.14.

Branch dataclass

Branch(source: int, target: int | None, index: int, taken: int, why: str = '')

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: waived or throw.

source instance-attribute

source: int

target instance-attribute

target: int | None

index instance-attribute

index: int

taken instance-attribute

taken: int

why class-attribute instance-attribute

why: str = ''

Region dataclass

Region(kind: str, name: str, start: int, lines: Lines, calls: int | None = None)

A function or a class.

Attributes:

Name Type Description
kind str

function or class.

name str

Its qualified name: Graph.walk.

start int

The line it starts on, its def or class line.

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.

kind instance-attribute

kind: str

name instance-attribute

name: str

start instance-attribute

start: int

lines instance-attribute

lines: Lines

calls class-attribute instance-attribute

calls: int | None = None

Range dataclass

Range(start_line: int, start_column: int, end_line: int, end_column: int, count: int = 0)

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.

start_line instance-attribute

start_line: int

start_column instance-attribute

start_column: int

end_line instance-attribute

end_line: int

end_column instance-attribute

end_column: int

count class-attribute instance-attribute

count: int = 0

extent property

extent: tuple[int, int, int, int]

Where it is: its start line and column, then its end line and column.

shown property

shown: str

Where it is as a refusal names it: 6:21-6:37.

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.

digest instance-attribute

digest: str

statements class-attribute instance-attribute

statements: Lines = frozenset()

counts class-attribute instance-attribute

counts: Mapping[int, int] = field(default_factory=dict)

excluded class-attribute instance-attribute

excluded: Lines = frozenset()

spans class-attribute instance-attribute

spans: tuple[tuple[int, int], ...] = ()

branches class-attribute instance-attribute

branches: tuple[Branch, ...] = ()

branch_counts class-attribute instance-attribute

branch_counts: tuple[tuple[int, int, int], ...] = ()

regions class-attribute instance-attribute

regions: tuple[Region, ...] = ()

reached class-attribute instance-attribute

reached: Mapping[int, Lines] = field(default_factory=dict)

ranges class-attribute instance-attribute

ranges: tuple[Range, ...] = ()

executed property

executed: Lines

The statements that ran.

missing property

missing: Lines

The statements that never ran.

partial property

partial: Lines

The lines that ran with a branch, or some of their code, that never did.

Part dataclass

Part(unit: str, measurer: Measurer, files: Mapping[str, Entry], contexts: tuple[str, ...] = ())

One measurer's reading of one unit.

Attributes:

Name Type Description
unit str

The unit read: a suite's path, or . for the whole data a run left.

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 reached indexes name; the empty string is the context outside every test.

unit instance-attribute

unit: str

measurer instance-attribute

measurer: Measurer

files instance-attribute

files: Mapping[str, Entry]

contexts class-attribute instance-attribute

contexts: tuple[str, ...] = ()

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.

files class-attribute instance-attribute

files: int = 0

statements class-attribute instance-attribute

statements: int = 0

executed class-attribute instance-attribute

executed: int = 0

excluded class-attribute instance-attribute

excluded: int = 0

branches class-attribute instance-attribute

branches: int = 0

taken class-attribute instance-attribute

taken: int = 0

partial class-attribute instance-attribute

partial: int = 0

covered class-attribute instance-attribute

covered: int = 0

coverable class-attribute instance-attribute

coverable: int = 0

missing property

missing: int

The statements that never ran.

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__

__add__(other: Numbers) -> Numbers

The numbers of both, added field by field.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def __add__(self, other: Numbers) -> Numbers:
    """The numbers of both, added field by field."""
    return Numbers(
        self.files + other.files,
        self.statements + other.statements,
        self.executed + other.executed,
        self.excluded + other.excluded,
        self.branches + other.branches,
        self.taken + other.taken,
        self.partial + other.partial,
        self.covered + other.covered,
        self.coverable + other.coverable,
    )

Merged dataclass

Merged(measurer: Measurer, entry: Entry, units: tuple[str, ...])

One file's readings, merged.

Attributes:

Name Type Description
measurer Measurer

The measurer whose readings merged.

entry Entry

The merged reading.

units tuple[str, ...]

The units whose readings merged, in the order met.

measurer instance-attribute

measurer: Measurer

entry instance-attribute

entry: Entry

units instance-attribute

units: tuple[str, ...]

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' reached indexes name, sorted.

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.

files instance-attribute

files: Mapping[str, Merged]

contexts instance-attribute

contexts: tuple[str, ...]

left_out instance-attribute

left_out: tuple[str, ...]

carried class-attribute instance-attribute

carried: int = 0

shown

shown(percent: float, precision: int = 0) -> str

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
def shown(percent: float, precision: int = 0) -> str:
    """*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.
    """
    near = 1.0 / 10**precision
    if 0 < percent < near:
        percent = near
    elif 100.0 - near < percent < 100:
        percent = 100.0 - near
    else:
        percent = round(percent, precision)
    return f"{percent:.{precision}f}"

numbers

numbers(entry: Entry, measurer: Measurer) -> 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
def numbers(entry: Entry, measurer: Measurer) -> 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.
    """
    executed = entry.executed
    missing = entry.statements - executed
    branches = len(entry.branches) + sum(total for _, total, _ in entry.branch_counts)
    taken = sum(1 for branch in entry.branches if branch.taken > 0) + sum(
        min(ran, total) for _, total, ran in entry.branch_counts
    )
    partial = sum(
        1
        for branch in entry.branches
        if branch.taken == 0 and branch.source not in missing
    ) + sum(
        total - ran
        for line, total, ran in entry.branch_counts
        if ran < total and line not in missing
    )
    judged = BRANCHES in measurer.judges
    return Numbers(
        files=1,
        statements=len(entry.statements),
        executed=len(executed),
        excluded=len(entry.excluded),
        branches=branches,
        taken=taken,
        partial=partial,
        covered=len(executed) + (taken if judged else 0),
        coverable=len(entry.statements) + (branches if judged else 0),
    )

narrowed

narrowed(entry: Entry, keep: Callable[[int], bool]) -> Entry

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
def narrowed(entry: Entry, keep: Callable[[int], bool]) -> Entry:
    """*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.
    """
    return Entry(
        digest=entry.digest,
        statements=frozenset(line for line in entry.statements if keep(line)),
        counts={line: ran for line, ran in entry.counts.items() if keep(line)},
        excluded=frozenset(line for line in entry.excluded if keep(line)),
        spans=tuple(span for span in entry.spans if keep(span[0])),
        branches=tuple(branch for branch in entry.branches if keep(branch.source)),
        branch_counts=tuple(item for item in entry.branch_counts if keep(item[0])),
        reached={line: held for line, held in entry.reached.items() if keep(line)},
        ranges=tuple(item for item in entry.ranges if keep(item.start_line)),
    )

region_rows

region_rows(entry: Entry, kind: str) -> list[tuple[Region | None, Entry]]

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
def region_rows(entry: Entry, kind: str) -> list[tuple[Region | None, Entry]]:
    """*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.
    """
    regions = [region for region in entry.regions if region.kind == kind]
    inside: set[int] = set()
    for region in regions:
        inside.update(region.lines)
    rows: list[tuple[Region | None, Entry]] = [
        (region, narrowed(entry, region.lines.__contains__)) for region in regions
    ]
    rows.append((None, narrowed(entry, lambda line: line not in inside)))
    return rows

ranges

ranges(lines: Iterable[int]) -> str

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
def ranges(lines: Iterable[int]) -> str:
    """*lines* as a range string: ``1-12,15,17-40``; empty for none."""
    ordered = sorted(set(lines))
    found: list[str] = []
    index = 0
    while index < len(ordered):
        start = end = ordered[index]
        while index + 1 < len(ordered) and ordered[index + 1] == end + 1:
            index += 1
            end = ordered[index]
        found.append(str(start) if start == end else f"{start}-{end}")
        index += 1
    return ",".join(found)

parse_ranges

parse_ranges(text: str) -> Lines

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
def parse_ranges(text: str) -> Lines:
    """The lines a range string names.

    Raises:
        ValueError: when a piece is not a line or a range of lines,
            naming the piece.
    """
    found: set[int] = set()
    for piece in text.split(","):
        if not piece and text == "":
            continue
        first, dash, last = piece.partition("-")
        if not first.isdigit() or (dash and not last.isdigit()):
            raise ValueError(f"{piece!r} is not a line or a range of lines")
        start, end = int(first), int(last) if dash else int(first)
        if start < 1 or end < start:
            raise ValueError(f"{piece!r} is not a range of lines from 1 up")
        found.update(range(start, end + 1))
    return frozenset(found)

pack_set

pack_set(indexes: Iterable[int]) -> str

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
def pack_set(indexes: Iterable[int]) -> str:
    """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.
    """
    previous = -1
    gaps: list[str] = []
    for value in sorted(set(indexes)):
        gaps.append(str(value - previous - 1))
        previous = value
    return ",".join(gaps)

unpack_set

unpack_set(text: str) -> Lines

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
def unpack_set(text: str) -> Lines:
    """The indexes in *text*, a set as `pack_set` writes it.

    Raises:
        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.
    """
    if not text:
        return frozenset()
    found: set[int] = set()
    previous = -1
    for piece in text.split(","):
        if not (piece.isdigit() and piece.isascii()) or (
            piece[0] == "0" and len(piece) > 1
        ):
            raise ValueError(_misspelled(text, piece, previous))
        previous += int(piece) + 1
        found.add(previous)
    return frozenset(found)

digest

digest(content: bytes) -> str

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
def digest(content: bytes) -> str:
    """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.
    """
    text = content.replace(b"\r\n", b"\n")
    header = f"blob {len(text)}\0".encode("ascii")
    return hashlib.sha1(header + text, usedforsecurity=False).hexdigest()

encode

encode(part: Part) -> dict[str, Any]

part as JSON holds it, every list in its one order.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def encode(part: Part) -> dict[str, Any]:
    """*part* as JSON holds it, every list in its one order."""
    measurer = part.measurer
    files: dict[str, Any] = {}
    for name in sorted(part.files):
        files[name] = _encoded_entry(part.files[name], measurer)
    return {
        "format": FORMAT,
        "unit": part.unit,
        "measurer": {
            "name": measurer.name,
            "version": measurer.version,
            "runtime": measurer.runtime,
            "counts": measurer.counts,
            "branches": measurer.branches,
            "regions": list(measurer.regions),
            "judges": list(measurer.judges),
            "columns": measurer.columns,
        },
        "contexts": list(part.contexts),
        "files": files,
    }

decode

decode(raw: object, *, source: str) -> Part

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
def decode(raw: object, *, source: str) -> Part:
    """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:
        OtherVersion: when the part is of another format version.
        PartError: when the part is off the format.
    """
    reader = _Reader(source)
    table = reader.table(raw, ())
    version = table.get("format")
    if version != FORMAT:
        raise OtherVersion(source, version)
    reader.known(table, (), ("format", "unit", "measurer", "contexts", "files"))
    unit = reader.text(table.get("unit"), ("unit",), empty=False)
    measurer = reader.measurer(table.get("measurer"), ("measurer",))
    contexts = reader.contexts(table.get("contexts", []), ("contexts",))
    files = {
        reader.file_name(name): reader.entry(
            value, ("files", name), measurer, len(contexts)
        )
        for name, value in reader.table(table.get("files"), ("files",)).items()
    }
    return Part(unit, measurer, files, tuple(contexts))

numbering

numbering(known: Sequence[str], contexts: Iterable[str]) -> tuple[str, ...]

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
def numbering(known: Sequence[str], contexts: Iterable[str]) -> tuple[str, ...]:
    """*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.
    """
    held = set(known)
    return (*known, *sorted(set(contexts) - held))

numbered

numbered(raw: Mapping[str, Any], known: Sequence[str], *, source: str) -> dict[str, Any]

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 renumbered does, naming source.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def numbered(
    raw: Mapping[str, Any], known: Sequence[str], *, source: str
) -> dict[str, Any]:
    """*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:
        PartError: as `renumbered` does, naming *source*.
    """
    reader = _Reader(source)
    table = reader.table(raw, ())
    own = reader.contexts(table.get("contexts", []), ("contexts",))
    return renumbered(table, numbering(known, own), source=source)

renumbered

renumbered(raw: Mapping[str, Any], order: Sequence[str], *, source: str) -> dict[str, Any]

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 reached are off the format. Each names source.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def renumbered(
    raw: Mapping[str, Any], order: Sequence[str], *, source: str
) -> dict[str, Any]:
    """*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:
        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 ``reached`` are off the format. Each names
            *source*.
    """
    reader = _Reader(source)
    table = reader.table(raw, ())
    contexts = reader.contexts(table.get("contexts", []), ("contexts",))
    wanted = reader.contexts(list(order), ("numbering",))
    place = {name: index for index, name in enumerate(wanted)}
    for index, name in enumerate(contexts):
        if name not in place:
            raise reader.refuse(
                ("contexts", index),
                f"is {name!r}, and the numbering drops it; a numbering only"
                " appends, so every context keeps its index",
            )
    moved = [place[name] for name in contexts]
    files: dict[str, Any] = {}
    for name, value in reader.table(table.get("files", {}), ("files",)).items():
        entry = reader.table(value, ("files", name))
        if entry.get("reached") is None:
            files[name] = entry
            continue
        path: KeyPath = ("files", name, "reached")
        held = reader.table(entry["reached"], path)
        reader.known(held, path, ("sets", "lines"))
        sets = [
            pack_set(moved[index] for index in found)
            for found in reader.sets(held, path, len(contexts))
        ]
        files[name] = {**entry, "reached": {**held, "sets": sets}}
    return {**table, "contexts": wanted, "files": files}

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
def 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*.
    """
    readings: dict[str, list[tuple[Part, Entry]]] = {}
    names: set[str] = set()
    for part in parts:
        if contexts:
            # A context that reached no line, a test that is gone, keeps
            # its index in its part's numbering and is no merged context.
            used: set[int] = set()
            for entry in part.files.values():
                for held in entry.reached.values():
                    used.update(held)
            names.update(part.contexts[index] for index in used)
        for name, entry in part.files.items():
            readings.setdefault(name, []).append((part, entry))
    numbered_by = tuple(sorted(names))
    index_of = {name: index for index, name in enumerate(numbered_by)}
    files: dict[str, Merged] = {}
    left_out: list[str] = []
    carried = 0
    for name in sorted(readings):
        at_checkout = (current or {}).get(name)
        chosen, others = _chosen(readings[name], at_checkout)
        kept = _reading(*chosen[0])
        kept_entry = chosen[0][1]
        at_current = [entry for _, entry in chosen]
        for part, entry in others:
            moved = None
            if source is not None and kept_entry.digest == at_checkout:
                moved = _carried(part, entry, chosen[0][0], at_current, source)
            if moved is None:
                left_out.append(
                    f"{name}: left out the reading of {_reading(part, entry)}; the"
                    f" union keeps the one of {kept}"
                )
                continue
            reading, total, dropped = moved
            left_out.append(
                f"{name}: carried the reading of {_reading(part, entry)} across the"
                f" change: {total - dropped} of {total} measured line(s) kept,"
                f" {dropped} dropped"
            )
            chosen.append((part, reading))
            carried += 1
        files[name] = Merged(
            measurer=chosen[0][0].measurer,
            entry=_merged(
                [
                    (
                        _reindexed(entry.reached, part.contexts, index_of)
                        if contexts
                        else {},
                        entry,
                    )
                    for part, entry in chosen
                ]
            ),
            units=tuple(dict.fromkeys(part.unit for part, _ in chosen)),
        )
    return Combined(files, numbered_by, tuple(left_out), carried)

unrun_columns

unrun_columns(entry: Entry) -> dict[int, tuple[tuple[int, int | None], ...]]

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
def unrun_columns(entry: Entry) -> dict[int, tuple[tuple[int, int | None], ...]]:
    """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.
    """
    by_line: dict[int, list[Range]] = {}
    for item in entry.ranges:
        for line in range(item.start_line, item.end_line + 1):
            by_line.setdefault(line, []).append(item)
    found: dict[int, tuple[tuple[int, int | None], ...]] = {}
    for line, held in sorted(by_line.items()):
        if all(item.count for item in held):
            continue
        spans = [
            (
                item.start_column if item.start_line == line else 1,
                item.end_column if item.end_line == line else None,
                item,
            )
            for item in held
        ]
        cuts = sorted(
            {start for start, _, _ in spans}
            | {end for _, end, _ in spans if end is not None}
        )
        unrun: list[tuple[int, int | None]] = []
        for place, start in enumerate(cuts):
            end = cuts[place + 1] if place + 1 < len(cuts) else None
            holding = [
                item
                for first, last, item in spans
                if first <= start
                and (last is None or (end is not None and last >= end))
            ]
            if not holding:
                continue
            inner = min(holding, key=_innermost)
            if inner.count:
                continue
            if unrun and unrun[-1][1] == start:
                unrun[-1] = (unrun[-1][0], end)
            else:
                unrun.append((start, end))
        if unrun:
            found[line] = tuple(unrun)
    return found

check_ranges

check_ranges(entry: Entry, text: str, *, source: str) -> None

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
def check_ranges(entry: Entry, text: str, *, source: str) -> None:
    """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:
        PartError: when a range starts or ends beyond the file's lines,
            or beyond its line's columns, naming *source* and the range.
    """
    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
    if lines and lines[-1] == "":
        lines.pop()
    widths = [len(line.encode("utf-8")) for line in lines]
    for index, item in enumerate(entry.ranges):
        problem = ""
        if item.end_line > len(widths):
            problem = f"the file has {len(widths)} lines"
        elif item.start_column > widths[item.start_line - 1] + 1:
            problem = (
                f"line {item.start_line} has {widths[item.start_line - 1]} columns"
            )
        elif item.end_column > widths[item.end_line - 1] + 1:
            problem = f"line {item.end_line} has {widths[item.end_line - 1]} columns"
        if problem:
            raise PartError(
                f"{source}: ranges[{index}]: {item.shown} lies outside the file:"
                f" {problem}"
            )

facts_name

facts_name(facts: Mapping[str, Any]) -> str

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
def facts_name(facts: Mapping[str, Any]) -> str:
    """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.
    """
    return digest(facts_text(facts).encode("utf-8"))

facts_text

facts_text(facts: Mapping[str, Any]) -> str

facts as one JSON text: keys sorted, no space between items.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def facts_text(facts: Mapping[str, Any]) -> str:
    """*facts* as one JSON text: keys sorted, no space between items."""
    return json.dumps(facts, sort_keys=True, separators=(",", ":"))

stored

stored(part: Part) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]

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
def stored(part: Part) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
    """*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.
    """
    full = encode(part)
    presence = part.measurer.counts == PRESENCE
    facts: dict[str, dict[str, Any]] = {}
    files: dict[str, Any] = {}
    for name, entry in full["files"].items():
        fixed, ran = _split(entry, presence=presence)
        if fixed:
            key = facts_name(fixed)
            facts[key] = fixed
            ran["facts"] = key
        files[name] = ran
    return {**full, "files": files}, facts

facts_names

facts_names(raw: Mapping[str, Any]) -> dict[str, str]

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
def facts_names(raw: Mapping[str, Any]) -> dict[str, str]:
    """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.
    """
    found: dict[str, str] = {}
    files = raw.get("files")
    if not isinstance(files, dict):
        return found
    for entry in cast("dict[str, Any]", files).values():
        if not isinstance(entry, dict):
            continue
        named = cast("dict[str, Any]", entry).get("facts")
        if isinstance(named, str) and named not in found:
            found[named] = str(cast("dict[str, Any]", entry).get("digest", ""))
    return found

from_stored

from_stored(raw: object, facts: Mapping[str, Any], *, source: str) -> Part

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.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_format.py
def from_stored(raw: object, facts: Mapping[str, Any], *, source: str) -> Part:
    """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:
        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.
    """
    reader = _Reader(source)
    table = reader.table(raw, ())
    version = table.get("format")
    if version != FORMAT:
        raise OtherVersion(source, version)
    measurer = reader.measurer(table.get("measurer"), ("measurer",))
    files = {
        name: _joined(reader, value, ("files", name), facts, measurer)
        for name, value in reader.table(table.get("files"), ("files",)).items()
    }
    return decode({**table, "files": files}, source=source)