livery.workshop¶
livery.workshop ¶
The livery ecosystem's devkit.
The task surface arrives through the footman plugin
(plugin("livery.workshop")); this module's own API is the extension
walk (livery.workshop.extension_names, livery.workshop.workspace_root),
the package contracts
(livery.workshop.discover_packages, livery.workshop.verify_workspace
over livery.workshop.Package and livery.workshop.Edge). The forge
lane belongs to
livery.forge.Forge; the workshop orchestrates local, git, and forge
steps and never hands a raw forge verb to a user.
An extension in its own wheel declares itself in an extension.toml
beside the package its workshop.extensions entry point names: the
steps it adds to the gate's phases under [phases.<phase>.<step>],
each with its body under main, a template of its tool's words
with {paths} where the paths the run reaches go and
{arguments} where the words after -- go, or the function that
runs it as "module:function". A step in code takes a
livery.workshop.PhaseContext. One that narrows by paths reads them
from livery.workshop.scoped_paths, which answers
livery.workshop.WHOLE for the tool's configured whole, and
calls its tool through livery.workshop.run_batched; a workspace
step that declares no inputs narrows by packages and reads them
from livery.workshop.scoped_packages, and one that judges a
package at a time (scope = "package") reads its files from
livery.workshop.scoped_files. One that declares inputs judges
the whole workspace in every scope, and asks
livery.workshop.selected_files which of them this run's change
touched, with the context its run was handed; its widen
reference receives the run's livery.workshop.Changes. A step
declares the options a package may set on it under its options
and reads a package's value with livery.workshop.step_option,
which answers from the installed declaration in a process that
mounted nothing. A step names the extensions it judges packages by,
livery.workshop.step_extensions, and judges a package whose set
holds one of them: the extensions it lists and every one they
require, livery.workshop.extension_set. A step declared
enabled = false registers once the root contract turns it on at
the step's address, which livery.workshop.step_enabled answers.
A step asks a package's extensions
what it needs of the package with livery.workshop.answer: the
modules a type-completeness step verifies,
livery.workshop.PUBLIC_MODULES, or where the package's build
writes the compilation database a linter reads,
livery.workshop.COMPILE_COMMANDS. The workspace's own tests, the
tests directory at its root, are a unit of their own,
livery.workshop.workspace_suite, which holds the root's set. A
test step runs them beside the packages it judges while that set
holds an extension the step names: livery.workshop.scoped_suite
returns the unit then. A step whose tool of the store is not on
PATH refuses with livery.workshop.undeployed: the refusal
names the tool and the sync that deploys it.
An extension reads the workspace through the names the engine reads
it by: the root of the workspace a package is a member of,
livery.workshop.Package.root; a contract's judged keys,
livery.workshop.read_contract; a query's answer,
livery.workshop.answer, asked with a package or
the workspace root through a livery.workshop.Query handle; the CI
run it belongs to, livery.workshop.ci_run, a
livery.workshop.RunContext or None at a desk; the workspace's
repository on its forge, livery.workshop.forge_repository, and,
connected, livery.workshop.this_repository on
livery.workshop.this_forge, whose everyday token
livery.workshop.forge_token resolves; the
registry an artifact kind goes to, livery.workshop.registry, a
livery.workshop.RegistryTarget, which a step of the publish
phase reads from its registry-target key with
livery.workshop.RegistryTarget.from_table; and the release
notes' provider the listed extensions answer,
livery.workshop.release_notes, which
answers the livery.workshop.ReleaseNotes protocol. A file an extension
writes outside the engine opens with
livery.workshop.generated_header. What a CI run changed
against the base it measures from is livery.workshop.ci_changes.
The guidance for one reader, livery.workshop.AGENT or
livery.workshop.HUMAN, is the composed set of
livery.workshop.Prose fragments livery.workshop.guidance
answers; each listed extension's shipped files live where
livery.workshop.shipped_content says; the gate's fixers run over
named files through livery.workshop.fix_files, and a phase's steps
over named packages through livery.workshop.run_phase_over; and
what the listed extensions declare for an extension is
livery.workshop.contributions_for. A phase the gate never runs,
one declared gated = false, runs over the workspace through
livery.workshop.run_phase, which first removes what a step that
stopped running declared it writes under outputs. The members come
in release order from livery.workshop.order_topologically, every
dependency before its dependents, and livery.workshop.release_tag
reads the member and the version a release tag names. A query's
combine function that decides between answers by what each answering
extension requires hands the lookup it is called with to
livery.workshop.nearest_extensions.
An extension that keeps records of a CI run reaches them through the names the gate's own records use. The workshop's series live on the checkout's state store, livery.workshop.state_store; on it, livery.workshop.RUNS keeps each check leg's files for one run until the gate job collects them. A check leg's entry leaves a file for the leg's one write with livery.workshop.leave_leg_file, and reads what the gate ran on the leg, a livery.workshop.LegScope, from livery.workshop.leg_scope. The gate job's entry leaves a section of the run's row with livery.workshop.leave_section. The branch whose run proved the checkout's tree, a livery.workshop.VerifiedBranch, is what livery.workshop.verified_branch reads. The check legs the gate produces are livery.workshop.check_legs, and those a pull request's run produces are livery.workshop.pull_request_legs, unless the pull request carries livery.workshop.EVERY_RUNNER_LABEL, when its run produces every leg; split into the shards the contract gives each runner they are livery.workshop.check_shards and livery.workshop.pull_request_shards, each shard spelled by a livery.workshop.Shard at the end of its label, which livery.workshop.platform_leg and livery.workshop.shard_of split. A shard's share of the items a test step partitions, pytest's test files, is what livery.workshop.partition packs from the medians livery.workshop.read_durations takes over the platform leg's rows in the livery.workshop.DURATIONS family, bounded by livery.workshop.checkout_time; the set it partitioned has the digest livery.workshop.files_digest, and the shard leaves what it ran with livery.workshop.leave_shard, a livery.workshop.ShardMarker that livery.workshop.read_shard reads back. Of a set of units, each a member's suite or the workspace's own tests at livery.workshop.WORKSPACE_TESTS, livery.workshop.tested keeps those a test step runs. Whether a package holds the extension of the workshop's own language is livery.workshop.holds_runtime_language, and what a path is to its package, a livery.workshop.Category, is livery.workshop.category_of.
An extension that builds a release's artifacts in a CI job of its own
reaches the release through the names the release train uses. The
members a release squash releases, each with its version, are what
livery.workshop.discover_release reads at a commit, and
livery.workshop.build_release builds one of them as the release
train does, into its dist/. The members a job of the release point
builds before the wave are the workspace's answer to
livery.workshop.JOB_BUILT_MEMBERS. The interpreters the CI matrix
runs are livery.workshop.python_matrix. What the checkout
installed of each tool is livery.workshop.tool_receipts, a
livery.workshop.ToolReceipt per tool, and the tool store's home on
this machine is livery.workshop.store_home.
An extension that judges a language's sources reads what each source
references from its package's references answer: one
livery.workshop.SourceReferences per source, and a
livery.workshop.ReferencedName for each name the source references
and how it makes the reference. Which member owns a referenced name is
what livery.workshop.neighbours answers, a
livery.workshop.Neighbours made from each member's module roots. A
step over the sources runs over every one of them when
livery.workshop.graph_changed says a contract, a native manifest or
a root src/ changed.
An extension that runs python in a venv names its interpreter with livery.workshop.venv_python and its executables directory with livery.workshop.scripts_dir. A runner that starts pytest shares two names with the workshop's pytest plugins: livery.workshop.is_example says which files the examples plugin collects as documentation examples, and the speed plugin sums each package's test time into the file the runner names in the variable livery.workshop.SPEED_FILE_VARIABLE. The plugins read three more names of the workshop: the speed plugin sums by the package livery.workshop.package_of names for a test's node id, the points plugin selects the tests of the CI point named in livery.workshop.POINT_VARIABLE, and the layout plugin checks the tests directory of each directory livery.workshop.package_directories lists. Each package's mark on each check leg, a livery.workshop.SpeedMark, is what livery.workshop.speed_marks reads.
An extension adds steps to a package's lifecycle phases under
[phases.<phase>.<step>], with the keys every step takes;
each runs once per package whose set holds the extension and
receives the same livery.workshop.PhaseContext, which carries the
keys the steps provide and read. It
answers questions about a package under [queries]: each a
livery.workshop.Query the workshop defines, such as
livery.workshop.PUBLIC_MODULES or livery.workshop.EXECUTABLES,
which livery.workshop.answer asks of a package's extensions and
combines by the query's rule. Each function it answers
requirement-writers with writes a requirement on a sibling into
the package's manifest, and is a livery.workshop.RequirementWriter.
Modules:
| Name | Description |
|---|---|
testing |
What an extension's steps and categories are judged against: the conformance kit. |
Classes:
| Name | Description |
|---|---|
Category |
A path's category, and who supplied the rule that answered. |
RunContext |
The CI run this process belongs to, as the runner's environment names it. |
Changes |
What changed since the tree a gate measures from. |
Edge |
One declared dependency edge of a package. |
Neighbours |
Who owns each name the workspace's members reference each other by. |
Package |
One package, as its contract declares it. |
ReferencedName |
One name a source references, and how the source makes the reference. |
SourceReferences |
What one source references: one record of a package's |
PhaseContext |
What a run hands a step: the workspace, the run's scope, and the phase's keys. |
Prose |
One prose fragment: a file an extension ships, or a render from the registries. |
Query |
A handle naming a declared query, typed by its answer. |
RequirementWriter |
Write a package's requirement on a sibling into one ecosystem's manifest. |
RegistryTarget |
One resolved registry for one artifact kind. |
ReleaseNotes |
What a release-notes provider answers. |
Shard |
One shard of a leg: which of how many, spelled |
ShardMarker |
What a shard left in |
SpeedMark |
A package's mark on one check leg and the row that set it. |
ToolReceipt |
What this checkout installed of one tool, as its file records it. |
LegScope |
What the gate ran on one check leg, as the marker the leg left says. |
VerifiedBranch |
The branch whose run proved a tree, or why the record could not say. |
Functions:
| Name | Description |
|---|---|
category_of |
Say what path, relative to package's directory, is to the package. |
ci_run |
The CI run this process belongs to, or None at a desk. |
state_store |
Open the state store of the checkout at root, with the workshop's policy. |
extension_set |
The extensions package holds: its list and every extension the list requires. |
nearest_extensions |
Of the extensions names, the ones no other of them requires: the nearest. |
read_contract |
The contract in directory, its keys judged: the workspace's or a package's. |
is_example |
Tell whether path is a documentation example. |
contributions_for |
What the installed extensions declare for target, by extension. |
extension_names |
The extensions the workspace installs and mounts, in mount order. |
shipped_content |
Each extension of the workspace's stack with its |
workspace_root |
The nearest ancestor carrying the workspace's contract, or None. |
forge_repository |
This workspace's repository name on its forge: the name |
this_forge |
The workspace's forge, per the contract's |
this_repository |
The workspace's repository, per the contract and the remote. |
order_topologically |
packages in release order: every dependency before its dependents. |
run_batched |
Run call once per batch of paths; one refusal naming every failure. |
build_release |
Build package's release artifacts into its |
leave_leg_file |
Leave data in the leg's spool as name, for the leg's one write. |
leave_section |
Leave a section of the run's row, a number per package, for the gate job. |
discover_packages |
Every package the workspace carries, by its contract, sorted by path. |
holds_runtime_language |
Say whether package holds the extension of the workshop's own language. |
neighbours |
Map each module root packages ship to the member that ships it. |
package_directories |
List every directory under |
release_tag |
The package path and version a release tag names; None for another tag. |
verify_workspace |
The layering lint: check every workspace invariant, or raise. |
workspace_suite |
The workspace's own tests, the |
run_phase |
Run a phase the gate never runs over the workspace at root; the shared context. |
check_legs |
Name the check legs the gate produces, |
check_shards |
Name the shard legs the gate produces, split as |
pull_request_legs |
Name the check legs a pull request's run produces, |
pull_request_shards |
Name the shard legs a pull request's run produces, split as the contract says. |
guidance |
The guidance one reader gets in the workspace at root, in reading order. |
generated_header |
The provenance header a generated file opens with, as a comment block. |
discover_release |
The members the release squash at ref releases, each with its version. |
python_matrix |
The CI matrix: the contract's declaration, else the floor and the newest minor. |
scripts_dir |
Name venv's executables directory: |
venv_python |
Name venv's interpreter on this platform. |
ci_changes |
What this CI run changed against the base it measures from; None for everything. |
fix_files |
Run the gate's fixers over paths, judging nothing. |
run_phase_over |
Run the steps of phase over packages whole; nothing recorded as proved. |
answer |
The answer to query about subject: the extensions' answers, combined. |
registry |
The registry the workspace at root reads and publishes kind artifacts at. |
release_notes |
The provider the extensions listed at root answer; None when none answers. |
checkout_time |
The committer time of HEAD's commit in the checkout at root, timezone-aware. |
files_digest |
A hex digest of the sorted names in files. |
leave_shard |
Leave the shard's record in |
partition |
Pack items into count shards by their durations, every item in exactly one. |
platform_leg |
The leg label without its shard; a label without one is returned as it is. |
read_durations |
The median seconds per item, and the head, of leg's rows before before. |
read_shard |
Read the record a shard left in |
shard_of |
The shard the leg label ends in; |
package_of |
Name the workspace package a test belongs to, from its pytest node id. |
speed_marks |
Read each package's current test-time mark on each check leg. |
graph_changed |
Tell whether a contract, a native manifest or a root |
scoped_files |
The files of package the step name judges in this run, absolute. |
scoped_packages |
The members the package-narrowing step name judges in this run. |
scoped_paths |
The paths the path-narrowing step name judges in this run. |
scoped_suite |
The workspace's own tests, when the step name judges them. |
selected_files |
The files the running step judges in this run; None for every file it reads. |
step_enabled |
Whether the step name is on in the workspace at root. |
step_extensions |
The extensions the step name names in its |
step_option |
What package sets for the step name's option, or the option's default. |
tested |
Keep the units whose suites a registered step of the test phase runs. |
forge_token |
The everyday token and the variable that supplied it. |
store_home |
The tool store's home on this machine, where every checkout's tools are. |
tool_receipts |
What the checkout at root installed of each tool, by the tool's name. |
undeployed |
Refuse the task: name is a tool of the store and is not on |
leg_scope |
Read what the gate ran on this leg from the marker it left at root. |
verified_branch |
Read which branch's run proved the tree checked out at root. |
Attributes:
| Name | Type | Description |
|---|---|---|
POINT_VARIABLE |
|
|
RUNS |
Keyed
|
|
WORKSPACE_TESTS |
|
|
EVERY_RUNNER_LABEL |
|
|
AGENT |
|
|
HUMAN |
|
|
COMPILE_COMMANDS |
Query[Path | None]
|
|
CURRENT_VERSION |
Query[str]
|
|
DISTRIBUTIONS |
Query[tuple[tuple[str, str], ...]]
|
|
EXECUTABLES |
Query[tuple[str, ...]]
|
|
JOB_BUILT_MEMBERS |
Query[Mapping[str, str]]
|
|
MODULE_ROOTS |
Query[tuple[str, ...]]
|
|
PUBLIC_MODULES |
Query[tuple[str, ...]]
|
|
REQUIREMENTS |
Query[Mapping[str, str]]
|
|
VERSION_FILES |
Query[tuple[Path, ...]]
|
|
DURATIONS |
Keyed
|
|
SPEED_FILE_VARIABLE |
|
|
NONE |
|
|
PACKAGE |
|
|
PACKAGES |
|
|
PATHS |
|
|
WHOLE |
|
|
__version__ |
|
RUNS
module-attribute
¶
COMPILE_COMMANDS
module-attribute
¶
DISTRIBUTIONS
module-attribute
¶
JOB_BUILT_MEMBERS
module-attribute
¶
DURATIONS
module-attribute
¶
DURATIONS: Keyed = git.Keyed('durations', ('leg',), window=WINDOW, schema=SCHEMA, current=_current_legs)
__all__
module-attribute
¶
__all__ = ['AGENT', 'COMPILE_COMMANDS', 'CURRENT_VERSION', 'DISTRIBUTIONS', 'DURATIONS', 'EVERY_RUNNER_LABEL', 'EXECUTABLES', 'HUMAN', 'JOB_BUILT_MEMBERS', 'MODULE_ROOTS', 'NONE', 'PACKAGE', 'PACKAGES', 'PATHS', 'POINT_VARIABLE', 'PUBLIC_MODULES', 'REQUIREMENTS', 'RUNS', 'SPEED_FILE_VARIABLE', 'VERSION_FILES', 'WHOLE', 'WORKSPACE_TESTS', 'Category', 'Changes', 'Edge', 'LegScope', 'Neighbours', 'Package', 'PhaseContext', 'Prose', 'Query', 'ReferencedName', 'RegistryTarget', 'ReleaseNotes', 'RequirementWriter', 'RunContext', 'Shard', 'ShardMarker', 'SourceReferences', 'SpeedMark', 'ToolReceipt', 'VerifiedBranch', '__version__', 'answer', 'build_release', 'category_of', 'check_legs', 'check_shards', 'checkout_time', 'ci_changes', 'ci_run', 'contributions_for', 'discover_packages', 'discover_release', 'extension_names', 'extension_set', 'files_digest', 'fix_files', 'forge_repository', 'forge_token', 'generated_header', 'graph_changed', 'guidance', 'holds_runtime_language', 'is_example', 'leave_leg_file', 'leave_section', 'leave_shard', 'leg_scope', 'nearest_extensions', 'neighbours', 'order_topologically', 'package_directories', 'package_of', 'partition', 'platform_leg', 'pull_request_legs', 'pull_request_shards', 'python_matrix', 'read_contract', 'read_durations', 'read_shard', 'registry', 'release_notes', 'release_tag', 'run_batched', 'run_phase', 'run_phase_over', 'scoped_files', 'scoped_packages', 'scoped_paths', 'scoped_suite', 'scripts_dir', 'selected_files', 'shard_of', 'shipped_content', 'speed_marks', 'state_store', 'step_enabled', 'step_extensions', 'step_option', 'store_home', 'tested', 'testing', 'this_forge', 'this_repository', 'tool_receipts', 'undeployed', 'venv_python', 'verified_branch', 'verify_workspace', 'workspace_root', 'workspace_suite']
Category
dataclass
¶
RunContext
dataclass
¶
RunContext(forge: str, run_id: str, event: str, ref: str, head_sha: str = '', base_ref: str = '', leg: str = '', head_ref: str = '', labels: tuple[str, ...] = (), attempt: str = '')
The CI run this process belongs to, as the runner's environment names it.
Attributes:
| Name | Type | Description |
|---|---|---|
forge |
str
|
|
run_id |
str
|
The forge's identifier of the run (GitLab: the pipeline). |
event |
str
|
What started the run ( |
ref |
str
|
The ref the run is for, as the runner spells it. |
head_sha |
str
|
The commit the forge files the run under. On a pull request the checkout is the merge commit the forge synthesised, and the run's own head is the pull request's head, which the event payload names; on a push both are the same commit. Empty when the runner did not say. |
base_ref |
str
|
The branch a pull request proposes into, as the event payload names it (GitLab: the merge request's target); empty on a push or when the runner did not say. |
leg |
str
|
The check leg this process runs in ( |
head_ref |
str
|
The branch a pull request comes from, as the event payload names it (GitLab: the merge request's source), the base of the branch's own coverage record; empty on a push or when the runner did not say. |
labels |
tuple[str, ...]
|
The pull request's label names, as the event payload
names them (GitLab: |
attempt |
str
|
Which attempt of the run this is, as the runner
counts them from 1 (GitHub's and Gitea's
|
shard
property
¶
shard: Shard
The shard the leg runs as, read from the end of leg; one of one without.
check-windows-latest-3.14-2of4 runs as the second of four
shards; check-ubuntu-latest-3.14, and an empty leg, as the
one shard of one. The label is the only source, so the shard
and the leg cannot disagree. A livery.workshop.Shard.
Raises:
| Type | Description |
|---|---|
ValueError
|
When the label ends in a shard spelling outside
the form, such as |
Changes
dataclass
¶
What changed since the tree a gate measures from.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
The workspace root. |
paths |
tuple[str, ...]
|
The changed paths, root-relative posix, deleted ones included. |
before |
str
|
The commit or tree the paths were taken from; empty when the caller named the paths itself. |
Methods:
| Name | Description |
|---|---|
removed |
The changed paths the working tree no longer holds: deleted or moved. |
text_before |
path where the change is measured from; empty if unknown. |
Edge
dataclass
¶
One declared dependency edge of a package.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The dependency's identity: its directory path from the workspace root, as the tags spell it. |
kind |
str
|
|
floor |
str
|
The released version the native manifest must require. |
Neighbours
dataclass
¶
Who owns each name the workspace's members reference each other by.
livery.workshop.neighbours makes it from the members; a rule over the sources asks it which member a referenced name belongs to.
Attributes:
| Name | Type | Description |
|---|---|---|
owners |
Mapping[str, str]
|
Each module root a member ships, to the member's path. Each member's extensions answer its roots (livery.workshop.MODULE_ROOTS), so a reference resolves the same way whichever extension made it. |
by_path |
Mapping[str, Package]
|
Every member by its path. |
Methods:
| Name | Description |
|---|---|
owner_of |
The package path owning reference, longest prefix winning. |
owner_of ¶
The package path owning reference, longest prefix winning.
Empty when no package owns it: a third-party name, or the
standard library. Longest prefix, because three distributions
share the livery.toolroom namespace and the shortest match
would attribute two of them to the third.
Source code in packages/workshop/src/livery/workshop/_packages.py
Package
dataclass
¶
Package(directory: Path, path: str, name: str, depends: tuple[Edge, ...], publish: bool = True, categories: tuple[tuple[str, tuple[str, ...]], ...] = (), step_options: tuple[tuple[str, tuple[tuple[str, object], ...]], ...] = (), extensions: tuple[str, ...] = ())
One package, as its contract declares it.
Attributes:
| Name | Type | Description |
|---|---|---|
directory |
Path
|
The package directory. |
path |
str
|
The identity path from the workspace root
( |
name |
str
|
The distribution name ( |
depends |
tuple[Edge, ...]
|
The declared edges, in contract order. |
step_options |
tuple[tuple[str, tuple[tuple[str, object], ...]], ...]
|
The options the package sets on its steps, by
the table that sets them: |
categories |
tuple[tuple[str, tuple[str, ...]], ...]
|
The package's own reassignments of its paths
among the categories, |
publish |
bool
|
Whether the release train uploads the package's
artifact to its registry. |
extensions |
tuple[str, ...]
|
The extensions the package lists, in its contract's order: its canonical list, which the extensions it requires complete into its set. |
categories
class-attribute
instance-attribute
¶
step_options
class-attribute
instance-attribute
¶
step_options: tuple[tuple[str, tuple[tuple[str, object], ...]], ...] = field(default=(), hash=False)
member
property
¶
member: str
The package's path under packages/: forge, extensions/widgets.
It names the package in a release tag
(packages/<member>/v<version>) and everywhere else a
package is addressed by its place rather than its
distribution name.
root
property
¶
root: Path
The root of the workspace the package is a member of.
The package's directory with its path's parts taken off, read
from the two fields alone, without touching the disk: the root
is two directories above packages/forge, three above
packages/extensions/widgets, and one above the workspace's
own tests (livery.workshop.workspace_suite). A package whose
path is . is at the root, so its directory is the root.
Raises:
| Type | Description |
|---|---|
ValueError
|
when the directory does not end with the path, naming both. |
ReferencedName
dataclass
¶
One name a source references, and how the source makes the reference.
A record of livery.workshop.SourceReferences: an extension that
answers the references query makes one for each name a source
references, once for each way the source makes the reference.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The dotted name, as the source spells it. |
lazy |
bool
|
Whether only a function or a method body makes the reference, so importing the source does not. |
type_checking |
bool
|
Whether only a type checker makes it, so no run of the source does. |
optional |
bool
|
Whether the source handles the name being absent, so it runs without it. |
SourceReferences
dataclass
¶
SourceReferences(path: str, module: str = '', references: tuple[ReferencedName, ...] = (), accounted: tuple[str, ...] = ())
What one source references: one record of a package's references answer.
An extension that reads a language's sources answers the
references query with one record for each source file of the
package, and the layering steps resolve each name to the member
that owns it with livery.workshop.neighbours.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The source, relative to the workspace root, posix: a file inside the package the answer is about. |
module |
str
|
The name other code references the source by; empty for a source nothing references by name, such as a test. |
references |
tuple[ReferencedName, ...]
|
Every name the source references, in source order, once for each way the source makes the reference. |
accounted |
tuple[str, ...]
|
The names among them that the conventions of the source's language account for, so they need no dependency edge. |
PhaseContext
dataclass
¶
PhaseContext(root: Path, packages: tuple[Package, ...] = (), subset: tuple[Package, ...] | None = None, tests: Mapping[str, tuple[str, ...]] = dict[str, tuple[str, ...]](), examples: tuple[str, ...] = (), fix: bool = False, files: tuple[str, ...] = (), safe: bool = False, point: str = '', shard: Shard = ONE, catalogue: Mapping[str, tuple[tuple[str, str], ...]] | None = None, package: Package | None = None, selection: tuple[str, ...] = (), changes: Changes | None = None, arguments: tuple[str, ...] = (), step: str = '', phase: str = '', _steps: Mapping[str, StepRecord] = dict[str, 'StepRecord'](), _given: Mapping[str, Mapping[str, object]] = dict[str, Mapping[str, object]](), _shared: _Shared = _Shared())
What a run hands a step: the workspace, the run's scope, and the phase's keys.
One context serves one walk, and every step receives its own view
of it, with the step named in step and, for a package step,
the package it runs over in package. A step writes the keys its
table provides with livery.workshop.PhaseContext.provide
and reads the ones it reads with
livery.workshop.PhaseContext.read; the views share what is
written, so the engine reads a provided key back from the context
the walk returns (livery.workshop.PhaseContext.result). The
run phase's step that starts the executable records its exit
code with livery.workshop.PhaseContext.exit. A view is frozen:
a step that assigns an attribute changes a copy nobody reads, so
the keys and the exit code go through the methods.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
The workspace root. |
packages |
tuple[Package, ...]
|
Every package the workspace carries. |
subset |
tuple[Package, ...] | None
|
The packages a scoped gate judges, or None for the whole gate. |
tests |
Mapping[str, tuple[str, ...]]
|
Per package path, the test files that stand for the package's suite in this run. |
examples |
tuple[str, ...]
|
The package paths whose changed files are examples and nothing else: their examples run and no suite. |
fix |
bool
|
Whether the rewriters run in their fix mode. |
files |
tuple[str, ...]
|
The files the run is limited to, root-relative, from
|
safe |
bool
|
Whether the fixers run in their in-flight mode, which
removes no code: |
point |
str
|
The CI point whose tests the test phase selects; empty for the gate's own. |
shard |
Shard
|
The shard of a sharded check leg this run is, as
|
catalogue |
Mapping[str, tuple[tuple[str, str], ...]] | None
|
Every file the run may read, by unit, each with its category, listed once per walk by livery.workshop._steps.catalogue; None when there is no listing, and then every step that applies runs. |
package |
Package | None
|
The package a package step runs over, else None. |
selection |
tuple[str, ...]
|
The test files selected for that package, relative to it, else empty. |
changes |
Changes | None
|
What changed since the tree the run measures from, which selects what each workspace step with declared inputs judges (livery.workshop._influence.select); None when the run knows nothing of it, and then each judges everything. |
arguments |
tuple[str, ...]
|
The words after |
step |
str
|
The running step's name, |
phase |
str
|
The phase the engine runs, |
Methods:
| Name | Description |
|---|---|
exit |
Record code as the exit code |
for_package |
This context narrowed to one package and its selected tests. |
provide |
Write value under key, a key the running step's table provides. |
read |
The value under key, a key the running step's table reads. |
result |
The value under key once the phase ran, for the engine that ran it. |
tests
class-attribute
instance-attribute
¶
catalogue
class-attribute
instance-attribute
¶
judged
property
¶
The packages under judgment: the subset, or every package.
member
property
¶
member: Package
The package the step runs over, for a step that runs once per package.
Raises:
| Type | Description |
|---|---|
Failed
|
when the run names none: a workspace step, or a context built outside a package step's run. |
exit ¶
exit(code: int) -> None
Record code as the exit code fm run exits with.
The run phase's step that starts the executable calls it
with the executable's; the walk hands the code to the verb
through the context it returns.
Source code in packages/workshop/src/livery/workshop/_phases.py
for_package ¶
for_package(package: Package) -> PhaseContext
This context narrowed to one package and its selected tests.
Source code in packages/workshop/src/livery/workshop/_phases.py
provide ¶
Write value under key, a key the running step's table provides.
Raises:
| Type | Description |
|---|---|
PhaseError
|
when the step's table does not provide key, or value is not of the type it declares. |
Source code in packages/workshop/src/livery/workshop/_phases.py
read ¶
The value under key, a key the running step's table reads.
Its type is the one its provider declares, or the one the phase's declaration gives an engine key.
Raises:
| Type | Description |
|---|---|
PhaseError
|
when the step's table does not read key, the engine did not give it, or its provider wrote nothing under it. |
Source code in packages/workshop/src/livery/workshop/_phases.py
result ¶
The value under key once the phase ran, for the engine that ran it.
A key a step provided for the context's package, else one the engine gave the context's phase; None when neither wrote one.
Source code in packages/workshop/src/livery/workshop/_phases.py
Prose
dataclass
¶
Prose(section: str, topic: str, audience: str = '', extension: str = BASE_EXTENSION, source: Path | None = None, render: Render | None = None)
One prose fragment: a file an extension ships, or a render from the registries.
Attributes:
| Name | Type | Description |
|---|---|---|
section |
str
|
The section it belongs to, one of the base's. |
topic |
str
|
What it is about; with the section, its name. |
audience |
str
|
|
extension |
str
|
The extension that ships or renders it; empty for the repository's own. |
source |
Path | None
|
The shipped file, or None for a rendered fragment. |
render |
Render | None
|
The render, or None for a shipped fragment. |
Methods:
| Name | Description |
|---|---|
text |
The markdown for audience: the shipped text, or the render's answer. |
text ¶
The markdown for audience: the shipped text, or the render's answer.
Source code in packages/workshop/src/livery/workshop/_prose.py
Query
dataclass
¶
Query(name: str)
RequirementWriter ¶
Bases: Protocol
Write a package's requirement on a sibling into one ecosystem's manifest.
An extension answers the requirement-writers query with its
writers, and the test-requirement-writers query with the writers
of a requirement the package's tests alone have. Every writer of a
package's set is called for each requirement. A writer takes a
sibling of its own ecosystem alone: for any other sibling it writes
nothing and returns None, so the requirement lands in the manifest
of the sibling's ecosystem. A requirement no writer of the set
takes refuses, naming the sibling's set.
Methods:
| Name | Description |
|---|---|
__call__ |
Write dependency at floor into package's manifest. |
__call__ ¶
Write dependency at floor into package's manifest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package
|
Package
|
The package whose manifest gains the requirement. |
required |
dependency
|
Package
|
The sibling it requires. |
required |
floor
|
str
|
The lowest version of dependency the requirement takes. |
required |
Returns:
| Type | Description |
|---|---|
list[str] | None
|
The files changed, relative to the package; empty when the |
list[str] | None
|
manifest names dependency already. None for a sibling |
list[str] | None
|
outside the writer's ecosystem, which it leaves alone. |
Source code in packages/workshop/src/livery/workshop/_queries.py
RegistryTarget
dataclass
¶
RegistryTarget(kind: str, url: str, publish_url: str = '', local: bool = False, token: str = '', releases: bool = False)
One resolved registry for one artifact kind.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
Which artifact registry this is. |
url |
str
|
The registry's address: the read index for python (the
publish endpoint is |
publish_url |
str
|
Where python dists upload; empty means the publisher's own default resolution (uv publish and trusted publishing on pypi.org). Unused by other kinds. |
local |
bool
|
True when the target is a folder or share rather than a server. |
releases |
bool
|
True when the artifacts ride the forge's own
releases, attached to each member's receipt tag. The
route a conan package takes on a forge that hosts no
conan registry; |
token |
str
|
The registry credential, for reads and uploads alike: the kind's credential variable when set, else the forge lane's token when the forge rung answered. Empty reads anonymously and lets the publisher's own resolution decide. |
Methods:
| Name | Description |
|---|---|
from_table |
The target a |
from_table
classmethod
¶
from_table(table: Mapping[str, object]) -> RegistryTarget
The target a registry-target table holds.
The engine gives each step of the publish phase the registry
it resolved as the registry-target key: a table of this
class's fields by name, which the step reads back with this
constructor. The table holds kind and url, and a field
it leaves out takes its default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
table
|
Mapping[str, object]
|
Each field of the target by its name. |
required |
Returns:
| Type | Description |
|---|---|
RegistryTarget
|
The target the table holds. |
Raises:
| Type | Description |
|---|---|
ValueError
|
when the table is not a registry target: it has
no |
Source code in packages/workshop/src/livery/workshop/_registries.py
ReleaseNotes ¶
Bases: Protocol
What a release-notes provider answers.
Methods:
| Name | Description |
|---|---|
entry |
The notes the commits since package's last release earn. |
record |
Write version's entry into package's history. |
verify |
The problems with version's recorded notes; empty when sound. |
entry ¶
The notes the commits since package's last release earn.
Headed by version when one is given, as unreleased otherwise; empty when nothing unreleased touches the package.
Source code in packages/workshop/src/livery/workshop/_release_notes.py
record ¶
Write version's entry into package's history.
An empty entry records a placeholder for a person to write. Returns the files changed, each with a note for the reader, empty when the history already holds the version's entry.
Source code in packages/workshop/src/livery/workshop/_release_notes.py
verify ¶
Shard
dataclass
¶
One shard of a leg: which of how many, spelled <i>of<n>.
Attributes:
| Name | Type | Description |
|---|---|---|
index |
int
|
The shard's number, from 1. |
count |
int
|
How many shards the leg runs as. |
Raises:
| Type | Description |
|---|---|
ValueError
|
When the count is below 1, the index below 1, or the index above the count. |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
parse |
The shard text spells, |
__str__ |
|
__post_init__ ¶
parse
classmethod
¶
The shard text spells, 2of4.
Raises:
| Type | Description |
|---|---|
ValueError
|
When text is not of the form, naming it. |
Source code in packages/workshop/src/livery/workshop/_shard.py
ShardMarker
dataclass
¶
ShardMarker(shard: Shard, digest: str, items: tuple[str, ...], rows: tuple[str, ...], before: datetime, suites: tuple[str, ...] = (), attempt: str = '')
What a shard left in SHARD_FILE: what it ran and what it partitioned from.
Attributes:
| Name | Type | Description |
|---|---|---|
shard |
Shard
|
The shard the leg ran as. |
digest |
str
|
The digest of the set it partitioned, livery.workshop.files_digest of every item of every shard. |
items |
tuple[str, ...]
|
The items this shard ran, in packing order; pytest's are test files. |
rows |
tuple[str, ...]
|
The durations rows it read, newest first. |
before |
datetime
|
The bound it read them under, the checkout's committer time. |
suites |
tuple[str, ...]
|
The units whose items were in the set, by path. A unit the record does not name ran whole on the first shard, with every step that does not read the shard, so the first shard leaves its parts. A record written without the key names none. |
attempt |
str
|
The attempt of the run the shard ran in, as the runner
counts them (livery.workshop.RunContext's |
SpeedMark
dataclass
¶
A package's mark on one check leg and the row that set it.
The mark is the suite's summed test time the gate job judges the leg's runs against; livery.workshop.speed_marks reads the current mark of each package on each leg.
Attributes:
| Name | Type | Description |
|---|---|---|
package |
str
|
The package path ( |
leg |
str
|
The check leg ( |
seconds |
float
|
The mark: the suite's summed test time. |
kind |
str
|
|
by |
str
|
The run or the person that wrote the row. |
reason |
str
|
The reason an accept gave; empty otherwise. |
when |
str
|
When the row was written, ISO 8601. |
ToolReceipt
dataclass
¶
ToolReceipt(tool: str, version: str, host: str, kind: str, mode: str, deployment: str = '', tool_dir: str = '', paths: tuple[str, ...] = (), env: dict[str, str] = dict(), entry_points: tuple[str, ...] = (), source: str = 'store', answered: str = '', stamp: dict[str, str] = dict())
What this checkout installed of one tool, as its file records it.
fm sync writes one receipt per tool under the checkout's
.workshop/receipts/; livery.workshop.tool_receipts reads
them all.
Attributes:
| Name | Type | Description |
|---|---|---|
tool |
str
|
The tool's name. |
version |
str
|
The exact version installed, the lock's. |
host |
str
|
The host key it was installed for, this machine's. |
kind |
str
|
The installer kind. |
mode |
str
|
How it reached PATH, one of livery.toolroom.store.MODES. |
deployment |
str
|
The digest of the deployment installed; empty for a delegated kind, whose installer resolves the host. |
tool_dir |
str
|
Where the tool is, under the machine's store home (livery.workshop.store_home). |
paths |
tuple[str, ...]
|
The absolute directories the tool puts on PATH in |
env |
dict[str, str]
|
The variables the tool sets, resolved against its directory. |
entry_points |
tuple[str, ...]
|
The executables' names the tool puts on PATH:
linked into the checkout's bin directory in |
source |
str
|
|
answered |
str
|
The version the host's copy printed when it served; empty for a store install. |
stamp |
dict[str, str]
|
The host copy's identity when it served: its |
Methods:
| Name | Description |
|---|---|
to_json |
The receipt as a JSON object. |
load |
The receipt at path. |
to_json ¶
The receipt as a JSON object.
Source code in packages/workshop/src/livery/workshop/_tools.py
load
classmethod
¶
load(path: Path) -> ToolReceipt
The receipt at path.
Raises:
| Type | Description |
|---|---|
ValueError
|
for a file that is not a receipt of this schema, naming the file. |
Source code in packages/workshop/src/livery/workshop/_tools.py
LegScope
dataclass
¶
What the gate ran on one check leg, as the marker the leg left says.
Attributes:
| Name | Type | Description |
|---|---|---|
scope |
str
|
What the gate ran. |
packages |
tuple[str, ...]
|
The paths of the suites a narrowed gate ran; empty for every other scope. |
leg |
str
|
The label the leg's rows are keyed by
( |
base_tree |
str
|
The tree a narrowed gate measured from; empty for every other scope. |
VerifiedBranch
dataclass
¶
The branch whose run proved a tree, or why the record could not say.
Attributes:
| Name | Type | Description |
|---|---|---|
branch |
str
|
The pull request branch whose run proved the tree; empty when no row names the tree, when the row names no branch, as main's own run's does, and when the row could not be read. |
reason |
str
|
Why the record decided nothing: the tree has no id, or its row could not be read; empty when the record was read. |
category_of ¶
Say what path, relative to package's directory, is to the package.
The package's own [categories] exception answers first. Then
the most specific rule of the tables that answer for the package
wins, and between rules of one specificity the nearer table's: the
extension later in composition order, the base's table last.
Nothing matching is configuration, which the base's table also says
last. The base's table names the documentation's paths (prose,
nav, asset, example, generated) and everything else
configuration; the extensions a package holds name the rest,
such as source and test. The workspace's own tests
(livery.workshop.WORKSPACE_TESTS) are answered by one table of
the base's alone, in which a file under tests/ is test or
test-support.
Returns:
| Type | Description |
|---|---|
Category
|
The category's name, who supplied the rule that answered, and |
Category
|
the pattern that matched. |
Raises:
| Type | Description |
|---|---|
CategoryError
|
a ValueError, when two rules of one specificity and one table claim path for different categories or from different extensions. |
Source code in packages/workshop/src/livery/workshop/_categories.py
ci_run ¶
ci_run(environ: dict[str, str] | None = None) -> RunContext | None
The CI run this process belongs to, or None at a desk.
Read from the runner's environment, environ when given, the
process's own otherwise: GitHub's and Gitea's GITHUB_*
variables, GitLab's CI_*. An extension that behaves
differently in CI asks this, never a variable of one forge.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
state_store ¶
state_store(root: Path) -> StateStore
Open the state store of the checkout at root, with the workshop's policy.
A CI run may write a ci_only series and a desk may not; every
commit the store makes is by the tools' identity
(livery.git.tool_identity); a published listing travels in the
WORKSHOP_SNAPSHOT variable. Every series the workshop and its
extensions keep is read and written through it.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
extension_set ¶
The extensions package holds: its list and every extension the list requires.
In composition order, as the installed declarations declare it:
each extension after the ones it requires, ties alphabetical, and
alphabetical while the declared order has no start. The list's own
order means nothing. Empty for a package that lists none. The
workspace's own tests (livery.workshop.workspace_suite) hold the
root's set: the extensions [workspace] extensions lists and
every one they require, read from the root's contract on each call.
A step that names extensions judges a package whose set holds one
of them.
A list is composed once for each scan of the installed extensions, so a scan taken after an install composes it again.
Source code in packages/workshop/src/livery/workshop/_composition.py
nearest_extensions ¶
Of the extensions names, the ones no other of them requires: the nearest.
The rule a query's nearest combine applies, for a combine
function that decides between answers by what each answering
extension requires, transitively. lookup is the one such a
function is called with, passed on as it came. The nearest come in
the order of names; two of them means neither requires the other.
Answers whose requires close a cycle leave none nearest, and
layering.graph names the cycle.
Source code in packages/workshop/src/livery/workshop/_composition.py
read_contract ¶
The contract in directory, its keys judged: the workspace's or a package's.
directory is the workspace root or a package's directory, and the
contract is its workshop.toml. A package's contract is judged
against the extensions the workspace lists, the root's against its
own list, so a key of an extension the workspace does not list
refuses naming the extension.
Raises:
| Type | Description |
|---|---|
Failed
|
when the contract holds a key no listed extension and not the workshop declares, or a value of the wrong type, naming the file and every such key. |
FileNotFoundError
|
when directory holds no contract. |
Source code in packages/workshop/src/livery/workshop/_contract.py
is_example ¶
Tell whether path is a documentation example.
An example is a python file under a docs/examples/ directory at
any depth of path, which the examples plugin collects as one
test. A conftest.py there is the package's setup around the
examples, never an example. Nothing is read from the disk.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
The file, relative or absolute. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True for an example; False for any other file. |
Source code in packages/workshop/src/livery/workshop/_examples.py
contributions_for ¶
What the installed extensions declare for target, by extension.
The extensions come in composition order. An extension contributes
its [for.<target>] table while target is listed and the
extension's listing contributes to it (every listed target it
declares a table for, except those its root entry's without
names), the rule the mount grafts by; an extension that requires
target contributes its top-level tables. The tables come as the
declaration file holds them, and an extension that declares nothing
for target is left out, as is every extension when target is
not listed. start is a directory in the workspace, the working
directory when absent.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_names ¶
The extensions the workspace installs and mounts, in mount order.
The root's set and every package's set, in composition order
(livery.workshop._extensions.installed_set).
workspace_names reads the workspace list alone, and
root_set the root's set.
Source code in packages/workshop/src/livery/workshop/_extensions.py
shipped_content ¶
Each extension of the workspace's stack with its content/ directory.
The base first, then the installed set in mount order, each with the directory its shipped files live in; an extension that ships no content, or that no installed distribution declares, is left out.
Source code in packages/workshop/src/livery/workshop/_extensions.py
workspace_root ¶
The nearest ancestor carrying the workspace's contract, or None.
The workspace contract is the marker; a checkout without one is
not a workspace and gets no extensions. A package's own
workshop.toml, under packages/<name>/ or
packages/<group>/<name>/ of a workspace whose root holds a
contract, is passed over, so a verb run inside a package resolves
the workspace it belongs to. Without start, the search starts at
the running task's directory, the process's outside a run: a task
never reads the process's own, which a parallel run shares.
Source code in packages/workshop/src/livery/workshop/_extensions.py
forge_repository ¶
This workspace's repository name on its forge: the name origin points at.
The remote's URL in either spelling, https://host/owner/name or
git@host:owner/name, with or without .git.
Raises:
| Type | Description |
|---|---|
Failed
|
when root has no |
Source code in packages/workshop/src/livery/workshop/_forge_lane.py
this_forge ¶
The workspace's forge, per the contract's [forge] table.
The token is FORGE_TOKEN (host-qualified first); with neither
set, the backend's own documented fallback decides.
Returns:
| Type | Description |
|---|---|
Forge
|
The connected livery.forge.Forge. |
Source code in packages/workshop/src/livery/workshop/_forge_lane.py
this_repository ¶
this_repository(root: Path) -> Repository
The workspace's repository, per the contract and the remote.
Source code in packages/workshop/src/livery/workshop/_forge_lane.py
order_topologically ¶
packages in release order: every dependency before its dependents.
Kahn's walk over the [[depends]] edges restricted to the given
set; ties keep the input order so the result is deterministic. A
cycle cannot arise, the layering lint refuses one long before a
release asks.
Source code in packages/workshop/src/livery/workshop/_graph.py
run_batched ¶
run_batched(paths: Sequence[str], call: Callable[[tuple[str, ...]], None], *, limit: int = ARGV_LIMIT) -> None
Run call once per batch of paths; one refusal naming every failure.
Every batch runs even when an earlier one fails, so one gate shows every finding. An empty paths runs nothing.
Raises:
| Type | Description |
|---|---|
Failed
|
when any batch failed, with each failure's reason. |
Source code in packages/workshop/src/livery/workshop/_invoke.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
leave_leg_file ¶
Leave data in the leg's spool as name, for the leg's one write.
The leg's last entry, ci.leg, puts every file the spool holds
on the leg's per-run ref, a series of livery.workshop.RUNS,
beside its timing row and under its own name, where the gate job
reads it. That write refuses a file named row.json, the timing
row's own name. A file left twice under one name keeps the last
data.
Returns:
| Type | Description |
|---|---|
Path
|
The path of the file left under root. |
Source code in packages/workshop/src/livery/workshop/_metrics.py
leave_section ¶
Leave a section of the run's row, a number per package, for the gate job.
The gate job's ci.metrics.collect entry, before its verdict,
folds every section left at root into the run's file on the
metrics series, and fm ci.timings renders each as a trend, the
numbers followed by unit. A section left twice under one name
keeps the last numbers.
Returns:
| Type | Description |
|---|---|
str
|
The line to print, naming the section and how many packages |
str
|
it holds. |
Source code in packages/workshop/src/livery/workshop/_metrics.py
discover_packages ¶
Every package the workspace carries, by its contract, sorted by path.
Raises ValueError, with every finding listed, when a directory
under packages/ lacks its contract, or holds the runtime's
language (holds_runtime_language) and lacks the
pyproject.toml a distribution of that language carries: a
half-present package is a wrong state, not a lesser one. A
directory holding only what a removed package left behind is
named as such, with the fm sync that removes it. A package
that lists no extension holds none, and needs no project file.
Source code in packages/workshop/src/livery/workshop/_packages.py
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 | |
holds_runtime_language ¶
Say whether package holds the extension of the workshop's own language.
That extension is python. A member holds it when it lists it,
or when an extension it lists requires it. The workspace's own
tests hold it when the root's set does. Discovery asks this of
every member, so a member that lists it is answered without
reading any extension's declaration.
Source code in packages/workshop/src/livery/workshop/_packages.py
neighbours ¶
neighbours(packages: tuple[Package, ...]) -> Neighbours
Map each module root packages ship to the member that ships it.
Each member's set answers the roots it ships (livery.workshop.MODULE_ROOTS), so the map names no language. A member whose set answers no root owns no name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
packages
|
tuple[Package, ...]
|
The workspace's members, as livery.workshop.discover_packages reads them. |
required |
Returns:
| Type | Description |
|---|---|
Neighbours
|
The roots by owner and the members by path. |
Source code in packages/workshop/src/livery/workshop/_packages.py
package_directories ¶
List every directory under packages/ that should hold a package.
A package lives at packages/<name>/ or, inside a group
directory, at packages/<group>/<name>/. A group is a directory
with no workshop.toml of its own and at least one subdirectory
that has one. The directories are listed whether or not they carry
a contract, and nothing in them is judged;
livery.workshop.discover_packages reads and judges the
contracts. Reach for this where a glob would assume one level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The directories, sorted by path; empty when root has no |
...
|
|
Source code in packages/workshop/src/livery/workshop/_packages.py
release_tag ¶
The package path and version a release tag names; None for another tag.
A release tag is packages/<member>/v<major>.<minor>.<patch>, and
the member may sit in a group directory:
packages/extensions/widgets/v1.2.0 names
("packages/extensions/widgets", "1.2.0"). Every reader of
release tags parses them here, so a package at any depth under
packages/ releases like any other.
Source code in packages/workshop/src/livery/workshop/_packages.py
verify_workspace ¶
The layering lint: check every workspace invariant, or raise.
The graph's invariants (livery.workshop._packages.verify_graph) and the base's rules over every python source (livery.workshop._packages.import_problems) together, in one refusal. Returns the discovered packages when everything holds. Raises ValueError listing every violation verbatim otherwise:
- every
buildedge appears in the native manifest with a constraint carrying its floor, and every workspace-internal native dependency is a declared edge (agreement both ways); - the dependency graph is acyclic, so dependencies only point downward;
- the base imports no extension, and each reference a package's sources make to a sibling is a declared edge.
Source code in packages/workshop/src/livery/workshop/_packages.py
workspace_suite ¶
The workspace's own tests, the tests directory at its root, as a unit.
None when the workspace has none. The unit lists no extension
and holds the root's set. A test step whose extensions that set
holds runs it beside the members it judges
(livery.workshop.scoped_suite). It is no member, so no package
step judges it, and the workspace's category table answers for its
files (is_workspace_unit).
Source code in packages/workshop/src/livery/workshop/_packages.py
run_phase ¶
run_phase(root: Path, phase: str, *, outputs: Iterable[str] = ()) -> PhaseContext
Run a phase the gate never runs over the workspace at root; the shared context.
The steps the listed extensions register for phase, their own and
those of the [for.<target>] tables that apply, run side by side
through the walk every phase runs through, each workspace step once
and each package step once per package whose set holds an
extension it names. A workspace step that names extensions runs
while a package holds one of them; while none does, a line says so
and the step does not run. A phase with no registered step runs
nothing.
Before the steps run, the paths a step declares under outputs
are settled: each one the phase's last run recorded, or a step that
does not run now declares, is removed unless a step that runs now
declares it, and a line names each path removed. So a step that
stops running, its extension unlisted or no longer installed or the
step turned off, leaves nothing behind wherever it wrote, and a
running step finds its own output as it left it. The record lives
in the checkout's .workshop/state/.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root. |
required |
phase
|
str
|
The phase, one declared with |
required |
outputs
|
Iterable[str]
|
Paths this run writes that no step declares, such as those of the verbs a step runs: each in the shape a step declares one, and removed and recorded as a running step's are. |
()
|
Returns:
| Type | Description |
|---|---|
PhaseContext
|
The context the steps shared. |
Raises:
| Type | Description |
|---|---|
PhaseError
|
when nobody declares phase, naming the declared
phases; when the gate runs it; or when an output in
outputs is not a path below the root, or names |
Exception
|
the first failing step's, raised again once every step ran. |
Source code in packages/workshop/src/livery/workshop/_phases.py
1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 | |
check_legs ¶
Name the check legs the gate produces, check-<os>-<python> each.
One per runner the root contract names ([ci] runners,
ubuntu-latest without it) and Python the gate runs: the
contract's [ci] python-versions, or the newest Python of the
derived matrix. Each label is spelled as the job runner names the
leg it runs, the key of the leg's rows on the state store.
Source code in packages/workshop/src/livery/workshop/_points.py
check_shards ¶
Name the shard legs the gate produces, split as [ci] shards says.
One leg per runner and Python livery.workshop.check_legs names,
spelled as that leg, check-<os>-<python>, for a count of one,
the count of every runner the table does not name; and
check-<os>-<python>-<i>of<n> for each of the n shards
otherwise, in order. [ci] shards-max caps a count, 4 when
absent. The task fails, naming the key and the runner, when the
table names a runner [ci] runners does not list, gives a count
below 1 or above the cap, or gives one that is not a whole number.
Source code in packages/workshop/src/livery/workshop/_points.py
pull_request_legs ¶
Name the check legs a pull request's run produces, check-<os>-<python> each.
One per runner the root contract's [ci] pull-request-runners
names and Python the gate runs; the first runner's legs among those
livery.workshop.check_legs names when the key is absent. The
task fails, naming both lists, when the key names a runner
[ci] runners does not list, and when it is empty.
Source code in packages/workshop/src/livery/workshop/_points.py
pull_request_shards ¶
Name the shard legs a pull request's run produces, split as the contract says.
One leg per runner and Python livery.workshop.pull_request_legs
names, split as livery.workshop.check_shards splits the gate's:
by [ci] pull-request-shards, judged against the pull request's
runners, or by [ci] shards when that key is absent. The task
fails as check_shards fails, and as pull_request_legs fails.
Source code in packages/workshop/src/livery/workshop/_points.py
guidance ¶
The guidance one reader gets in the workspace at root, in reading order.
audience is livery.workshop.AGENT or livery.workshop.HUMAN.
The set is every fragment the mounted extensions ship, every
fragment the base renders, and the repository's own under
fragments/: by section, then by extension in mount order, the
repository's own last, then by name. A fragment written for the
other reader is left out.
Raises:
| Type | Description |
|---|---|
ValueError
|
when two fragments in the set deliver under one name, naming both. |
Source code in packages/workshop/src/livery/workshop/_prose.py
generated_header ¶
The provenance header a generated file opens with, as a comment block.
style is the file's comment marker (# or //), or html
for a <!-- --> block. lines say what writes the file and how
a reader changes it, for a file an extension writes outside the
engine; without them, the header says what every artifact the
engine emits says: the contract is the source, and an edit here is
drift.
Source code in packages/workshop/src/livery/workshop/_provenance.py
discover_release ¶
The members the release squash at ref releases, each with its version.
The members and their versions are the release's member list,
.release-manifest.json, as committed at ref: the record the
release branch writes when it prepares the set. They come in
release order, every dependency before its dependents
(livery.workshop.order_topologically). A rider file in the
squash changes nothing here, which is what makes hand-editing a
release branch safe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root. |
required |
ref
|
str
|
The commit whose member list is read, as git names it. |
required |
Returns:
| Type | Description |
|---|---|
tuple[tuple[Package, str], ...]
|
Each released member and the version the list states for it. |
Raises:
| Type | Description |
|---|---|
Failed
|
when the commit carries no readable member list, since it is then no release squash, naming the flag that points the publish at the squash; and when the list names a member the workspace does not hold. |
Source code in packages/workshop/src/livery/workshop/_publish.py
python_matrix ¶
The CI matrix: the contract's declaration, else the floor and the newest minor.
[ci] python-versions in the root's workshop.toml wins where
declared, so a development workspace runs one leg and a production
contract keeps the full pair. Without it the pair derives: the
lower bound of the root pyproject.toml's requires-python,
and the newest minor the workshop tests against, so a new Python
reaches every instance through a wheel bump. Each entry is a
version such as 3.14, or 3.14t for a free-threaded build: in
the declared order, or the floor first.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the key, when |
Source code in packages/workshop/src/livery/workshop/_pythons.py
scripts_dir ¶
Name venv's executables directory: Scripts on Windows, bin elsewhere.
The running platform decides: a venv is used on the machine that made it. Nothing is read from the disk, so the venv may not exist yet.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
venv
|
Path
|
The venv's directory. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The directory its interpreter and its console scripts are in. |
Source code in packages/workshop/src/livery/workshop/_pythons.py
venv_python ¶
Name venv's interpreter on this platform.
python.exe in livery.workshop.scripts_dir on Windows, and
python there elsewhere. Nothing is read from the disk, so the
venv may not exist yet.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
venv
|
Path
|
The venv's directory. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The interpreter's path. |
Source code in packages/workshop/src/livery/workshop/_pythons.py
ci_changes ¶
What this CI run changed against the base it measures from; None for everything.
A pull request's run in a workspace that declares [ci]
affected-legs measures from its base branch: the paths changed
since the merge base with origin/<base>, committed or not, with
that merge base, so a widen reference can read a file as it
was. None at a desk, on any other event, without
affected-legs, and when git cannot answer; the run then judges
everything, and the line printed says why.
Source code in packages/workshop/src/livery/workshop/_quality.py
fix_files ¶
Run the gate's fixers over paths, judging nothing.
Every step whose claims reach a file fixes it, and a file no claim reaches is left alone. safe keeps to the fixes a step marks safe, which never remove code an edit in flight still needs; an agent's post-edit hook runs it after each edit.
Source code in packages/workshop/src/livery/workshop/_quality.py
run_phase_over ¶
Run the steps of phase over packages whole; nothing recorded as proved.
The gate's walk (livery.workshop._quality.walk) narrowed to the
steps the extensions register for phase, and the steps they run
after, over the named packages alone, with the gate's inputs. A
package no step of the phase judges is skipped by the walk, and a
phase with no step runs nothing. An extension runs a phase this
way over packages the gate did not run it on. Inside CI the leg's
label names the shard the run is, as check reads it without the
flag.
Source code in packages/workshop/src/livery/workshop/_quality.py
answer ¶
The answer to query about subject: the extensions' answers, combined.
subject is the package for a package-level query, answered by its set in composition order, and the workspace root, or a directory in the workspace, for a workspace-level one, answered by the installed set in composition order. With no extension answering, the query's declared default, or its rule's answer over nothing.
Raises:
| Type | Description |
|---|---|
QueryError
|
when no extension declares the query, when subject is at the other level, when an answer is off the query's values, or when the answers break the query's rule; the message names the query and the extensions, and a package's path for a package-level query. |
Source code in packages/workshop/src/livery/workshop/_queries.py
registry ¶
registry(root: Path, kind: str) -> RegistryTarget
The registry the workspace at root reads and publishes kind artifacts at.
kind is python, conan or container. The first rung
that names one wins: the environment's variables for the kind, the
contract's [registries] table, the forge's own registry of the
kind, then the ecosystem's default.
Raises:
| Type | Description |
|---|---|
Failed
|
when kind is not an artifact registry kind, naming the three. |
Source code in packages/workshop/src/livery/workshop/_registries.py
release_notes ¶
release_notes(root: Path) -> ReleaseNotes | None
The provider the extensions listed at root answer; None when none answers.
The answer is imported when first asked, so a mount imports none of the answering extension's code.
Raises:
| Type | Description |
|---|---|
QueryError
|
when two listed extensions answer and neither requires the other, naming both. |
Source code in packages/workshop/src/livery/workshop/_release_notes.py
checkout_time ¶
The committer time of HEAD's commit in the checkout at root, timezone-aware.
Every shard of a run checks out the same commit, so this bounds the durations rows every shard reads without a call to the forge.
Raises:
| Type | Description |
|---|---|
GitError
|
When HEAD names no commit. |
Source code in packages/workshop/src/livery/workshop/_shard.py
files_digest ¶
A hex digest of the sorted names in files.
Two shards that partitioned one set have one digest, so the gate job can prove they did.
Source code in packages/workshop/src/livery/workshop/_shard.py
leave_shard ¶
leave_shard(root: Path, *, shard: Shard, digest: str, items: Iterable[str], rows: Iterable[str], before: datetime, suites: Iterable[str] = (), attempt: str = '') -> Path
Leave the shard's record in SHARD_FILE at root, for the gate job's proof.
suites names the units whose items are in the set; a unit
left out ran whole on the first shard. attempt is the run's
attempt the shard ran in, the run context's; empty when unknown.
The leg's one write copies the record into its timing row under
shard, where the gate job's fold reads it.
Returns:
| Type | Description |
|---|---|
Path
|
The path of the file left. |
Source code in packages/workshop/src/livery/workshop/_shard.py
partition ¶
partition(items: Iterable[str], durations: Mapping[str, float], count: int, *, head: float = 0.0) -> tuple[tuple[str, ...], ...]
Pack items into count shards by their durations, every item in exactly one.
The items go longest first, ties by name, each into the shard with the least summed seconds so far, ties to the lowest shard. The first shard's sum starts at head seconds, the time of the steps it runs that the other shards leave to it, so its share of the items is lighter by about that much; a head above every other shard's final sum leaves the first shard no item. An item durations does not name weighs the median of the named durations, or one second when none are named. The result is a function of the set, the durations and the head alone: the same whatever order items comes in, and an item given twice is one item. With more shards than items the surplus shards are empty.
Returns:
| Type | Description |
|---|---|
tuple[str, ...]
|
One tuple of items per shard, in the order the items were |
...
|
packed. |
Raises:
| Type | Description |
|---|---|
ValueError
|
When count is below 1, or head is below 0. |
Source code in packages/workshop/src/livery/workshop/_shard.py
platform_leg ¶
The leg label without its shard; a label without one is returned as it is.
check-windows-latest-3.14-2of4 gives check-windows-latest-3.14.
Source code in packages/workshop/src/livery/workshop/_shard.py
read_durations ¶
read_durations(root: Path, leg: str, *, before: datetime) -> tuple[dict[str, float], float, tuple[str, ...], str]
The median seconds per item, and the head, of leg's rows before before.
The rows are the newest NEWEST of the series durations/<platform
leg> whose store stamp is before before; a row stamped at or
after it, or not stamped, is not read, so every shard of a run
reads the same rows whatever lands while the run is in flight. The
median of an item is over the rows that name it with a number
under items. The head is the median of every row read's
head, a row without a number there counting as 0, and is what
livery.workshop.partition starts the first shard's sum at. A
naive before is read as UTC.
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
The seconds per item, the head in seconds, the names of the |
float
|
rows read, newest first, and why the series could not be read. |
tuple[str, ...]
|
A series that cannot be read is |
str
|
never a raise: the caller runs as one shard of one and says |
tuple[dict[str, float], float, tuple[str, ...], str]
|
so. An absent series is |
Source code in packages/workshop/src/livery/workshop/_shard.py
read_shard ¶
read_shard(root: Path) -> tuple[ShardMarker | None, str]
Read the record a shard left in SHARD_FILE at root.
Returns:
| Type | Description |
|---|---|
ShardMarker | None
|
|
str
|
file; |
Source code in packages/workshop/src/livery/workshop/_shard.py
shard_of ¶
The shard the leg label ends in; ONE when it ends in none.
Raises:
| Type | Description |
|---|---|
ValueError
|
When the label ends in a shard spelling outside the
form, such as |
Source code in packages/workshop/src/livery/workshop/_shard.py
package_of ¶
Name the workspace package a test belongs to, from its pytest node id.
The package is the path before the first directory a package keeps
its tests or sources in, tests, src or docs:
packages/forge/tests/test_x.py::test_y belongs to
packages/forge. A package in a group directory is one level
deeper, and its own name may be one of those three: in
packages/extensions/docs/tests/test_x.py::test_y the tests
beneath docs says docs is the package, so the answer is
packages/extensions/docs. Nothing is read from the disk.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nodeid
|
str
|
A test's node id, relative to the workspace root. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The package's path relative to the workspace root, or |
str
|
a node outside |
str
|
|
Source code in packages/workshop/src/livery/workshop/_speed.py
speed_marks ¶
Read each package's current test-time mark on each check leg.
The marks live on the checkout's state store (livery.workshop.state_store). The newest row per package and leg is its mark. A row that does not parse, is of another schema, or lacks a mark's fields is skipped, so one bad row disables nothing. A store that cannot be read falls open: the caller prints the reason and judges nothing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The checkout whose state store holds the marks. |
required |
Returns:
| Type | Description |
|---|---|
dict[tuple[str, str], SpeedMark] | None
|
Each mark by its package's path and its leg, with an empty |
str
|
reason; an empty store gives |
tuple[dict[tuple[str, str], SpeedMark] | None, str]
|
cannot be read, None and the reason. |
Source code in packages/workshop/src/livery/workshop/_speed.py
graph_changed ¶
Tell whether a contract, a native manifest or a root src/ changed.
A step over a language's sources widens on it through its
widen reference, a function of its own extension that calls
this one: the members, their module roots and what they declare
come from these files, so a change to one judges every source
again, as the base's own layering steps do. Prose and the licence
beside a manifest never count.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
changes
|
Changes
|
What the run changed, as a step's |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when a changed path is the root contract, a file directly |
bool
|
in a member's directory, or a file under |
Source code in packages/workshop/src/livery/workshop/_steps.py
scoped_files ¶
scoped_files(ctx: PhaseContext, name: str, package: Package | None = None) -> tuple[Path, ...]
The files of package the step name judges in this run, absolute.
package is the run's own package unless named: a package step names none, and a step that narrows by packages names each one livery.workshop.scoped_packages answers. The files the run names, when it names any; else every file the step's claims reach in the package, an untracked new one among them.
Raises:
| Type | Description |
|---|---|
Failed
|
when neither package nor the run names a package. |
Source code in packages/workshop/src/livery/workshop/_steps.py
scoped_packages ¶
scoped_packages(ctx: PhaseContext, name: str) -> tuple[Package, ...]
The members the package-narrowing step name judges in this run.
The members holding an extension it names, in a scoped run those of the subset, less each one that turned the step off in its contract. Each skip is printed, so a narrowed gate names what it left out. A run over named files keeps the members holding a named file the step claims. The workspace's own tests are not a member.
Source code in packages/workshop/src/livery/workshop/_steps.py
scoped_paths ¶
scoped_paths(ctx: PhaseContext, name: str) -> tuple[str, ...]
The paths the path-narrowing step name judges in this run.
The files the run names, when it names any. Otherwise the whole
tree, ., when the run reaches every member the step judges;
else the src and tests directories of the reached members
holding the runtime's language, the workspace's own tests when the
run and the step judge them, and the files the step's claims give
it in the other reached members.
Source code in packages/workshop/src/livery/workshop/_steps.py
scoped_suite ¶
scoped_suite(ctx: PhaseContext, name: str) -> Package | None
The workspace's own tests, when the step name judges them.
The unit (livery.workshop.workspace_suite) holds the root's
set, so the step judges it while that set holds an extension the
step names. Its tests reach any package, so every run of the step
runs them then. None when the workspace has no tests
directory. None as well when the step does not judge the unit, and
then a line says why.
Source code in packages/workshop/src/livery/workshop/_steps.py
selected_files ¶
selected_files(ctx: PhaseContext) -> frozenset[str] | None
The files the running step judges in this run; None for every file it reads.
A workspace step that declares inputs judges, in a run that
knows what changed, the changed files among its inputs, and what
its widen reference adds; in a run that knows nothing of the
changes, it judges every file it reads, and this is None. The
context names the running step, so a step asks with the context
its run was handed.
Raises:
| Type | Description |
|---|---|
Failed
|
when ctx names no step: one built by hand, outside a step's run. |
Source code in packages/workshop/src/livery/workshop/_steps.py
step_enabled ¶
Whether the step name is on in the workspace at root.
A step its extension declares on is always on. A step it declares
enabled = false is on while the root contract turns it on, with
enabled = true in the step's [phases.<phase>.<step>] table,
and registers only then. A package turns a step off for itself
with the step's enabled option, which
livery.workshop.step_option reads.
Raises:
| Type | Description |
|---|---|
Failed
|
when no installed extension declares the step, naming it. |
Source code in packages/workshop/src/livery/workshop/_steps.py
step_extensions ¶
The extensions the step name names in its extensions list.
The step judges a package whose set holds one of them (livery.workshop.extension_set), and every package when it names none. The step is read as livery.workshop.step_option reads it: registered, else installed.
Raises:
| Type | Description |
|---|---|
Failed
|
when no installed extension declares the step, naming it. |
Source code in packages/workshop/src/livery/workshop/_steps.py
step_option ¶
What package sets for the step name's option, or the option's default.
The deepest of the package's tables that sets it wins. A step the mount registered answers from its registration. A step it did not register, as in a process that mounted nothing, answers from the installed extension that declares it.
Raises:
| Type | Description |
|---|---|
Failed
|
when no installed extension declares the step, naming it; when the step declares no option, naming its options; or when the package sets a value of the wrong type, naming the table. |
Source code in packages/workshop/src/livery/workshop/_steps.py
tested ¶
Keep the units whose suites a registered step of the test phase runs.
A step runs a unit's suite while the unit's set holds an extension the step names, and every unit's when it names none: a member holds its own set, and the workspace's own tests (livery.workshop.WORKSPACE_TESTS) hold the root's set. A step of package scope runs over one member at a time and never over the workspace's own tests.
Returns:
| Type | Description |
|---|---|
tuple[Package, ...]
|
The units of units some test step runs, in units order. |
Source code in packages/workshop/src/livery/workshop/_steps.py
forge_token ¶
The everyday token and the variable that supplied it.
Host-qualified first, then bare FORGE_TOKEN; both empty means
the backend's own documented resolution decides (GitHub asks
gh auth token; a backend may read its own dialect's
variables).
Source code in packages/workshop/src/livery/workshop/_tokens.py
store_home ¶
store_home() -> Home
The tool store's home on this machine, where every checkout's tools are.
The toolroom directory in the runner's data directory, one per
machine and shared by every checkout on it, as a
livery.toolroom.store.Home.
Source code in packages/workshop/src/livery/workshop/_tools.py
tool_receipts ¶
tool_receipts(root: Path) -> dict[str, ToolReceipt]
What the checkout at root installed of each tool, by the tool's name.
The receipts the last sync wrote, each a livery.workshop.ToolReceipt: a receipt names the version the lock pins and where the tool is on this machine. Empty for a checkout no sync has supplied.
Raises:
| Type | Description |
|---|---|
ValueError
|
for a file under the receipts directory that is not a receipt, naming it. |
Source code in packages/workshop/src/livery/workshop/_tools.py
undeployed ¶
Refuse the task: name is a tool of the store and is not on PATH.
Call it where a step spawns a tool of the store and the spawn
raises OSError, or where shutil.which finds nothing for a
tool the step spawns by its path. A toolroom handle spawns its tool
by name from PATH, and the store's tools are on PATH only
after the machine has deployed them and the shell has entered the
environment. A traceback from the spawn names nothing a person can
act on. This refusal names the tool and the next action: run
fm sync, then the env.emit line it prints, then run the task
again.
It never returns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The tool's name, as its handle spawns it. |
required |
Raises:
| Type | Description |
|---|---|
Failed
|
always, naming name and the sync that deploys it. |
Source code in packages/workshop/src/livery/workshop/_tools.py
leg_scope ¶
Read what the gate ran on this leg from the marker it left at root.
The gate leaves the marker on a CI run's check leg, so the leg's entries after the gate read it there. A gate outside CI leaves none.
Returns:
| Type | Description |
|---|---|
LegScope
|
The leg's scope; |
LegScope
|
marker is not a JSON object. |
Source code in packages/workshop/src/livery/workshop/_verified.py
verified_branch ¶
verified_branch(root: Path) -> VerifiedBranch
Read which branch's run proved the tree checked out at root.
Main's run after a squash merge reads it to find the branch whose records the tree carries. A row the store cannot read, and a tree git cannot name, decide nothing: the branch is empty and the reason says why, so the caller reads main's records alone.
Source code in packages/workshop/src/livery/workshop/_verified.py
__getattr__ ¶
Serve a public name from its module, each time it is read.
The value is never kept here. A kept value would be whatever the module held at the first read, so a test that patched the module's name before that read would leave its fake in this module for the rest of the process.