livery.toolroom.bench._ingest¶
livery.toolroom.bench._ingest ¶
Ingest verification: structural checks on a version's deployments, from any machine.
A new version is checked against the deployment already known before its pull request merges. The checks need no execution, so every host of the version is checked from whichever machine runs the refresh: each host's artifact is staged through the store, unpacked and looked at, and compared with the version before it.
The nine checks, in the order CHECKS lists them:
root: the declared root is in the archive (a stage refuses it otherwise, and the refusal is the finding).entry-points: every declared entry point is a file in the tree.paths: every declared path directory is in the tree.shims: every shim's target is a file in the tree.env: every env value naming a path under the install points at something in the tree.entry-points-kept: no entry point the previous version declared for the host is gone.hosts-kept: no host the previous version had lost its build.exclusions: every exclusion pattern matches something in the unpacked tree.stray-executables: no executable sits in a declared path directory without being a declared entry point or shim.
A finding names the check, the host and what was found. The structural diff of the paths added and removed since the previous version, per host, is the reviewer's summary. The executable checks, the entry point runs and the surface extracts, need a matching host and are the six-host point's business.
Classes:
| Name | Description |
|---|---|
Finding |
One check that did not pass, on one host. |
HostDiff |
The paths one host's tree gained and lost since the previous version. |
Report |
What the checks found for one version of one tool. |
Functions:
| Name | Description |
|---|---|
previous_with_hosts |
The nearest earlier version that has a host, or empty when there is none. |
verify |
Run the nine checks on version of record for its hosts; the report. |
summary |
The report as lines: the verdict, each finding, and each host's diff. |
Attributes:
| Name | Type | Description |
|---|---|---|
CHECKS |
The nine structural checks, by name, in the order they run. |
CHECKS
module-attribute
¶
CHECKS = ('root', 'entry-points', 'paths', 'shims', 'env', 'entry-points-kept', 'hosts-kept', 'exclusions', 'stray-executables')
The nine structural checks, by name, in the order they run.
Finding
dataclass
¶
HostDiff
dataclass
¶
Report
dataclass
¶
Report(name: str, version: str, previous: str, hosts: tuple[str, ...], findings: tuple[Finding, ...] = (), diffs: tuple[HostDiff, ...] = tuple())
What the checks found for one version of one tool.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The tool. |
version |
str
|
The version checked. |
previous |
str
|
The version it was compared with; empty for the first version with a host. |
hosts |
tuple[str, ...]
|
The hosts checked, in the record's order. |
findings |
tuple[Finding, ...]
|
Every check that did not pass; empty means every check passed on every host. |
diffs |
tuple[HostDiff, ...]
|
Per host, the structural diff against the previous version; a host the previous version lacked diffs against nothing, so every path is added. |
diffs
class-attribute
instance-attribute
¶
previous_with_hosts ¶
The nearest earlier version that has a host, or empty when there is none.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_ingest.py
verify ¶
verify(record: Record, version: str, *, store: Store, hosts: tuple[str, ...] = (), previous: str | None = None) -> Report
Run the nine checks on version of record for its hosts; the report.
Each host's artifact is staged through store into a scratch directory, which goes when the host's checks are done. hosts narrows to some of the version's hosts; previous names the version to compare with, the nearest earlier version with a host otherwise. A version with no host has nothing to check and passes with no diff.
Raises:
| Type | Description |
|---|---|
RecordError
|
when the record does not track version. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_ingest.py
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | |
summary ¶
The report as lines: the verdict, each finding, and each host's diff.