Skip to content

livery.extensions.coverage._pages

livery.extensions.coverage._pages

Draw the site's coverage pages from the measured data, in the line format.

This extension adds a step to each of the docs extension's two phases in its [for.docs] table, so the pages are drawn only while docs is listed, for each package whose [docs] coverage names a report at TREE. pages_run, the docs phase's step, draws them before the site builds, from the data the last gate run left on this machine: the parts a native suite's measurer left in the workspace, and the parts each listed extension's reduction makes of its measurer's data, the pytest extension's of coverage.py's (_parts). redraw_run, the deploy phase's step, draws them again just before the site publishes, from main's coverage record on every check leg, read from their stored form with the fixed facts the record holds, as the legs made them.

The pages are drawn from parts in the line format (_format) by _render. Each package's index states its floor (_floors.floor_status).

Functions:

Name Description
pages_run

Draw the coverage pages from this machine's data: the docs phase's step.

redraw_run

Draw the coverage pages from main's coverage record: the deploy phase's step.

draw

Draw the pages of every package that declares a TREE report; the members.

declaring

The packages whose [docs] coverage names a report at TREE, in order.

render_coverage_pages

Draw each of packages' coverage pages from the measured data.

stored_rows

Every unit of main's record on each leg in labels, by leg; and the misses.

Attributes:

Name Type Description
TREE

TREE module-attribute

TREE = 'htmlcov'

pages_run

pages_run(ctx: PhaseContext) -> None

Draw the coverage pages from this machine's data: the docs phase's step.

Before the site builds, from the data the last gate run left; where no gate ran first, as in a CI job of its own, nothing is drawn and each page states the absence.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def pages_run(ctx: PhaseContext) -> None:
    """Draw the coverage pages from this machine's data: the docs phase's step.

    Before the site builds, from the data the last gate run left; where
    no gate ran first, as in a CI job of its own, nothing is drawn and
    each page states the absence.
    """
    draw(ctx.root, merged=False)

redraw_run

redraw_run(ctx: PhaseContext) -> None

Draw the coverage pages from main's coverage record: the deploy phase's step.

docs.publish runs it on the built site just before it publishes the site, in the merge point's gate job after the union wrote the record, and then puts each declared report's tree into the site. A failure here fails the publish; the verdict was given before it.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def redraw_run(ctx: PhaseContext) -> None:
    """Draw the coverage pages from main's coverage record: the deploy phase's step.

    ``docs.publish`` runs it on the built site just before it publishes
    the site, in the merge point's gate job after the union wrote the
    record, and then puts each declared report's tree into the site. A
    failure here fails the publish; the verdict was given before it.
    """
    draw(ctx.root, merged=True)

draw

draw(root: Path, *, merged: bool) -> list[str]

Draw the pages of every package that declares a TREE report; the members.

From main's coverage record with merged, else from the data the last gate run left on this machine (render_coverage_pages). A workspace where no package declares one draws nothing.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def draw(root: Path, *, merged: bool) -> list[str]:
    """Draw the pages of every package that declares a `TREE` report; the members.

    From main's coverage record with *merged*, else from the data the
    last gate run left on this machine (`render_coverage_pages`). A
    workspace where no package declares one draws nothing.
    """
    packages = declaring(root)
    if not packages:
        return []
    drawn = render_coverage_pages(root, packages, merged=merged)
    if drawn:
        print(f"  coverage: pages drawn for {', '.join(drawn)}")
    return drawn

declaring

declaring(root: Path) -> tuple[Package, ...]

The packages whose [docs] coverage names a report at TREE, in order.

Read from each package's contract, the table the docs extension owns and frames each declared report from.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def declaring(root: Path) -> tuple[Package, ...]:
    """The packages whose ``[docs] coverage`` names a report at `TREE`, in order.

    Read from each package's contract, the table the docs extension
    owns and frames each declared report from.
    """
    from livery.workshop import discover_packages, read_contract

    found: list[Package] = []
    for package in discover_packages(root):
        table = read_contract(package.directory).get("docs") or {}
        reports = table.get("coverage") if isinstance(table, dict) else None
        if isinstance(reports, list) and any(
            isinstance(entry, dict) and entry.get("path") == TREE for entry in reports
        ):
            found.append(package)
    return tuple(found)

render_coverage_pages

render_coverage_pages(root: Path, packages: tuple[Package, ...], *, merged: bool = False) -> list[str]

Draw each of packages' coverage pages from the measured data.

Each package's tree goes to its htmlcov directory, drawn from the parts of its files: main's record on every check leg with merged, and the data the last gate run left on this machine without it. A package no measurement reaches gets no tree, and its coverage page states the absence.

