1"""What the engine asks of a package: build, versions, tests, publish, requirements.
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.
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"""
29 from collections.abc import Iterable, Mapping
30 from pathlib import Path
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
40 """Run the sync phase over the workspace at *root* holding *packages*.
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
55 run_registered(PhaseContext(root=root, packages=tuple(packages), phase="sync"))
58#: What the release train's build gives the build phase beside the
59#: epoch: the isolated side, in the release configuration.
64 """Build *package*'s release artifacts into its ``dist/``; that directory.
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.
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.
77 Returns:
78 The directory the build phase's steps wrote the artifacts into.
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
88 ctx = _served(package, "build", root, {**RELEASE_BUILD, "epoch": epoch})
89 return cast("Path", _provided(ctx, "dist", Path))
93 """The version *package*'s own manifest declares.
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
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
116 """Every file the stamp phase's steps write: the version, and the floors.
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
126 return tuple(answer(package, VERSION_FILES))
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.
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.
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
156 changed.append(CONTRACT)
157 return changed
161 """Raise each ``[[depends]]`` floor of *package*'s contract on one of *floors*.
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
169 from livery.workshop._contract import CONTRACT
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
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.
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.
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
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))
224 """The distributions *package* releases, each as its ecosystem and its name.
226 Its set's answers to the ``distributions`` query, combined.
227 """
228 from livery.workshop._queries import DISTRIBUTIONS, answer
230 return answer(package, DISTRIBUTIONS)
234 """The one ecosystem *package* releases to, which its registry resolves by.
236 The ecosystem its distributions name (``distributions``): the release
237 train publishes the package to that ecosystem's registry and probes
238 it there.
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
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]
270 """The registry *package* releases to, as a probe of the versions it serves.
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.
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
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
297 """Whether *package*'s release tests its built artifact on the isolated side.
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))
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.
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.
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
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()}
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.
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.
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))
370 """What *package*'s native manifests require, each name to its constraint.
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
378 return dict(answer(package, REQUIREMENTS))
382 """What *package*'s manifests require for its tests, each name to its constraint.
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
390 if not answers(package, TEST_REQUIREMENTS):
391 return None
392 return dict(answer(package, TEST_REQUIREMENTS))
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.
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.
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 )
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))
448 """The names other packages reference *package*'s code by; empty for none."""
449 from livery.workshop._queries import MODULE_ROOTS, answer
451 return tuple(answer(package, MODULE_ROOTS))
455 """What each of *package*'s sources references, one record per source.
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.
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
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)
492 """Whether *path*, relative to the workspace root, is a file inside *package*."""
493 from pathlib import PurePosixPath
495 return path.startswith(f"{package.path}/") and ".." not in PurePosixPath(path).parts
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.
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
514 ctx = PhaseContext(root=root, packages=(package,), package=package, phase=phase)
515 return walk_steps(ctx, steps, inputs={phase: inputs})
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.
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
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
542 """The steps *package*'s set adds to the test phase that serve its isolated side."""
543 from livery.workshop._phases import ISOLATED, serves
545 return tuple(
546 record
547 for record in _phase_steps(package, "test")
548 if serves(record, {ISOLATED: True})
549 )
553 """The steps *package*'s set adds to *phase*, less those the set deletes.
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
563 return phase_steps(phase, extension_set(package), installed_declaration)
567 """What *ctx*'s steps provided under *key*; refuses when none of them did."""
568 from livery.footman import fail
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
580 """The extensions *package*'s set holds, as its queries ask them."""
581 from livery.workshop._composition import extension_set
583 return extension_set(package)