Coverage for packages/workshop/src/livery/workshop/_footprint.py: 96%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""The runner footprint: the runner-minutes the metrics window holds, by runner label.
2
3What ``fm ci.footprint`` prints. Each row of the ``metrics`` series
4([livery.workshop._metrics.SERIES][]) is one run with the forge's wall
5time of every job. A job whose display name lists its matrix, ``check
6(macos-latest, 3.14)`` or ``check (windows-latest, 3.14, 2of4)``, ran
7on the runner the first item names; every other job (the gate job, the
8docs build, the release jobs, the matrix picker) ran on the first
9runner ``[ci] runners`` names, where the workflow places them. The
10folded row of a platform's shards is left out: the forge never ran it,
11and the shards' own rows carry the minutes. A job without a wall time,
12still running when the gate job collected or never started, is counted
13apart and priced as nothing.
14
15The price is GitHub's, for the standard runners of a private
16repository; `fm ci.footprint` decides when to print it. A public
17repository on GitHub is not billed for them, so the price says what
18the same minutes would cost a private one.
19"""
20
21from __future__ import annotations(empty)
22
23import re(empty)
24from collections import defaultdict(empty)
25from collections.abc import Mapping, Sequence(empty)
26from dataclasses import dataclass(empty)
27from datetime import datetime(empty)
28from pathlib import Path(empty)
29from typing import Any(empty)
30
31from livery.workshop._contract import load_contract(empty)
32
33#: GitHub's rates in USD per minute for the standard runners of a
34#: private repository, by the class a runner label names: Linux
35#: 2-core, Windows 2-core, macOS 4-core (M1), as the page
36#: https://docs.github.com/en/billing/reference/actions-runner-pricing
37#: lists them. Larger runners cost more per minute and are not priced
38#: here; a public repository is not billed for standard runners at all.
39RATES: Mapping[str, float] = {"linux": 0.006, "windows": 0.010, "macos": 0.062}(empty)
40
41#: The page the rates come from, printed under the price.
42SOURCE = "https://docs.github.com/en/billing/reference/actions-runner-pricing"(empty)
43
44#: The two kinds a line sums: the check matrix's legs, and every other job.
45LEGS = "check legs"(empty)
46OTHER = "other jobs"(empty)
47
48#: A matrix job's display name: the job, then its runner first inside
49#: the parentheses, then at least one more item (the Python, a shard).
50_MATRIX = re.compile(r"^[^ (]+ \((?P<runner>[^,)]+), [^)]+\)$")(empty)
51
52
53@dataclass(frozen=True)(empty)
54class Line:(empty)
55 """The jobs and minutes of one kind on one runner label.
56
57 Attributes:
58 label: The runner label, ``macos-latest``.
59 kind: `LEGS` for the check matrix's legs, `OTHER` for every
60 other job, counted on the first runner ``[ci] runners``
61 names.
62 jobs: How many jobs with a wall time the line sums.
63 minutes: Their summed wall time in minutes.
64 """
65
66 label: str(empty)
67 kind: str(empty)
68 jobs: int(empty)
69 minutes: float(empty)
70
71 @property(empty)
72 def runner_class(self) -> str:(empty)
73 """The class the label names, a key of `RATES`; empty for none."""
74 return runner_class(self.label)
75
76 @property(empty)
77 def usd(self) -> float | None:(empty)
78 """The line's minutes at the class's rate; None for a label of no class."""
79 rate = RATES.get(self.runner_class)
80 return None if rate is None else self.minutes * rate
81
82
83@dataclass(frozen=True)(empty)
84class Footprint:(empty)
85 """The runner-minutes of a window of runs, by runner label and kind.
86
87 Attributes:
88 runs: How many runs the window holds.
89 first_day: The day of the oldest run, ISO; empty when no run
90 says when it was created.
91 last_day: The day of the newest run, ISO; empty likewise.
92 span_days: The days from the oldest run to the newest, at
93 least one: the rate per 30 days divides by it.
94 lines: One per runner label and kind, by label then kind.
95 untimed: The jobs without a wall time, counted apart.
96 """
97
98 runs: int(empty)
99 first_day: str(empty)
100 last_day: str(empty)
101 span_days: float(empty)
102 lines: tuple[Line, ...](empty)
103 untimed: int(empty)
104
105 @property(empty)
106 def jobs(self) -> int:(empty)
107 """Every job the window holds, the ones without a wall time included."""
108 return sum(line.jobs for line in self.lines) + self.untimed
109
110 @property(empty)
111 def minutes(self) -> float:(empty)
112 """The summed runner-minutes."""
113 return sum(line.minutes for line in self.lines)
114
115 @property(empty)
116 def usd(self) -> float:(empty)
117 """The priced lines' USD; a label of no class adds nothing."""
118 return sum(line.usd or 0.0 for line in self.lines)
119
120 @property(empty)
121 def unpriced(self) -> tuple[Line, ...]:(empty)
122 """The lines whose label names no class."""
123 return tuple(line for line in self.lines if line.usd is None)
124
125 def per_30_days(self, value: float) -> float:(empty)
126 """*value*, a total over the window, as a rate per 30 days."""
127 return value * 30.0 / self.span_days
128
129
130def runner_class(label: str) -> str:(empty)
131 """The class *label* names: ``linux``, ``windows``, ``macos``, or empty.
132
133 By substring of the lowercased label: ``ubuntu`` or ``linux`` is
134 linux, ``windows`` is windows, ``macos`` is macos. A label naming
135 none, a self-hosted runner's say, is empty, and prices as nothing.
136 """
137 lowered = label.lower()
138 if "ubuntu" in lowered or "linux" in lowered:
139 return "linux"
140 if "windows" in lowered:
141 return "windows"
142 if "macos" in lowered:
143 return "macos"
144 return ""
145
146
147def runner_of(display: str, *, default: str) -> tuple[str, str]:(empty)
148 """The runner label the job *display* ran on, and the kind of line it counts in.
149
150 A matrix job, ``check (macos-latest, 3.14)`` or ``check
151 (windows-latest, 3.14, 2of4)``, ran on the first item in its
152 parentheses and counts as `LEGS`. Every other display name ran on
153 *default* and counts as `OTHER`.
154 """
155 matched = _MATRIX.match(display)
156 if matched is None:
157 return default, OTHER
158 return matched["runner"].strip(), LEGS
159
160
161def _folded(row: Mapping[str, Any]) -> bool:(empty)
162 """Whether *row* is a fold's own row: its ``shard`` lists the shards."""
163 shard = row.get("shard")
164 return isinstance(shard, Mapping) and "shards" in shard
165
166
167def _moment(entry: Mapping[str, Any]) -> datetime | None:(empty)
168 stamp = str(entry.get("created_at") or entry.get("when") or "")
169 if not stamp:169 ↛ 170line 169 didn't jump to line 170 because the condition on line 169 was never true
170 return None
171 try:
172 return datetime.fromisoformat(stamp.replace("Z", "+00:00"))
173 except ValueError:
174 return None
175
176
177def footprint((empty)
178 entries: Sequence[Mapping[str, Any]], *, default_runner: str
179) -> Footprint:
180 """Sum the runner-minutes of *entries*, the rows of a window of runs.
181
182 Every job of every row is counted on one runner label, as
183 `runner_of` attributes it with *default_runner*; a fold's own row
184 is left out, since the shards' rows carry its minutes. A job whose
185 ``wall_ms`` is no number is counted apart. The span is from the
186 oldest row's creation to the newest, at least one day; a row that
187 says no moment is left out of it.
188 """
189 jobs: dict[tuple[str, str], int] = defaultdict(int)
190 minutes: dict[tuple[str, str], float] = defaultdict(float)
191 untimed = 0
192 for entry in entries:
193 rows = entry.get("jobs")
194 if not isinstance(rows, Mapping):194 ↛ 195line 194 didn't jump to line 195 because the condition on line 194 was never true
195 continue
196 for display, row in rows.items():
197 if not isinstance(row, Mapping) or _folded(row):
198 continue
199 wall = row.get("wall_ms")
200 if not isinstance(wall, int | float):
201 untimed += 1
202 continue
203 key = runner_of(str(display), default=default_runner)
204 jobs[key] += 1
205 minutes[key] += float(wall) / 60_000.0
206 moments = sorted(m for m in (_moment(entry) for entry in entries) if m is not None)
207 first, last = (moments[0], moments[-1]) if moments else (None, None)
208 span = (last - first).total_seconds() / 86_400.0 if first and last else 0.0
209 return Footprint(
210 runs=len(entries),
211 first_day=first.date().isoformat() if first else "",
212 last_day=last.date().isoformat() if last else "",
213 span_days=max(1.0, span),
214 lines=tuple(
215 Line(label, kind, jobs[label, kind], minutes[label, kind])
216 for label, kind in sorted(jobs)
217 ),
218 untimed=untimed,
219 )
220
221
222def default_runner(root: Path) -> str:(empty)
223 """The first runner the root contract's ``[ci] runners`` names.
224
225 ``ubuntu-latest`` when the contract names none, as the workflow
226 renders it.
227 """
228 ci = load_contract(root / "workshop.toml").get("ci") or {}
229 runners = [str(runner) for runner in ci.get("runners") or ["ubuntu-latest"]]
230 return runners[0]
231
232
233def render(summed: Footprint, *, default_runner: str) -> list[str]:(empty)
234 """The footprint as ``fm ci.footprint`` prints it: the window, a table, the rate.
235
236 The window line gives the runs, the days and the span. One table
237 line per runner label and kind, the total, and a line for the
238 jobs without a wall time when there are any. Then the minutes per
239 30 days from the span.
240 """
241 days = (
242 f", {summed.first_day} to {summed.last_day}"
243 if summed.first_day and summed.last_day
244 else ""
245 )
246 lines = [
247 f" {summed.runs} run(s) in the window{days}, {summed.span_days:.1f} day(s);"
248 f" {summed.jobs} job(s)",
249 f" a job outside the check matrix is counted on {default_runner}, the first"
250 " of [ci] runners, where the workflow places it",
251 f" {'label':<24} {'kind':<12} {'jobs':>6} {'minutes':>9}",
252 ]
253 lines.extend(
254 f" {line.label:<24} {line.kind:<12} {line.jobs:>6} {line.minutes:>9.1f}"
255 for line in summed.lines
256 )
257 timed = summed.jobs - summed.untimed
258 lines.append(f" {'total':<24} {'':<12} {timed:>6} {summed.minutes:>9.1f}")
259 if summed.untimed:
260 lines.append(
261 f" {'no wall time':<24} {'':<12} {summed.untimed:>6} {'-':>9} still"
262 " running when the gate job collected, or never started"
263 )
264 lines.append(
265 f" rate: {summed.per_30_days(summed.minutes):.0f} minutes per 30 days"
266 )
267 return lines
268
269
270def price(summed: Footprint) -> list[str]:(empty)
271 """The footprint priced at GitHub's rates for a private repository, as printed.
272
273 Only for a public repository on GitHub, which is not billed for
274 standard runners: the table says what the same minutes would cost
275 a private one, one line per runner label and kind at its class's
276 rate, a label of no class named as unpriced, then the total, the
277 USD per 30 days, and the source page.
278 """
279 lines = [
280 " a public repository on GitHub is not billed for standard runners; the"
281 " same minutes on a private one, at GitHub's rates:",
282 f" {'label':<24} {'kind':<12} {'class':<8} {'USD/min':>8} {'USD':>9}",
283 ]
284 for line in summed.lines:
285 usd = line.usd
286 if usd is None:
287 lines.append(
288 f" {line.label:<24} {line.kind:<12} unpriced: the label names no"
289 " class (ubuntu or linux, windows, macos)"
290 )
291 continue
292 lines.append(
293 f" {line.label:<24} {line.kind:<12} {line.runner_class:<8}"
294 f" {RATES[line.runner_class]:>8.3f} {usd:>9.2f}"
295 )
296 lines.append(f" {'total':<24} {'':<12} {'':<8} {'':>8} {summed.usd:>9.2f}")
297 lines.append(
298 f" rate: {summed.per_30_days(summed.usd):.2f} USD per 30 days; larger"
299 " runners cost more per minute"
300 )
301 lines.append(f" source: {SOURCE}")
302 return lines