Coverage for packages/workshop/src/livery/workshop/_lifecycle.py: 98%

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"""What the engine asks of a package: build, versions, tests, publish, requirements.
2
3The release train, the layering phase and the docs reach a package's
4artifacts and manifests through these functions alone: its build, the
5version its manifest declares, the files a version is written into,
6writing a version, testing the built artifact in isolation, publishing
7what it built and the registry it goes to, verifying a released
8version, its declared requirements, writing one, the names other
9packages reference its code by, and what its sources reference. A
10question is a query ([livery.workshop._queries.Query][]) the package's
11set answers, the extensions it lists and those they require; a build,
12a stamp, an isolated test, a publish or a verification runs as the
13package's phase ([livery.workshop._phases.walk_steps][]), the steps its
14set adds to it. So a caller never names an extension.
15
16A question nothing in the set answers gets the query's empty answer:
17no module roots, no requirements. The version is the one question an
18empty answer cannot serve, and it refuses naming the query. A phase
19the set adds no step to refuses the release, naming the phase. A
20package that lists no extension holds none: every question gets its
21empty answer, and every phase refuses.
22"""
23
24from __future__ import annotations(empty)
25
26from typing import TYPE_CHECKING, cast(empty)
27
28if TYPE_CHECKING:(empty)
29 from collections.abc import Iterable, Mapping
30 from pathlib import Path
31
32 from livery.forge import Registry
33 from livery.workshop._packages import Package, SourceReferences
34 from livery.workshop._phases import PhaseContext
35 from livery.workshop._registries import RegistryTarget
36 from livery.workshop._steps import StepRecord
37
38
39def sync(packages: Iterable[Package], root: Path) -> None:(empty)
40 """Run the sync phase over the workspace at *root* holding *packages*.
41
42 The phase is what the workspace and its members need before
43 ``uv sync`` installs them: the steps the listed extensions
44 registered at mount, each once over the workspace, and a step that
45 judges one package at a time once for each of *packages* whose set
46 holds an extension it names. A workspace step that names
47 extensions runs while one of *packages* holds one of them, and not
48 at all while none does. conan's profile step is one: it runs once
49 while a package holds conan, a package that lists nanobind among
50 them, since its set holds conan. With no step registered, the phase
51 runs nothing.
52 """
53 from livery.workshop._phases import PhaseContext, run_registered
54
55 run_registered(PhaseContext(root=root, packages=tuple(packages), phase="sync"))
56
57
58#: What the release train's build gives the build phase beside the
59#: epoch: the isolated side, in the release configuration.
60RELEASE_BUILD: Mapping[str, object] = {"isolated": True, "configuration": "release"}(empty)
61
62
63def build_release(package: Package, root: Path, *, epoch: int = 0) -> Path:(empty)
64 """Build *package*'s release artifacts into its ``dist/``; that directory.
65
66 The release train's build: the steps *package*'s set adds to the
67 build phase, run on the phase's isolated side in the ``release``
68 configuration. One of them provides the ``dist`` directory it
69 wrote.
70
71 Args:
72 package: The member to build.
73 root: The workspace root *package* is a member of.
74 epoch: The build's source date in seconds, so two builds of one
75 tree are the same bytes; 0 takes the build tool's own.
76
77 Returns:
78 The directory the build phase's steps wrote the artifacts into.
79
80 Raises:
81 Failed: naming the package, its set and the phase, when no
82 extension of the set adds a step to the build phase; and
83 naming the package, when the steps that ran provide no
84 ``dist`` directory.
85 """
86 from pathlib import Path
87
88 ctx = _served(package, "build", root, {**RELEASE_BUILD, "epoch": epoch})
89 return cast("Path", _provided(ctx, "dist", Path))
90
91
92def current_version(package: Package) -> str:(empty)
93 """The version *package*'s own manifest declares.
94
95 Raises:
96 Failed: naming the package, its set and the query, when nothing
97 in the set answers the version, since a release reads and
98 stamps it.
99 """
100 from livery.footman import fail
101 from livery.workshop._queries import CURRENT_VERSION, answer
102
103 answered = answer(package, CURRENT_VERSION)
104 if not answered:
105 held = ", ".join(_set_of(package)) or "none"
106 fail(
107 f"{package.path}: its extensions ({held}) answer no"
108 f" {CURRENT_VERSION.name}: none of them reads a version from the"
109 " package's manifests, so the release train has no version to read"
110 " or stamp. List the extension whose manifest carries the version"
111 )
112 return answered
113
114
115def version_files(package: Package) -> tuple[Path, ...]:(empty)
116 """Every file the stamp phase's steps write: the version, and the floors.
117
118 A file holding only floors is among them, as a recipe that names no
119 version is. A caller that stamps for one build keeps these files
120 first, then restores them. Empty for a package whose set names none.
121 The floors the base raises are in the package's own contract, which
122 is not among them.
123 """
124 from livery.workshop._queries import VERSION_FILES, answer
125
126 return tuple(answer(package, VERSION_FILES))
127
128
129def stamp((empty)
130 package: Package,
131 root: Path,
132 version: str,
133 *,
134 floors: Mapping[str, str] | None = None,
135) -> list[str]:
136 """Write *version* and raise *package*'s floors in its manifests; the files changed.
137
138 The stamp phase's steps write the version into their own manifests,
139 and raise there each floor a manifest declares on one of *floors*:
140 the members released with *package*, each by its path, to the
141 version it releases at. The base raises the floor of each
142 ``[[depends]]`` edge of the package's contract on one of them.
143 Without *floors* no floor moves, as for a member released alone.
144 Each file is named relative to the package's directory.
145
146 Raises:
147 Failed: naming the package, its set and the phase, when no
148 extension of the set adds a step to the stamp phase.
149 """
150 given = dict(floors or {})
151 ctx = _served(package, "stamp", root, {"version": version, "floors": given})
152 changed = list(cast("list[str]", _provided(ctx, "changed", (list, tuple))))
153 if _raise_depends_floors(package, given):
154 from livery.workshop._contract import CONTRACT
155
156 changed.append(CONTRACT)
157 return changed
158
159
160def _raise_depends_floors(package: Package, floors: Mapping[str, str]) -> bool:(empty)
161 """Raise each ``[[depends]]`` floor of *package*'s contract on one of *floors*.
162
163 A text edit, so the contract keeps its comments and layout: the
164 ``floor`` of the edge whose ``path`` names the member takes its
165 version. Whether the contract changed.
166 """
167 import re
168
169 from livery.workshop._contract import CONTRACT
170
171 contract = package.directory / CONTRACT
172 if not floors or not contract.is_file():
173 return False
174 text = original = contract.read_text("utf-8")
175 for path, version in floors.items():
176 if path == package.path:176 ↛ 177line 176 didn't jump to line 177 because the condition on line 176 was never true
177 continue
178 text = re.sub(
179 rf'(path = "{re.escape(path)}"[^[]*?floor = ")[^"]+(")',
180 rf"\g<1>{version}\g<2>",
181 text,
182 flags=re.S,
183 )
184 if text == original:
185 return False
186 contract.write_text(text, encoding="utf-8")
187 return True
188
189
190def publish((empty)
191 package: Package,
192 root: Path,
193 *,
194 version: str,
195 target: RegistryTarget,
196 prebuilt: bool = False,
197) -> bool:
198 """Upload *package*'s built artifacts to *target*; False when all were there.
199
200 A re-run walks past what an earlier attempt uploaded, so False is
201 a success that uploaded nothing. *prebuilt* says a job of the run
202 built the package and the run collected what it built into the
203 package's ``dist/``, so this runner built nothing. The publish
204 phase gets it as ``prebuilt``, and a step whose upload reads
205 something other than ``dist/``, as conan's reads its cache, puts
206 the collected files there first.
207
208 Raises:
209 Failed: naming the package, its set and the phase, when no
210 extension of the set adds a step to the publish phase.
211 """
212 from livery.workshop._registries import target_table
213
214 inputs: dict[str, object] = {
215 "version": version,
216 "registry-target": target_table(target),
217 "prebuilt": prebuilt,
218 }
219 ctx = _served(package, "publish", root, inputs)
220 return cast("bool", _provided(ctx, "published", bool))
221
222
223def distributions(package: Package) -> tuple[tuple[str, str], ...]:(empty)
224 """The distributions *package* releases, each as its ecosystem and its name.
225
226 Its set's answers to the ``distributions`` query, combined.
227 """
228 from livery.workshop._queries import DISTRIBUTIONS, answer
229
230 return answer(package, DISTRIBUTIONS)
231
232
233def ecosystem(package: Package) -> str:(empty)
234 """The one ecosystem *package* releases to, which its registry resolves by.
235
236 The ecosystem its distributions name (``distributions``): the release
237 train publishes the package to that ecosystem's registry and probes
238 it there.
239
240 Raises:
241 Failed: naming the package and its set when no extension of the
242 set releases a distribution of it, and naming the ecosystems
243 when its distributions name more than one, since a package
244 releases to one registry.
245 """
246 from livery.footman import fail
247
248 # A list, not a tuple: basedpyright narrows a tuple by the length
249 # checks below and then reads the last line's index as out of range.
250 named = list(dict.fromkeys(found for found, _name in distributions(package)))
251 if not named:
252 held = ", ".join(_set_of(package)) or "none"
253 fail(
254 f"{package.path}: its extensions ({held}) answer no registry: none of"
255 " them releases a distribution of it, so the release train has nowhere"
256 " to publish it. List the extension that releases it, or set [release]"
257 " publish = false to version and tag it without an upload"
258 )
259 if len(named) > 1:
260 fail(
261 f"{package.path}: its extensions answer more than one registry,"
262 f" {', '.join(named[:-1])} and {named[-1]}: each releases a"
263 " distribution of it, and a package releases to one registry. List"
264 " the extensions that release it to one of them"
265 )
266 return named[0]
267
268
269def registry(package: Package) -> Registry:(empty)
270 """The registry *package* releases to, as a probe of the versions it serves.
271
272 Its set's answer to the ``registry`` query, from the extension that
273 releases its distribution. The release train polls the probe until
274 a version it uploaded is served.
275
276 Raises:
277 Failed: naming the package when its extensions answer no
278 registry or more than one (``ecosystem``), before any probe is
279 built, and naming the ecosystem when the extensions that
280 release it answer no probe of its registry.
281 """
282 from livery.footman import fail
283 from livery.workshop._queries import REGISTRY, answer
284
285 released = ecosystem(package)
286 probe = answer(package, REGISTRY)
287 if not probe:
288 fail(
289 f"{package.path}: its extensions release it to {released} and answer"
290 " no probe of that registry, so the release train cannot see what it"
291 " serves"
292 )
293 return probe
294
295
296def has_isolated_test(package: Package) -> bool:(empty)
297 """Whether *package*'s release tests its built artifact on the isolated side.
298
299 Whether its set adds a step serving the test phase's isolated side,
300 as python does for the wheel it builds.
301 """
302 return bool(_isolated_tests(package))
303
304
305def isolated_test((empty)
306 package: Package, root: Path, *, resolution: str, release_dirs: tuple[Path, ...]
307) -> dict[str, str]:
308 """Run *package*'s test phase on its isolated side at *resolution*; what it got.
309
310 Each distribution the run installed, to its version. *resolution*
311 is ``floor``, ``latest`` or ``head``; *release_dirs* are the
312 co-released set's ``dist/`` directories, the only place the run
313 finds a sibling's unpublished wheel. Ask
314 [livery.workshop._lifecycle.has_isolated_test][] first: a package
315 with no isolated test refuses here.
316
317 Raises:
318 Failed: naming the package when its set adds no step on the test
319 phase's isolated side.
320 """
321 from livery.footman import fail
322
323 if not _isolated_tests(package):
324 fail(
325 f"{package.path}: nothing tests its release isolated: its extensions"
326 " add no step on the test phase's isolated side"
327 )
328 inputs: dict[str, object] = {
329 "isolated": True,
330 "resolution": resolution,
331 "release-dirs": list(release_dirs),
332 }
333 ctx = _served(package, "test", root, inputs)
334 resolved = cast("dict[object, object]", _provided(ctx, "resolved", dict))
335 return {str(name): str(version) for name, version in resolved.items()}
336
337
338def verify((empty)
339 package: Package,
340 root: Path,
341 *,
342 tree: Path,
343 version: str,
344 python: str,
345 index: str,
346 extras: str,
347) -> int:
348 """Install *package*'s released *version* alone and run its tests; the exit code.
349
350 *tree* is checked out at the release's receipt tag, *python* is the
351 interpreter, *index* where the version installs from and *extras*
352 the extras installed with it, comma-joined.
353
354 Raises:
355 Failed: naming the package, its set and the phase, when no
356 extension of the set adds a step to the verify phase.
357 """
358 inputs: dict[str, object] = {
359 "version": version,
360 "tree": tree,
361 "interpreter": python,
362 "index": index,
363 "extras": extras,
364 }
365 ctx = _served(package, "verify", root, inputs)
366 return cast("int", _provided(ctx, "exit-code", int))
367
368
369def declared_requirements(package: Package) -> dict[str, str]:(empty)
370 """What *package*'s native manifests require, each name to its constraint.
371
372 Empty for a package whose set reads no manifest, which declares no
373 requirement: ``layering.graph`` names each of its edges on a
374 sibling as missing from its manifests.
375 """
376 from livery.workshop._queries import REQUIREMENTS, answer
377
378 return dict(answer(package, REQUIREMENTS))
379
380
381def declared_test_requirements(package: Package) -> dict[str, str] | None:(empty)
382 """What *package*'s manifests require for its tests, each name to its constraint.
383
384 None for a package whose set answers no ``test-requirements``: the
385 package has no home for its test edges, and ``layering.graph``
386 judges none of them.
387 """
388 from livery.workshop._queries import TEST_REQUIREMENTS, answer, answers
389
390 if not answers(package, TEST_REQUIREMENTS):
391 return None
392 return dict(answer(package, TEST_REQUIREMENTS))
393
394
395def declare_requirement((empty)
396 package: Package, dependency: Package, floor: str, *, kind: str = "runtime"
397) -> list[str]:
398 """Write *dependency* at *floor* into *package*'s manifests; the files changed.
399
400 *kind* is the edge's: a build or runtime requirement is written by
401 the writers the package's set answers ``requirement-writers`` with,
402 and a test requirement by those it answers
403 ``test-requirement-writers`` with. Every writer is called. Each
404 takes a sibling of its own ecosystem alone, so the requirement
405 lands in the manifest of the dependency's ecosystem: python's
406 ``pyproject.toml`` for a sibling that holds python, conan's recipe
407 for a sibling that is a conan package. The files are relative to
408 the package; empty when the manifests name the dependency already,
409 and for a test requirement in a set with no writer of one, which
410 has no home for it.
411
412 Raises:
413 Failed: when no writer of the set takes *dependency*, naming
414 both sets; nothing is written then.
415 """
416 from livery.footman import fail
417 from livery.workshop._composition import extension_set
418 from livery.workshop._queries import (
419 REQUIREMENT_WRITERS,
420 TEST_REQUIREMENT_WRITERS,
421 answer,
422 )
423
424 writers = answer(
425 package, TEST_REQUIREMENT_WRITERS if kind == "test" else REQUIREMENT_WRITERS
426 )
427 if kind == "test" and not writers:427 ↛ 428line 427 didn't jump to line 428 because the condition on line 427 was never true
428 return []
429 taken = [
430 written
431 for writer in writers
432 if (written := writer(package, dependency, floor)) is not None
433 ]
434 if not taken:
435 own = ", ".join(extension_set(package)) or "no extension"
436 theirs = ", ".join(extension_set(dependency)) or "no extension"
437 what = "test requirement" if kind == "test" else "requirement"
438 fail(
439 f"{package.path} holds {own}, and no writer of its set takes a"
440 f" {what} on {dependency.path}, which holds {theirs}: a writer"
441 " takes a sibling of its own ecosystem alone. List an extension"
442 f" whose manifest takes {dependency.path}, or drop the dependency"
443 )
444 return list(dict.fromkeys(name for written in taken for name in written))
445
446
447def module_roots(package: Package) -> tuple[str, ...]:(empty)
448 """The names other packages reference *package*'s code by; empty for none."""
449 from livery.workshop._queries import MODULE_ROOTS, answer
450
451 return tuple(answer(package, MODULE_ROOTS))
452
453
454def references(package: Package) -> tuple[SourceReferences, ...]:(empty)
455 """What each of *package*'s sources references, one record per source.
456
457 The ``references`` answers of the package's set, combined as their
458 union. Empty for a package nothing answers for, such as one whose
459 language no extension reads sources of. Each record names a file
460 inside the package, and one extension answers for each file.
461
462 Raises:
463 QueryError: when an answer names a file outside the package,
464 naming the extension and the file, or when two extensions
465 answer for one file, naming both.
466 """
467 from livery.workshop._queries import REFERENCES, QueryError, answers
468
469 found: Mapping[str, Iterable[SourceReferences]] = answers(package, REFERENCES)
470 owners: dict[str, str] = {}
471 union: dict[SourceReferences, None] = {}
472 for name, answered in found.items():
473 for source in answered:
474 if not _inside(package, source.path):
475 raise QueryError(
476 f"{package.path}: {REFERENCES.name}: {name} answers for"
477 f" {source.path}, a file outside the package; an answer"
478 " names the package's own sources"
479 )
480 held = owners.setdefault(source.path, name)
481 if held != name:
482 raise QueryError(
483 f"{package.path}: {REFERENCES.name}: {held} and {name} both"
484 f" answer for {source.path}; one extension of a package"
485 " answers for each source"
486 )
487 union[source] = None
488 return tuple(union)
489
490
491def _inside(package: Package, path: str) -> bool:(empty)
492 """Whether *path*, relative to the workspace root, is a file inside *package*."""
493 from pathlib import PurePosixPath
494
495 return path.startswith(f"{package.path}/") and ".." not in PurePosixPath(path).parts
496
497
498def _run_steps((empty)
499 package: Package, phase: str, root: Path, inputs: Mapping[str, object]
500) -> PhaseContext | None:
501 """Run *phase* over *package* with the engine's *inputs*; None without steps.
502
503 None when no extension of the package's set adds steps to the
504 phase. A step an extension of the set deletes is none of them. The
505 steps run through the one walk
506 ([livery.workshop._phases.walk_steps][]), the context naming the
507 package and the phase.
508 """
509 steps = _phase_steps(package, phase)
510 if not steps:
511 return None
512 from livery.workshop._phases import PhaseContext, walk_steps
513
514 ctx = PhaseContext(root=root, packages=(package,), package=package, phase=phase)
515 return walk_steps(ctx, steps, inputs={phase: inputs})
516
517
518def _served((empty)
519 package: Package, phase: str, root: Path, inputs: Mapping[str, object]
520) -> PhaseContext:
521 """Run *phase* over *package* as `_run_steps` does; refuse a phase with no step.
522
523 Raises:
524 Failed: naming the package, its set and the phase, when no
525 extension of the set adds a step to the phase, so nothing
526 does what the release asks of it.
527 """
528 ctx = _run_steps(package, phase, root, inputs)
529 if ctx is None:
530 from livery.footman import fail
531
532 held = ", ".join(_set_of(package)) or "none"
533 fail(
534 f"{package.path}: its extensions ({held}) add no step to the {phase}"
535 " phase, so the release has nothing to run there. List the extension"
536 f" whose steps serve the {phase} phase"
537 )
538 return ctx
539
540
541def _isolated_tests(package: Package) -> tuple[StepRecord, ...]:(empty)
542 """The steps *package*'s set adds to the test phase that serve its isolated side."""
543 from livery.workshop._phases import ISOLATED, serves
544
545 return tuple(
546 record
547 for record in _phase_steps(package, "test")
548 if serves(record, {ISOLATED: True})
549 )
550
551
552def _phase_steps(package: Package, phase: str) -> tuple[StepRecord, ...]:(empty)
553 """The steps *package*'s set adds to *phase*, less those the set deletes.
554
555 Empty for a package listing none.
556 """
557 if not package.extensions:
558 return ()
559 from livery.workshop._composition import extension_set
560 from livery.workshop._extensions import installed_declaration
561 from livery.workshop._phases import phase_steps
562
563 return phase_steps(phase, extension_set(package), installed_declaration)
564
565
566def _provided(ctx: PhaseContext, key: str, kind: type | tuple[type, ...]) -> object:(empty)
567 """What *ctx*'s steps provided under *key*; refuses when none of them did."""
568 from livery.footman import fail
569
570 value = ctx.result(key)
571 if not isinstance(value, kind):
572 fail(
573 f"{ctx.member.path}: the {ctx.phase} phase's steps provide no {key},"
574 " which the release train reads from the phase"
575 )
576 return value
577
578
579def _set_of(package: Package) -> tuple[str, ...]:(empty)
580 """The extensions *package*'s set holds, as its queries ask them."""
581 from livery.workshop._composition import extension_set
582
583 return extension_set(package)