Skip to content

livery.extensions.coverage._marks

livery.extensions.coverage._marks

The coverage marks: a package's high-water mark, and how it moves.

A package whose contract declares [coverage] floor = "auto-ratchet" is judged against the mark recorded on the CI state store instead of a committed number. Enforcement passes at the mark minus the package's epsilon ([coverage] epsilon, in percentage points, 0.5 when absent), and the mark ratchets up only when a run clears it by more than epsilon, so the scheduling wobble of a parallel suite neither fails the gate nor moves the mark. The first run records the mark and never judges; a store that cannot be read falls open with its reason and never writes, since a write from an unread state would erase the marks it could not see.

Lowering a mark is an explicit act: fm coverage.accept writes a dated, reasoned row, and the gate judges from it. Every row names the run or the person that wrote it, so the trail of a package's floor is readable on the store. Reach for livery.extensions.coverage._marks.marks to read the current marks and livery.extensions.coverage._marks.judge to decide a run.

Classes:

Name Description
Mark

A package's current mark and the row that set it.

Verdict

One package's answer under auto-ratchet.

Functions:

Name Description
marks

The current mark per package; (None, reason) when the store could not answer.

write_mark

Append one row setting package's mark; "" or why it was not written.

judge

Compare the measured packages against their marks; one verdict each.

render

One line for verdict: the measured value, the mark, the floor, the move.

Attributes:

Name Type Description
SERIES
AUTO_RATCHET
DEFAULT_EPSILON

SERIES module-attribute

SERIES = git.Series('coverage/marks', window=400, ci_only=False)

AUTO_RATCHET module-attribute

AUTO_RATCHET = 'auto-ratchet'

DEFAULT_EPSILON module-attribute

DEFAULT_EPSILON = 0.5

Mark dataclass

Mark(package: str, value: float, kind: str, by: str, reason: str, when: str)

A package's current mark and the row that set it.

Attributes:

Name Type Description
package str

The package path (packages/forge).

value float

The mark, in percent.

kind str

ratchet (a run raised it), first (a run recorded it), or accept (a person lowered it).

by str

The run id or the person that wrote the row.

reason str

The reason an accept gave; empty otherwise.

when str

When the row was written, ISO 8601.

package instance-attribute

package: str

value instance-attribute

value: float

kind instance-attribute

kind: str

by instance-attribute

by: str

reason instance-attribute

reason: str

when instance-attribute

when: str

Verdict dataclass

Verdict(package: str, measured: float, mark: Mark | None, epsilon: float)

One package's answer under auto-ratchet.

Attributes:

Name Type Description
package str

The package path.

measured float

The union's percentage for the package.

mark Mark | None

The current mark, or None when none is recorded.

epsilon float

The tolerance, in percentage points.

raises bool

Whether the run clears the mark by more than epsilon.

package instance-attribute

package: str

measured instance-attribute

measured: float

mark instance-attribute

mark: Mark | None

epsilon instance-attribute

epsilon: float

floor property

floor: float | None

The lowest percentage that passes, or None without a mark.

ok property

ok: bool

Whether the package passes: no mark yet, or at least the floor.

raises property

raises: bool

Whether the run sets a new mark: the first, or a clear rise.

marks

marks(root: Path) -> tuple[dict[str, Mark] | None, str]

The current mark per package; (None, reason) when the store could not answer.

An empty store is ({}, ""): the first run writes. A read the transport could not answer returns its reason, and a caller that would write refuses on it. A row that does not parse, is of another schema, or lacks a mark's fields is skipped, so one bad row disables nothing. The newest row per package is its mark.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_marks.py
def marks(root: Path) -> tuple[dict[str, Mark] | None, str]:
    """The current mark per package; ``(None, reason)`` when the store could not answer.

    An empty store is ``({}, "")``: the first run writes. A read the
    transport could not answer returns its reason, and a caller that
    would write refuses on it. A row that does not parse, is of
    another schema, or lacks a mark's fields is skipped, so one bad
    row disables nothing. The newest row per package is its mark.
    """
    found = SERIES.rows(state_store(root))
    if found.failed:
        return None, found.reason
    current: dict[str, Mark] = {}
    for row in found.rows:
        mark = _mark(row.data)
        if mark is not None:
            current.setdefault(mark.package, mark)
    return current, ""

write_mark

write_mark(root: Path, *, package: str, value: float, kind: str, by: str, reason: str = '') -> str

Append one row setting package's mark; "" or why it was not written.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_marks.py
def write_mark(
    root: Path,
    *,
    package: str,
    value: float,
    kind: str,
    by: str,
    reason: str = "",
) -> str:
    """Append one row setting *package*'s mark; ``""`` or why it was not written."""
    row = {
        "package": package,
        "value": round(value, 2),
        "kind": kind,
        "by": by,
        "reason": reason,
    }
    return SERIES.put(
        state_store(root),
        {_row_name(datetime.now(UTC), package): row},
        message=f"coverage mark: {package} {kind} {value:.2f} by {by}",
    )

judge

judge(measured: dict[str, float], current: dict[str, Mark], epsilons: dict[str, float]) -> list[Verdict]

Compare the measured packages against their marks; one verdict each.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_marks.py
def judge(
    measured: dict[str, float],
    current: dict[str, Mark],
    epsilons: dict[str, float],
) -> list[Verdict]:
    """Compare the measured packages against their marks; one verdict each."""
    return [
        Verdict(
            package=package,
            measured=percent,
            mark=current.get(package),
            epsilon=epsilons.get(package, DEFAULT_EPSILON),
        )
        for package, percent in sorted(measured.items())
    ]

render

render(verdict: Verdict) -> str

One line for verdict: the measured value, the mark, the floor, the move.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_marks.py
def render(verdict: Verdict) -> str:
    """One line for *verdict*: the measured value, the mark, the floor, the move."""
    if verdict.mark is None:
        return (
            f"  coverage {verdict.package}: {verdict.measured:.1f}% (no mark yet;"
            " this run records it)"
        )
    state = "" if verdict.ok else " BELOW THE FLOOR"
    line = (
        f"  coverage {verdict.package}: {verdict.measured:.1f}% (mark"
        f" {verdict.mark.value:.1f}% {verdict.mark.kind} by {verdict.mark.by},"
        f" floor {verdict.floor:.1f}%, epsilon {verdict.epsilon}){state}"
    )
    if verdict.mark.reason:
        line += f"\n    accepted: {verdict.mark.reason}"
    if verdict.raises:
        line += f"\n    new mark: {verdict.measured:.1f}%"
    return line