livery.extensions.coverage._floors¶
livery.extensions.coverage._floors ¶
Each package's coverage policy, its measured figure, the preview and the floors.
A package states its policy in its [coverage] table, a table this
extension declares: a floor, the mark on the store, or no verdict at
all (coverage_policy). The figure is one computation, figures, over
merged parts in the line format: each source file's measurer judges
what it names, its lines alone or its lines and branches. The gate job
judges it over the union of every leg (enforce_coverage), and a
machine's run of the tests prints it over its own run, beside each
floor, as a preview that judges nothing (report_coverage); both read
their data through measured_coverage. The coverage pages state each
package's floor in the words floor_status gives.
Classes:
| Name | Description |
|---|---|
FloorPolicy |
How a package's coverage is judged: a floor, the ratchet, or not at all. |
Functions:
| Name | Description |
|---|---|
coverage_policy |
The package's |
coverage_floor |
The floor the package's coverage is judged at, or None. |
floor_status |
The line a package's coverage pages state about its floor. |
figures |
Each measured package's figure over its source files in files. |
measured_coverage |
Each measured package's figure ( |
report_coverage |
Print each package's local coverage beside its floor, no verdict. |
previewer |
Answer |
enforce_coverage |
Fail any package measurably below its floor; the measured percentages. |
Attributes:
| Name | Type | Description |
|---|---|---|
DEFAULT_FLOOR |
|
|
UNJUDGED |
|
|
SOURCE |
|
FloorPolicy
dataclass
¶
FloorPolicy(floor: float | None, ratchet: bool, epsilon: float, required: bool = True, default: bool = False)
How a package's coverage is judged: a floor, the ratchet, or not at all.
Attributes:
| Name | Type | Description |
|---|---|---|
floor |
float | None
|
The percentage, or |
ratchet |
bool
|
Whether the mark on the store is the floor. |
epsilon |
float
|
The tolerance in percentage points, in both modes. |
required |
bool
|
Whether anything judges the package; |
default |
bool
|
Whether the floor is the default, the contract naming none. |
coverage_policy ¶
coverage_policy(package: Package) -> FloorPolicy | None
The package's [coverage] policy, or None when it has none.
The floor is a percentage, or the mode "auto-ratchet"; anything
else refuses by name. A package with tests that names no floor is
judged at the default floor, 100, and one without tests that names
none has no policy. required = false leaves the package unjudged
on purpose, and a floor beside it refuses. epsilon is a number of
percentage points, 0.5 when absent; a negative one refuses.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
coverage_floor ¶
The floor the package's coverage is judged at, or None.
None under auto-ratchet too, whose floor is the mark on the
store, and when nothing judges the package; coverage_policy
tells them apart.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
floor_status ¶
The line a package's coverage pages state about its floor.
The floor its contract names, or the default one; under auto-ratchet
the mark it ratchets to, from marks, the marks read from the state
store, and the mode alone when they were not read (None); or that
nothing judges it: on purpose, required = false, or for want of
tests.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
figures ¶
figures(root: Path, files: Mapping[str, Merged], units: Iterable[str], packages: tuple[Package, ...]) -> dict[str, float]
Each measured package's figure over its source files in files.
A file counts in the package that holds it when its category there
is source and the checkout holds it, so a test's own lines and a
build script never dilute the figure, and a module a test built
under its temporary directory counts nowhere. Each file counts what
its measurer judges (numbers): coverage.py's statements and
branches, a native measurer's lines alone, the figure being what is
covered over what can be.
units are the units whose parts files merged. A native package is measured only when its own suite's parts are among them, since its suite's measurer leaves them; any other package is measured when any unit that is not a native suite's is, and a package measured with no source file reached is 100. A package not measured has no figure.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
measured_coverage ¶
measured_coverage(root: Path, packages: tuple[Package, ...], *, none_ok: bool = False) -> dict[str, float]
Each measured package's figure (figures) over the measured data at root.
In the gate job the data is the union every leg's parts and the records' made, which its judge wrote at root. Anywhere else it is what the last run on this machine left: the parts a native suite's measurer left, and the parts the listed reductions make of the rest of the data. A machine's data is the whole run's, which names every source under the meter's directory, one nothing imported among them with no line run; the leg's units hold the files their suites reached alone, so such a file is left out here too, and the preview and the union agree on every file both measured. A run that left no data for a package that is not native is empty under none_ok, and refuses otherwise.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
report_coverage ¶
Print each package's local coverage beside its floor, no verdict.
One machine's run misses the platform branches and the task shells only the measured CI union reaches, so the local number is a low-biased preview: it informs, and the aggregating CI job's union is what the floors gate.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
previewer ¶
Answer python.test.preview with the function that prints the preview.
The python extension asks with the workspace root, which the answer does not depend on, after a machine's run of the suites, and calls the answer with the root and the packages the run tested.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
enforce_coverage ¶
Fail any package measurably below its floor; the measured percentages.
A floor, the package's own or the default, passes at the floor
minus the package's epsilon. Under auto-ratchet the floor is the
mark on the store minus epsilon: a run with no mark records one and
passes, a run that clears the mark by more than epsilon raises it
(a CI run writes; a local run says it would), and a store that
cannot be read falls open with its reason and writes nothing. A
package whose contract sets required = false gets no verdict and
no mark, and its line says so. Every verdict prints with its
numbers, so the numbers on screen are the numbers enforced.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_floors.py
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 | |