livery.extensions.coverage._record¶
livery.extensions.coverage._record ¶
The coverage record: main's and each branch's parts per leg, and the parts in flight.
Coverage stays global under the affected mode. A record holds, per check leg, one row per unit (a package's test suite, or the workspace's own tests): the unit's parts in the line format, one per measurer that measured the suite, each holding the files of the suite's closure it reached, and the identity of the closure it was measured at. Main has a record, and so does every branch with a pull request run, under the same family with the branch as the base part. A check leg skips a suite when its branch's record or main's holds the unit at the suite's current closure identity, and runs it otherwise. A leg that ran a suite leaves the suite's parts, with the scope its gate ran, for the leg's one write, which puts them on its per-run ref beside its timing half; the run's gate job unions the per-run refs with the rows it carries from the records, judges the floors on that union, and writes the union back: a pull request's run onto its branch's record, main's run onto main's, each replaced in place, the units that no longer exist removed. A row a write replaces at another closure, or removes, stays for a day under the moment it was kept and its closure's name: a run whose leg skipped a suite on it, while another run moved the record on, still unions it. At the merge main's run finds its tree on the verified record, which names the branch, and copies the branch's rows into main's without measuring; a squash of a stale branch has another tree, and main pays the full gate. A unit neither record holds is measured on the spot, never red.
The unit is the suite that ran, never the package covered: a suite
executes lines across packages (a dependant's tests run its
dependencies), so a unit's parts hold the files of the suite's closure
alone, the files whose identity the key names. A row keeps its parts in
the line format's stored form: what ran, each file's fixed facts named
by their own digest. The facts are files of their own beside the rows
(FACTS), each kept once however many rows, legs and writes name it,
and a write drops the facts no row names any more. A python suite's
row names the tests that reached each line, and its numbering of them
lives in the row: each write numbers them as the row it replaces did,
so a test keeps its index from run to run, a new test takes the next,
and a test that is gone keeps its index, reached by no line (the line
format's numbering). Two rows of a unit a run apart then keep a
line's set of tests byte for byte wherever the same tests reached it.
One run's writes append the same tests on every leg (run_contexts),
so a test has one index in its unit's rows on every leg, and the legs'
rows keep a line's set alike wherever the same tests reached it. Reach
for
recorded to read a record on a leg, leave_run to leave a leg's
parts for its write, fold_leg to fold the files a platform's shards
left into the platform leg's one, run_legs to read them in the gate
job, and put_record to write the record. A read of a record parses its
current rows and the facts they name alone, and names its kept rows,
reading one only when the union asks for it.
Classes:
| Name | Description |
|---|---|
Unit |
One unit's measurement: the parts its suite's measurers made within its closure. |
Leg |
What one check leg put on its per-run ref. |
Kept |
A row a write replaced at another closure, or removed, kept for a day. |
Record |
A base's record on one leg, as read. |
Functions:
| Name | Description |
|---|---|
branches |
The branches origin holds, by name; |
current_keys |
The keys the world produces: main and every branch on origin, per check leg. |
facts_file |
The record's file for the fixed facts named name. |
kept_name |
The record's file for a kept row: the unit at path, measured at closure. |
record_ref |
The ref holding base's record on leg: main's, or a branch's. |
record_bases |
The records a leg reads, in order: the branch's own if any, then main's. |
record_prefixes |
The refs of the records a run reads, as prefixes: branch's if any, then main's. |
series |
Answer |
row_name |
The record's file for the unit at path. |
closure |
package and every package it depends on, transitively, in path order. |
closure_id |
The identity of package's suite inputs at |
in_closure |
Whether filename (workspace-relative) belongs to package's closure. |
unit_fields |
unit as a row and a leg's file hold it: its parts, without their facts. |
units_facts |
The fixed facts units' parts name, by name, each once. |
leave_run |
Leave leg's scope and measured units for its one write; |
fold_leg |
Answer |
folders |
Answer |
run_legs |
Every check leg's coverage file on run's per-run refs; the legs, or the reason. |
recorded |
base's record on leg, main's by default: every recorded unit, in one read. |
run_contexts |
Every context one run's writes name, by unit path and measurer name. |
put_record |
Write the fresh units onto base's record on leg; |
Attributes:
| Name | Type | Description |
|---|---|---|
SCHEMA |
|
|
FACTS |
|
|
MAIN |
|
|
RUN_FILE |
|
|
ROOT_PINS |
|
|
RECORD |
|
|
KEPT_FOR |
|
|
KEPT_STAMP |
|
RECORD
module-attribute
¶
RECORD = git.Keyed('coverage', ('base', 'leg'), schema=SCHEMA, current=current_keys, linger=timedelta(days=1), blobs=FACTS)
Unit
dataclass
¶
Unit(path: str, closure: str, run: str, sha: str, parts: tuple[dict[str, Any], ...] = (), facts: Mapping[str, Any] = dict())
One unit's measurement: the parts its suite's measurers made within its closure.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The unit's path ( |
closure |
str
|
The closure identity the measurement is keyed by. |
run |
str
|
The run that measured it. |
sha |
str
|
The commit that run checked out. |
parts |
tuple[dict[str, Any], ...]
|
The unit's parts in the line format's stored form, as JSON holds them: one for each measurer that measured the suite, each holding the files of the suite's closure it reached. A suite that ran unmeasured has none. |
facts |
Mapping[str, Any]
|
The fixed facts the parts name, by name; the units of one record share the record's. Two units with the same parts are equal whatever else their tables hold, since a part names its facts by their content. |
Leg
dataclass
¶
Leg(key: str, label: str, scope: str, packages: tuple[str, ...], units: dict[str, Unit], why: str = '')
What one check leg put on its per-run ref.
Attributes:
| Name | Type | Description |
|---|---|---|
key |
str
|
The leg's part of the per-run key, as its ref spells it. |
label |
str
|
The leg's label ( |
scope |
str
|
The scope the leg's gate ran, as its marker named it. |
packages |
tuple[str, ...]
|
The packages whose suites a narrowed leg ran. |
units |
dict[str, Unit]
|
The suites the leg measured, by the unit's path. |
why |
str
|
Why the ref carries no readable file, when it does not. |
Kept
dataclass
¶
A row a write replaced at another closure, or removed, kept for a day.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The row's file on the ref: the moment the write kept it,
the closure it was measured at, and its unit's slug
( |
unit |
Unit | None
|
The measurement, once read. A read of a record names its
kept rows and reads none; the union reads the one it asks
for ( |
Record
dataclass
¶
Record(units: dict[str, Unit], skipped: tuple[Skipped, ...] = (), failed: bool = False, reason: str = '', kept: tuple[Kept, ...] = (), read_kept: Callable[[str], Unit | None] | None = None, facts: dict[str, Any] = dict(), held_facts: tuple[str, ...] = ())
A base's record on one leg, as read.
Attributes:
| Name | Type | Description |
|---|---|---|
units |
dict[str, Unit]
|
The recorded units by path: the current rows. |
skipped |
tuple[Skipped, ...]
|
The rows that are not units, named; printing one gives the line. |
failed |
bool
|
Whether the record could not be read at all. |
reason |
str
|
Why it could not, in the store's wording. |
kept |
tuple[Kept, ...]
|
The rows writes replaced or removed, by file name, kept
for |
read_kept |
Callable[[str], Unit | None] | None
|
Reads a kept row by its name, for |
facts |
dict[str, Any]
|
The fixed facts read, by name: the ones the current rows name, and a kept row's once it is read. |
held_facts |
tuple[str, ...]
|
The name of every fixed facts file the record holds, read or not. |
Methods:
| Name | Description |
|---|---|
at |
The measurement of path at closure: the current row's, else a kept one's. |
expired |
The names of the kept rows past their day at now. |
stale |
The row names to drop: units outside current, and rows that are no unit. |
read_kept
class-attribute
instance-attribute
¶
facts
class-attribute
instance-attribute
¶
at ¶
The measurement of path at closure: the current row's, else a kept one's.
The union asks here for what a leg skipped: the leg read the current row, and a write since may have kept it instead. The kept rows of path at closure are read newest first, and the first that is the unit's answers.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
expired ¶
The names of the kept rows past their day at now.
A row is kept for KEPT_FOR from the write that kept it, the
moment its name carries. A row whose name carries none counts
as expired: its age cannot be told.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
stale ¶
The row names to drop: units outside current, and rows that are no unit.
A stale row is a unit that no longer exists, or a row the reader could not take as a unit at all.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
branches ¶
The branches origin holds, by name; None if origin cannot be listed.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
current_keys ¶
The keys the world produces: main and every branch on origin, per check leg.
The janitor drops a ref outside this set: a branch's record once
the branch is gone from origin, and a leg's once the matrix no
longer produces it. None when the contract or the remote
cannot be read, and then nothing is dropped.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
facts_file ¶
kept_name ¶
The record's file for a kept row: the unit at path, measured at closure.
The name carries the moment when the write kept it, so a reader
tells a kept row's age from its name and reads no kept row for it.
It ends in the unit's own row name (row_name), the moment and the
closure before it: git chooses which files to store as the
difference from another by the last sixteen characters of their
names, so a kept row can be stored against its unit's other rows,
of every leg and every run, where the stable numbering of the tests
keeps that difference small.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
record_ref ¶
The ref holding base's record on leg: main's, or a branch's.
record_bases ¶
The records a leg reads, in order: the branch's own if any, then main's.
record_prefixes ¶
The refs of the records a run reads, as prefixes: branch's if any, then main's.
A check leg and the gate job hand them to
livery.git.remote_snapshot as the refs to bring when the block
opens: one prefix per base record_bases names, spelled in full
as that base's refs are (refs/workshop/coverage/<branch>/), so
a run fetches the two records it reads and no other branch's. A
record outside them, the one of the branch a verified row names,
is brought on its first read, every leg of it, in one more fetch.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
series ¶
Answer store.series: the coverage record and the coverage marks.
The janitor bounds them and fm store.ls lists them while the
workspace lists the coverage extension. The answer is the same in
every workspace, so root is not read.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
row_name ¶
closure ¶
package and every package it depends on, transitively, in path order.
An edge naming a path no package has is skipped: the workspace lint refuses such an edge before any gate runs, and the identity here is of the packages that exist.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
closure_id ¶
The identity of package's suite inputs at HEAD.
A digest over the tree ids of the package's closure directories
and the blob ids of ROOT_PINS, so an identical identity means
identical code and identical dependencies: the argument that lets
the suite's run be skipped at all. A root pin the tree lacks
contributes nothing.
The workspace's own tests reach any package, so their identity is every package's tree, their own directory's tree, and the root pins: prose leaves it untouched, and a root configuration change forces a full run anyway, which measures the unit afresh.
Raises:
| Type | Description |
|---|---|
GitError
|
When a closure directory is not in |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
in_closure ¶
Whether filename (workspace-relative) belongs to package's closure.
Every file belongs to the workspace tests' closure.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
unit_fields ¶
unit as a row and a leg's file hold it: its parts, without their facts.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
units_facts ¶
The fixed facts units' parts name, by name, each once.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
leave_run ¶
leave_run(root: Path, run: RunContext, *, leg: str, scope: str, packages: tuple[str, ...], units: Mapping[str, Unit]) -> str
Leave leg's scope and measured units for its one write; "" or why not.
The one file carries the scope the leg's gate ran, the packages a
narrowed gate named, every unit's parts, and the fixed facts they
name, each once, so the gate job reads a leg's whole fact in one
read and the parts go with the ref when the run's metrics are
collected. It lands in the leg's spool
(livery.workshop.leave_leg_file), and the leg's last entry,
ci.leg, puts it on the leg's per-run ref beside the timing row,
so a leg writes its ref once.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
fold_leg ¶
Answer ci.fold for RUN_FILE: one platform leg's file from its shards'.
Each shard of a platform ran a slice of the test files and left the parts of the suites it reached; together they are one leg's measurement. The folded file names the platform leg (livery.workshop.platform_leg), the shards' one scope and packages, and every unit any shard measured, its parts every shard's concatenated in shard order: a unit one shard measured and another did not is measured. The fixed facts are every shard's, each name once, since a name is its content's digest.
Raises:
| Type | Description |
|---|---|
ValueError
|
When the shards' files are not one leg's, naming what differs: legs of two platforms, two scopes, two package lists, or a unit at two closures. |
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 | |
folders ¶
Answer ci.fold: the gate job folds RUN_FILE with fold_leg.
The answer is the same in every workspace, so root is not read.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
run_legs ¶
Every check leg's coverage file on run's per-run refs; the legs, or the reason.
The reason is set when the refs could not be listed. A ref that
carries no readable coverage file is a leg whose why names
it: a leg that died before its parts, or a file that is not a
row; the caller decides, and a missing put is red there.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
recorded ¶
base's record on leg, main's by default: every recorded unit, in one read.
An absent record is no units and no failure; a record the store
could not read is a failure with its reason; a row that is not a
unit is skipped and named, and the rest stand. The current rows
alone are read, then the fixed facts they name: a row naming facts
the record does not hold is skipped, naming the facts and the
content, so its unit is a miss and is measured afresh. A row named
by its unit, closure and moment (kept_name) is a kept one, named
in the record and read, with its facts, only when the union asks
for it (Record.at). The record is the platform leg's
(livery.workshop.platform_leg), so a shard's label reads its
platform's. A leg without a label, or an empty base, has no record
to read.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
run_contexts ¶
Every context one run's writes name, by unit path and measurer name.
writes holds each leg's rows, by unit path. A context that is not text names nothing here; the write that reads its row refuses it.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
put_record ¶
put_record(root: Path, run: RunContext, *, leg: str, fresh: Mapping[str, Unit], remove: Iterable[str] = (), base: str = MAIN, held: Record | None = None, now: datetime | None = None, numbered_like: Mapping[str, Unit] | None = None, run_contexts: Mapping[str, Mapping[str, Collection[str]]] | None = None) -> str
Write the fresh units onto base's record on leg; "" or the reason.
Main's record is written by main's run alone, the run of a push; a branch's record by that branch's own pull request run alone. Either replaces its record in place: a fresh row replaces the unit's, a row named in remove goes, every other row stands as the carried measurement it is. Any other run is refused by name, so a pull request never writes what main's next run will skip on, and no branch writes another's record.
A current row that a fresh one replaces at another closure, or
that remove names, stays as a kept row under its closure's name
and the moment now (kept_name), and every kept row older than
KEPT_FOR at now goes. held is the record as the caller read
it; it is read here when absent, and a record that cannot be read
refuses the write, since what it would keep is unknown.
The fixed facts a fresh row names are written beside the rows when the record does not hold them yet, from the fresh units' own facts, and the facts no row of the written record names go. The kept rows that stay are read for the facts they name, and a write whose rows name facts no unit holds is refused by name.
Each fresh row numbers the tests that reached its lines as the row
it replaces numbers them, part by part of one measurer: every
context that row numbers keeps its index, and the new ones follow,
sorted: the ones run_contexts names for the unit and measurer
(run_contexts, every test the run's rows of the unit name on any
leg) and the part's own. Rows of every leg start alike and extend
alike, so a test has one index in a unit's rows on every leg. A
unit the record does not hold yet is numbered as its row in
numbered_like, main's for a branch's first write, and without
one its numbering starts afresh. A fresh part off the line format
refuses the write, naming the unit and the key.
Source code in packages/extensions/coverage/src/livery/extensions/coverage/_record.py
926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 | |