A measured file the checkout no longer has is red inside CI, where the measurement is the record of the tree being built; on a machine, whose data outlives a moved file until the next gate run, the package's index names it and the rest is drawn. A file whose content differs from the content measured keeps its numbers, and its page says it was measured at other content; a file measured at the checkout's content with a range outside its text refuses, naming the file and the range. Each package's index states its floor: the floor its contract names, the mark it ratchets to, read beside main's record, or that nothing judges it. Returns the members drawn.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def render_coverage_pages(
    root: Path, packages: tuple[Package, ...], *, merged: bool = False
) -> list[str]:
    """Draw each of *packages*' coverage pages from the measured data.

    Each package's tree goes to its ``htmlcov`` directory, drawn from
    the parts of its files: main's record on every check leg with
    *merged*, and the data the last gate run left on this machine
    without it. A package no measurement reaches gets no tree, and its
    coverage page states the absence.

    A measured file the checkout no longer has is red inside CI, where
    the measurement is the record of the tree being built; on a
    machine, whose data outlives a moved file until the next gate run,
    the package's index names it and the rest is drawn. A file whose
    content differs from the content measured keeps its numbers, and
    its page says it was measured at other content; a file measured at
    the checkout's content with a range outside its text refuses,
    naming the file and the range. Each package's index states its
    floor: the floor its contract names, the mark it ratchets to, read
    beside main's record, or that nothing judges it. Returns the
    members drawn.
    """
    from livery.extensions.coverage._floors import floor_status
    from livery.workshop import ci_run

    prefixes = tuple(f"{package.path}/" for package in packages)
    measured = _measured(root, prefixes, merged=merged)
    for miss in measured.misses:
        print(f"  coverage: {miss}")
    names = {name for part in measured.parts for name in part.files}
    digests = {
        name: digest((root / name).read_bytes())
        for name in sorted(names)
        if (root / name).is_file()
    }
    combined = merge(measured.parts, digests)
    for line in combined.left_out:
        print(f"  coverage: {line}")
    gone = sorted(name for name in combined.files if name not in digests)
    if gone and ci_run() is not None:
        fail(
            f"coverage: the measured data names {', '.join(gone)}, which the"
            " checkout does not have; inside CI the data is the record of the"
            " tree being built, so a file it names and the tree lacks is red"
        )
    for name in gone:
        print(
            f"  coverage: the local data names {name}, which the checkout no"
            " longer has; its package's index states the absence until"
            f" `{footman.prog()} check` measures again"
        )
    head = _head(root)
    marks = _marks_read(root, packages) if merged else None
    rendered: list[str] = []
    for package in packages:
        prefix = f"{package.path}/"
        drawn = tuple(
            _drawn(root, name, merged, digests[name])
            for name, merged in sorted(combined.files.items())
            if name.startswith(prefix) and name in digests
        )
        if not drawn:
            shutil.rmtree(package.directory / TREE, ignore_errors=True)
            print(
                f"  coverage: {package.member}: no measured data; its page states"
                " the absence"
            )
            continue
        notes = (*measured.notes, *((f"Drawn at commit {head[:12]}.",) if head else ()))
        render(
            package.directory / TREE,
            Report(
                title=package.path,
                files=drawn,
                contexts=combined.contexts,
                notes=notes,
                absent=tuple(name for name in gone if name.startswith(prefix)),
                floor=floor_status(package, marks),
            ),
        )
        rendered.append(package.member)
    return rendered

stored_rows

stored_rows(root: Path, labels: Sequence[str]) -> tuple[dict[str, dict[str, Unit]], list[str]]

Every unit of main's record on each leg in labels, by leg; and the misses.

A leg whose record cannot be read, or holds nothing, is a named miss, never a refusal: the pages draw what there is.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_pages.py
def stored_rows(
    root: Path, labels: Sequence[str]
) -> tuple[dict[str, dict[str, Unit]], list[str]]:
    """Every unit of main's record on each leg in *labels*, by leg; and the misses.

    A leg whose record cannot be read, or holds nothing, is a named
    miss, never a refusal: the pages draw what there is.
    """
    from livery.extensions.coverage._record import MAIN, recorded

    found: dict[str, dict[str, Unit]] = {}
    misses: list[str] = []
    for label in labels:
        held = recorded(root, leg=label)
        if held.failed:
            misses.append(
                f"{MAIN}/{label}: the record could not be read ({held.reason});"
                " the pages draw without it"
            )
            continue
        if not held.units:
            misses.append(f"{MAIN}/{label}: nothing recorded")
            continue
        found[label] = dict(held.units)
    return found, misses