livery.workshop._lifecycle¶
livery.workshop._lifecycle ¶
What the engine asks of a package: build, versions, tests, publish, requirements.
The release train, the layering phase and the docs reach a package's artifacts and manifests through these functions alone: its build, the version its manifest declares, the files a version is written into, writing a version, testing the built artifact in isolation, publishing what it built and the registry it goes to, verifying a released version, its declared requirements, writing one, the names other packages reference its code by, and what its sources reference. A question is a query (livery.workshop._queries.Query) the package's set answers, the extensions it lists and those they require; a build, a stamp, an isolated test, a publish or a verification runs as the package's phase (livery.workshop._phases.walk_steps), the steps its set adds to it. So a caller never names an extension.
A question nothing in the set answers gets the query's empty answer: no module roots, no requirements. The version is the one question an empty answer cannot serve, and it refuses naming the query. A phase the set adds no step to refuses the release, naming the phase. A package that lists no extension holds none: every question gets its empty answer, and every phase refuses.
Functions:
| Name | Description |
|---|---|
sync |
Run the sync phase over the workspace at root holding packages. |
build_release |
Build package's release artifacts into its |
current_version |
The version package's own manifest declares. |
version_files |
Every file the stamp phase's steps write: the version, and the floors. |
stamp |
Write version and raise package's floors in its manifests; the files changed. |
publish |
Upload package's built artifacts to target; False when all were there. |
distributions |
The distributions package releases, each as its ecosystem and its name. |
ecosystem |
The one ecosystem package releases to, which its registry resolves by. |
registry |
The registry package releases to, as a probe of the versions it serves. |
has_isolated_test |
Whether package's release tests its built artifact on the isolated side. |
isolated_test |
Run package's test phase on its isolated side at resolution; what it got. |
verify |
Install package's released version alone and run its tests; the exit code. |
declared_requirements |
What package's native manifests require, each name to its constraint. |
declared_test_requirements |
What package's manifests require for its tests, each name to its constraint. |
declare_requirement |
Write dependency at floor into package's manifests; the files changed. |
module_roots |
The names other packages reference package's code by; empty for none. |
references |
What each of package's sources references, one record per source. |
Attributes:
| Name | Type | Description |
|---|---|---|
RELEASE_BUILD |
Mapping[str, object]
|
|
RELEASE_BUILD
module-attribute
¶
sync ¶
Run the sync phase over the workspace at root holding packages.
The phase is what the workspace and its members need before
uv sync installs them: the steps the listed extensions
registered at mount, each once over the workspace, and a step that
judges one package at a time once for each of packages whose set
holds an extension it names. A workspace step that names
extensions runs while one of packages holds one of them, and not
at all while none does. conan's profile step is one: it runs once
while a package holds conan, a package that lists nanobind among
them, since its set holds conan. With no step registered, the phase
runs nothing.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
build_release ¶
Build package's release artifacts into its dist/; that directory.
The release train's build: the steps package's set adds to the
build phase, run on the phase's isolated side in the release
configuration. One of them provides the dist directory it
wrote.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package
|
Package
|
The member to build. |
required |
root
|
Path
|
The workspace root package is a member of. |
required |
epoch
|
int
|
The build's source date in seconds, so two builds of one tree are the same bytes; 0 takes the build tool's own. |
0
|
Returns:
| Type | Description |
|---|---|
Path
|
The directory the build phase's steps wrote the artifacts into. |
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package, its set and the phase, when no
extension of the set adds a step to the build phase; and
naming the package, when the steps that ran provide no
|
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
current_version ¶
The version package's own manifest declares.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package, its set and the query, when nothing in the set answers the version, since a release reads and stamps it. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
version_files ¶
Every file the stamp phase's steps write: the version, and the floors.
A file holding only floors is among them, as a recipe that names no version is. A caller that stamps for one build keeps these files first, then restores them. Empty for a package whose set names none. The floors the base raises are in the package's own contract, which is not among them.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
stamp ¶
stamp(package: Package, root: Path, version: str, *, floors: Mapping[str, str] | None = None) -> list[str]
Write version and raise package's floors in its manifests; the files changed.
The stamp phase's steps write the version into their own manifests,
and raise there each floor a manifest declares on one of floors:
the members released with package, each by its path, to the
version it releases at. The base raises the floor of each
[[depends]] edge of the package's contract on one of them.
Without floors no floor moves, as for a member released alone.
Each file is named relative to the package's directory.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package, its set and the phase, when no extension of the set adds a step to the stamp phase. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
publish ¶
publish(package: Package, root: Path, *, version: str, target: RegistryTarget, prebuilt: bool = False) -> bool
Upload package's built artifacts to target; False when all were there.
A re-run walks past what an earlier attempt uploaded, so False is
a success that uploaded nothing. prebuilt says a job of the run
built the package and the run collected what it built into the
package's dist/, so this runner built nothing. The publish
phase gets it as prebuilt, and a step whose upload reads
something other than dist/, as conan's reads its cache, puts
the collected files there first.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package, its set and the phase, when no extension of the set adds a step to the publish phase. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
distributions ¶
The distributions package releases, each as its ecosystem and its name.
Its set's answers to the distributions query, combined.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
ecosystem ¶
The one ecosystem package releases to, which its registry resolves by.
The ecosystem its distributions name (distributions): the release
train publishes the package to that ecosystem's registry and probes
it there.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package and its set when no extension of the set releases a distribution of it, and naming the ecosystems when its distributions name more than one, since a package releases to one registry. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
registry ¶
The registry package releases to, as a probe of the versions it serves.
Its set's answer to the registry query, from the extension that
releases its distribution. The release train polls the probe until
a version it uploaded is served.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package when its extensions answer no
registry or more than one ( |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
has_isolated_test ¶
Whether package's release tests its built artifact on the isolated side.
Whether its set adds a step serving the test phase's isolated side, as python does for the wheel it builds.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
isolated_test ¶
isolated_test(package: Package, root: Path, *, resolution: str, release_dirs: tuple[Path, ...]) -> dict[str, str]
Run package's test phase on its isolated side at resolution; what it got.
Each distribution the run installed, to its version. resolution
is floor, latest or head; release_dirs are the
co-released set's dist/ directories, the only place the run
finds a sibling's unpublished wheel. Ask
livery.workshop._lifecycle.has_isolated_test first: a package
with no isolated test refuses here.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package when its set adds no step on the test phase's isolated side. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
verify ¶
verify(package: Package, root: Path, *, tree: Path, version: str, python: str, index: str, extras: str) -> int
Install package's released version alone and run its tests; the exit code.
tree is checked out at the release's receipt tag, python is the interpreter, index where the version installs from and extras the extras installed with it, comma-joined.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the package, its set and the phase, when no extension of the set adds a step to the verify phase. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
declared_requirements ¶
What package's native manifests require, each name to its constraint.
Empty for a package whose set reads no manifest, which declares no
requirement: layering.graph names each of its edges on a
sibling as missing from its manifests.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
declared_test_requirements ¶
What package's manifests require for its tests, each name to its constraint.
None for a package whose set answers no test-requirements: the
package has no home for its test edges, and layering.graph
judges none of them.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
declare_requirement ¶
declare_requirement(package: Package, dependency: Package, floor: str, *, kind: str = 'runtime') -> list[str]
Write dependency at floor into package's manifests; the files changed.
kind is the edge's: a build or runtime requirement is written by
the writers the package's set answers requirement-writers with,
and a test requirement by those it answers
test-requirement-writers with. Every writer is called. Each
takes a sibling of its own ecosystem alone, so the requirement
lands in the manifest of the dependency's ecosystem: python's
pyproject.toml for a sibling that holds python, conan's recipe
for a sibling that is a conan package. The files are relative to
the package; empty when the manifests name the dependency already,
and for a test requirement in a set with no writer of one, which
has no home for it.
Raises:
| Type | Description |
|---|---|
Failed
|
when no writer of the set takes dependency, naming both sets; nothing is written then. |
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
module_roots ¶
The names other packages reference package's code by; empty for none.
Source code in packages/workshop/src/livery/workshop/_lifecycle.py
references ¶
references(package: Package) -> tuple[SourceReferences, ...]
What each of package's sources references, one record per source.
The references answers of the package's set, combined as their
union. Empty for a package nothing answers for, such as one whose
language no extension reads sources of. Each record names a file
inside the package, and one extension answers for each file.
Raises:
| Type | Description |
|---|---|
QueryError
|
when an answer names a file outside the package, naming the extension and the file, or when two extensions answer for one file, naming both. |