Skip to content

livery.extensions.coverage._parts

livery.extensions.coverage._parts

The parts the measurers hand over, and the union the gate job writes.

Every measurer hands the coverage extension its readings as parts in the line format (_format), one part per unit it measured, in one of two ways. A measurer that reads its measurement inside its own step leaves each unit's part in the workspace, under PARTS, as <measurer>/<unit>.json: the cmake extension's test does, for a native suite. A measurer whose run leaves data for later answers this extension's coverage.measurers query with a Reduction, which makes the parts when it is asked: the pytest extension does, for coverage.py's data. A check leg gathers both for each unit it ran; the gate job's union merges every leg's parts with the records' and writes the merged files to UNION, which the floors read. On a machine the floors' preview and the coverage pages read the parts the last run left, both ways.

native tells which units the reductions are asked for: every unit that holds the runtime's language; any other is native, and its measurer leaves its parts itself.

Classes:

Name Description
Reduction

How an extension reduces the data its measurer left to parts.

Unioned

What the gate job's union wrote: the merged files and the units they came from.

Functions:

Name Description
measurers_by_name

coverage.measurers' rule: each answering extension's reductions, by measurer.

reduced

What call, a reduction, returns; one that refuses stops the caller, named.

native

Whether package's suite is native, measured by its build's measurer.

part_files

Every part a measurer left under PARTS at root, in name order.

read_part

The part in the file path, decoded.

write_union

Write combined, the union of units' parts, to UNION; the path.

read_union

The union the gate job wrote at root; None when it wrote none.

Attributes:

Name Type Description
PARTS
UNION
MEASURERS Query[Mapping[str, Reduction]]

PARTS module-attribute

PARTS = '.workshop/coverage/parts'

UNION module-attribute

UNION = '.workshop/coverage/union.json'

MEASURERS module-attribute

MEASURERS: Query[Mapping[str, Reduction]] = Query('coverage.measurers')

Reduction

Bases: Protocol

How an extension reduces the data its measurer left to parts.

An extension answers coverage.measurers with a reduction for each measurer it reduces, by the measurer's name. Both methods return parts as JSON holds them, in the line format; a part off the format refuses, naming the reduction and the key. A reduction that cannot reduce what it finds raises ValueError naming the cause, and its caller stops on it.

Methods:

Name Description
leg

One part per unit, in the units' order, from the data a check leg left.

left

The parts of the data the measurer's last run on a machine left at root.

leg

leg(root: Path, units: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]

One part per unit, in the units' order, from the data a check leg left.

Each unit is {"unit": <its path>, "tests": <the prefix its own tests' contexts start with>, "within": [<the path prefixes of its closure>]}, and a unit without within takes every file. A unit's part holds the files of its closure the data names, each as the unit's own tests and the code outside every test reached it, and names the contexts that reached each line wherever the data names a test. The record numbers the contexts when it stores the part, so a reduction numbers them as it likes.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def leg(
    self, root: Path, units: Sequence[Mapping[str, Any]]
) -> list[dict[str, Any]]:
    """One part per unit, in the units' order, from the data a check leg left.

    Each unit is ``{"unit": <its path>, "tests": <the prefix its own
    tests' contexts start with>, "within": [<the path prefixes of its
    closure>]}``, and a unit without ``within`` takes every file. A
    unit's part holds the files of its closure the data names, each
    as the unit's own tests and the code outside every test reached
    it, and names the contexts that reached each line wherever the
    data names a test. The record numbers the contexts when it
    stores the part, so a reduction numbers them as it likes.
    """
    ...

left

left(root: Path) -> list[dict[str, Any]]

The parts of the data the measurer's last run on a machine left at root.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def left(self, root: Path) -> list[dict[str, Any]]:
    """The parts of the data the measurer's last run on a machine left at *root*."""
    ...

Unioned dataclass

Unioned(files: Mapping[str, Merged], units: tuple[str, ...], left_out: tuple[str, ...] = ())

What the gate job's union wrote: the merged files and the units they came from.

Attributes:

Name Type Description
files Mapping[str, Merged]

Each file's merged reading, by its path from the root.

units tuple[str, ...]

The units whose parts the union merged.

left_out tuple[str, ...]

A line for each reading the merge left out.

files instance-attribute

files: Mapping[str, Merged]

units instance-attribute

units: tuple[str, ...]

left_out class-attribute instance-attribute

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

measurers_by_name

measurers_by_name(answers: Mapping[str, Any], lookup: object) -> dict[str, Reduction]

coverage.measurers' rule: each answering extension's reductions, by measurer.

Raises:

Type Description
ValueError

when two extensions reduce one measurer, naming both.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def measurers_by_name(
    answers: Mapping[str, Any], lookup: object
) -> dict[str, Reduction]:
    """``coverage.measurers``' rule: each answering extension's reductions, by measurer.

    Raises:
        ValueError: when two extensions reduce one measurer, naming both.
    """
    del lookup
    found: dict[str, Reduction] = {}
    by: dict[str, str] = {}
    for extension, reductions in answers.items():
        for name, reduction in dict(reductions).items():
            if name in found:
                raise ValueError(
                    f"{by[name]} and {extension} both reduce the {name} measurer;"
                    " one extension reduces each"
                )
            found[str(name)] = reduction
            by[str(name)] = extension
    return found

reduced

reduced(call: Callable[[], list[dict[str, Any]]], source: str) -> list[dict[str, Any]]

What call, a reduction, returns; one that refuses stops the caller, named.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def reduced(
    call: Callable[[], list[dict[str, Any]]], source: str
) -> list[dict[str, Any]]:
    """What *call*, a reduction, returns; one that refuses stops the caller, named."""
    try:
        return call()
    except ValueError as error:
        fail(f"coverage: {source} refuses: {error}")

native

native(package: Package) -> bool

Whether package's suite is native, measured by its build's measurer.

A suite is native when its package does not hold the runtime's language. A native suite's measurer leaves its parts itself, so the reductions are never asked for it, and a package whose suite left no part is not measured. The workspace's own tests hold the root's set, so they are native while that set does not hold the runtime's language.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def native(package: Package) -> bool:
    """Whether *package*'s suite is native, measured by its build's measurer.

    A suite is native when its package does not hold the runtime's
    language. A native suite's measurer leaves its parts itself, so the
    reductions are never asked for it, and a package whose suite left
    no part is not measured. The workspace's own tests hold the root's
    set, so they are native while that set does not hold the runtime's
    language.
    """
    from livery.workshop import holds_runtime_language

    return not holds_runtime_language(package)

part_files

part_files(root: Path) -> list[Path]

Every part a measurer left under PARTS at root, in name order.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def part_files(root: Path) -> list[Path]:
    """Every part a measurer left under `PARTS` at *root*, in name order."""
    return sorted((root / PARTS).glob("*/*.json"))

read_part

read_part(path: Path, root: Path) -> Part

The part in the file path, decoded.

Raises:

Type Description
PartError

when the file does not parse, or holds a part off the format; the message names the file from root and the key at fault. OtherVersion, one of them, names a part of another format version.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def read_part(path: Path, root: Path) -> Part:
    """The part in the file *path*, decoded.

    Raises:
        PartError: when the file does not parse, or holds a part off
            the format; the message names the file from *root* and the
            key at fault. ``OtherVersion``, one of them, names a part of
            another format version.
    """
    source = path.relative_to(root).as_posix()
    try:
        raw = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError) as error:
        raise PartError(f"{source}: the part does not parse ({error})") from None
    return decode(raw, source=source)

write_union

write_union(root: Path, combined: Combined, units: Sequence[str]) -> Path

Write combined, the union of units' parts, to UNION; the path.

The merged files are grouped into one part per measurer, each numbering combined's contexts, so the file reads back with the line format's own reader.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def write_union(root: Path, combined: Combined, units: Sequence[str]) -> Path:
    """Write *combined*, the union of *units*' parts, to `UNION`; the path.

    The merged files are grouped into one part per measurer, each
    numbering *combined*'s contexts, so the file reads back with the
    line format's own reader.
    """
    by_measurer: dict[Measurer, dict[str, Any]] = {}
    for name, merged in combined.files.items():
        by_measurer.setdefault(merged.measurer, {})[name] = merged.entry
    parts = [
        encode(Part(".", measurer, files, combined.contexts))
        for measurer, files in sorted(
            by_measurer.items(), key=lambda item: item[0].identity
        )
    ]
    path = root / UNION
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {
                "format": FORMAT,
                "units": sorted(set(units)),
                "parts": parts,
                "left-out": list(combined.left_out),
            },
            sort_keys=True,
        ),
        encoding="utf-8",
    )
    return path

read_union

read_union(root: Path) -> Unioned | None

The union the gate job wrote at root; None when it wrote none.

Raises:

Type Description
PartError

when the file is not a union this workshop wrote, naming the file and the key at fault.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_parts.py
def read_union(root: Path) -> Unioned | None:
    """The union the gate job wrote at *root*; ``None`` when it wrote none.

    Raises:
        PartError: when the file is not a union this workshop wrote,
            naming the file and the key at fault.
    """
    path = root / UNION
    if not path.is_file():
        return None
    try:
        raw: Any = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError) as error:
        raise PartError(f"{UNION}: the union does not parse ({error})") from None
    parts = raw.get("parts") if isinstance(raw, dict) else None
    units = raw.get("units") if isinstance(raw, dict) else None
    if not isinstance(parts, list) or not isinstance(units, list):
        raise PartError(f"{UNION}: holds no parts and units; a union writes both")
    files: dict[str, Merged] = {}
    for index, item in enumerate(parts):
        part = decode(item, source=f"{UNION}: parts[{index}]")
        for name, entry in part.files.items():
            files[name] = Merged(part.measurer, entry, ())
    left_out: Any = raw.get("left-out", [])
    return Unioned(
        files,
        tuple(str(unit) for unit in units),
        tuple(str(line) for line in left_out) if isinstance(left_out, list) else (),
    )