livery.workshop._steps¶
livery.workshop._steps ¶
The step registry: what the quality gate runs, one record per step.
A step is one tool's judgment over the workspace or over one package: a formatter's pass, the render drift comparison, ctest over a native member. Each is a livery.workshop._steps.StepRecord registered through livery.workshop._steps.register_step, and the gate is the walk over the registry: every applicable step green, the exit code the verdict. The workshop registers the builtin records at import; an extension's records register at mount, after them and in composition order, each extension after the ones it requires, ties alphabetical, and re-registering a name replaces the record.
A step names the extensions whose packages it judges, and a package holding none of them skips it by name: a C++ member is formatted over its recipe by a python formatter and over its sources by clang-format because each step names an extension it holds. The phases the registry knows are the ones its steps name, so they are what the listed extensions register.
A step is named by its phase and its name in the phase,
test.pytest. The phase is a declared one
(livery.workshop._phases.declared_phases), and a step of a phase
nobody declares refuses naming the declared ones. A phase that
declares a verb is a verb and every step a sub-task of it, made by
livery.workshop._steps.generate_verbs from the registry: fm
test runs the test phase's steps and fm test.pytest the one;
the gate runs the steps of the phases that declare themselves gated.
The gate runs the registered steps through the one walk
(livery.workshop._phases.walk_steps), each a footman step: the
rewriters one at a time before any judge reads the tree
(livery.workshop._steps.rewriters), then every judge in one
block (livery.workshop._steps.judges), each with its own record.
A step that must follow another on the same package, a build after
its configure, names it in after: the walk starts it once the
earlier one ran, and the gate brings the earlier one in
(livery.workshop._steps.with_earlier).
Classes:
| Name | Description |
|---|---|
Option |
One option a package may set on a step, in the step's own table. |
Claim |
One category a step judges, and the rules it withholds there. |
StepRecord |
One step, completely. |
Functions:
| Name | Description |
|---|---|
register_step |
Register record; a name already registered is replaced. |
option_addresses |
The tables that reach record's options, shallowest first. |
option_value |
What package sets for record's option name, or the option's default. |
option_problems |
Every option table or key no registered step takes, one line each. |
enabled |
packages minus those that turned the step name off, each skip printed. |
tools_for |
The tools the steps judging packages that hold extensions run. |
unregister_step |
Drop the step name; unknown names refuse naming the registry. |
narrowings |
The gate's lines naming each step an extension registered. |
step_names |
Every registered step, in registration order. |
snapshot |
The registry's state, for livery.workshop._steps.restore to put back. |
restore |
Put the registry back to state. |
judged_files |
The files of package the step's claims reach, relative to it, sorted. |
claimants |
The steps whose claims reach path in package, by name, sorted. |
per_file_ignores |
The per-file ignores the claims render, pattern to rule codes, sorted. |
steps_by_name |
Every registered record by name, in registration order. |
answering |
The step answering to address, its name; None when none is registered. |
step_for |
The step named name, |
phases |
The phases the registered steps belong to, sorted. |
judges_extensions |
Whether record judges a package holding extensions. |
judges_unit |
Whether record judges unit, by the extensions the unit holds. |
judged_by |
The packages record judges, by the extensions they hold; each other skips. |
judges_package |
Whether the package step record runs over package in this run. |
members |
The packages under judgment that are members: every one but the tests unit. |
verb_tree |
Each phase's steps by name, sorted: the verbs the registry generates. |
split_arguments |
A verb's positional words as its paths, then the words after |
generate_verbs |
Make a verb per phase and a sub-task per step, from the registry. |
arguments_refusal |
Why verb, which runs several steps, takes no arguments after |
run_step |
Run the step name over ctx through the walk: its judge, or its fix mode. |
with_earlier |
The records of names, and of every step one of them runs after. |
installed_step |
Whether an installed extension or the base declares the step name. |
workspace_selected |
The workspace steps with declared inputs that this run's changes select. |
selected_files |
The files the running step judges in this run; None for every file it reads. |
package_files |
The files directly in each package's directory, as patterns. |
graph_files |
What the graph is made of: the contracts, the native manifests, a root src/. |
graph_changed |
Tell whether a contract, a native manifest or a root |
selected |
What record judges in this run, by its declared inputs. |
catalogue |
Every file git holds under the root, by unit, each with its category. |
reads_files |
Whether record's claims reach a file of units, or of its scope in this run. |
claimed_files |
The files of the run's catalogue record's claims reach, as absolute paths. |
with_files |
names less the steps with no file to read in this run, each skip said. |
on_this_shard |
names less the steps this shard leaves to the first shard, each said. |
rewriters |
The steps whose fix mode runs, serially and in order, under --fix. |
judges |
The steps the gate judges together, in registration order. |
scoped_paths |
The paths the path-narrowing step name judges in this run. |
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_suite |
The workspace's own tests, when the step name judges them. |
declared_step |
The step name: its registered record, else the installed declaration's. |
step_option |
What package sets for the step name's option, or the option's default. |
step_extensions |
The extensions the step name names in its |
step_enabled |
Whether the step name is on in the workspace at root. |
tested |
Keep the units whose suites a registered step of the test phase runs. |
Attributes:
| Name | Type | Description |
|---|---|---|
WORKSPACE |
|
|
PACKAGE |
|
|
PATHS |
|
|
PACKAGES |
|
|
NONE |
|
|
BASE_EXTENSION |
|
|
ENABLED |
|
|
FLAGS |
|
|
NOT_INPUTS |
|
|
GENERATED |
|
|
ROOT_UNIT |
|
|
WHOLE |
|
ENABLED
module-attribute
¶
ENABLED = Option('enabled', 'bool', True, 'whether the step judges this package')
GENERATED
module-attribute
¶
GENERATED = ('.github/workflows/*.yml', '.gitea/workflows/*.yml', '.gitlab-ci.yml', 'setup.sh', '.github/CODEOWNERS', '.gitlab/CODEOWNERS', '.gitea/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS')
Option
dataclass
¶
One option a package may set on a step, in the step's own table.
The table is [phases.<phase>.<step>], the step's address; a
[phases.<phase>] table sets an option on every step of the
phase.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The option's key, kebab-case. |
kind |
str
|
|
default |
object
|
What the step reads when the package says nothing. |
doc |
str
|
One line saying what the option changes. |
Claim
dataclass
¶
One category a step judges, and the rules it withholds there.
Attributes:
| Name | Type | Description |
|---|---|---|
category |
str
|
The category, |
ignore |
tuple[str, ...]
|
Rule codes the step does not apply to that category; a tool with per-file ignores renders them as those. |
suffixes |
tuple[str, ...]
|
The file suffixes the step reads in the category,
|
StepRecord
dataclass
¶
StepRecord(step: str, phase: str, run: Callable[[PhaseContext], None], scope: str = WORKSPACE, narrowing: str = NONE, fix: Callable[[PhaseContext], None] | None = None, extensions: tuple[str, ...] = (), tests_only: bool = False, inputs: Inputs | None = None, after: tuple[str, ...] = (), extension: str = BASE_EXTENSION, tools: tuple[str, ...] = (), options: tuple[Option, ...] = (), fragments: tuple[Fragment, ...] = (), claims: tuple[Claim, ...] = (), flags: tuple[str, ...] = (), arguments: bool = False, words: Words | None = None, provides: tuple[tuple[str, str], ...] = (), reads: tuple[str, ...] = (), isolated: bool | None = None, enabled: bool = True, replaces: tuple[tuple[str, str], ...] = (), deletes: tuple[tuple[str, str], ...] = (), outputs: tuple[str, ...] = ())
One step, completely.
A step's name is its phase and its name in the phase,
test.pytest: the verb fm test.pytest, the
[phases.test.pytest] table of its options, the gate's lines,
and every lookup use it. An extension declares the step in its
[phases.<phase>.<step>] table.
Attributes:
| Name | Type | Description |
|---|---|---|
step |
str
|
The step's name in its phase, as its sub-task names it
under the phase's verb: |
phase |
str
|
The phase the step belongs to: |
run |
Callable[[PhaseContext], None]
|
The judging callable, called with the run's livery.workshop.PhaseContext: the engine running the step's words or a reference to its code; a refusal is its verdict. |
scope |
str
|
|
narrowing |
str
|
How a workspace step narrows under a scoped gate:
|
fix |
Callable[[PhaseContext], None] | None
|
The rewriting callable when the tool can rewrite, run
serially before any judge under |
extensions |
tuple[str, ...]
|
The extensions whose packages the step judges: a package whose set holds one of them (livery.workshop.extension_set). A package step runs per such member; a workspace step names them so its tools and claims reach those packages, or leaves them empty. |
tests_only |
bool
|
Whether a package step still runs when the package's change is confined to its tests. A build and the tests do; a formatter does not. |
inputs |
Inputs | None
|
The files a workspace step reads, so a run judges it only when one of them, or what widens it, changed, and then only the changed ones when it judges per file (livery.workshop._influence.Inputs). None for a step that narrows by its packages alone. |
after |
tuple[str, ...]
|
The steps this one runs after, by name: a build after its configure, a ctest after its build. The walk starts this one once each of them ran for the same package, and the gate's walk brings them in (livery.workshop._steps.with_earlier). |
extension |
str
|
The extension that registered the step, named when a narrowing is printed. |
tools |
tuple[str, ...]
|
The tools the step runs, as the tool profile names
them, |
options |
tuple[Option, ...]
|
The options a package may set under
|
fragments |
tuple[Fragment, ...]
|
The configuration the render manages for the step, one per rendered file it has something to say in; composed in step-name order, judged by the drift gate, gone from the next render with the record. |
claims |
tuple[Claim, ...]
|
The categories the step judges, each with the rules it withholds there and the suffixes it reads; a step judges every file its claims reach and no other, and a tool with per-file ignores renders its ignores from them. |
flags |
tuple[str, ...]
|
The command-line flags the step reads, from |
arguments |
bool
|
Whether the step hands the tool it wraps the words
after |
words |
Words | None
|
The step's words when it is declared in words, which
|
provides |
tuple[tuple[str, str], ...]
|
The context keys the step writes inside its phase, each to its type name; a step of one phase reads what another provides. |
reads |
tuple[str, ...]
|
The context keys the step reads inside its phase. |
isolated |
bool | None
|
Whether the step serves the phase's isolated side (True), from a copy of the sources in a fresh environment, or its tree side (False); None serves both. The walk runs the step on the side the engine gives the phase (livery.workshop._phases.serves), and the gate gives the tree side. |
enabled |
bool
|
Whether the step registers while its extension is
listed. An extension declares False for a step a workspace
turns on at the step's address in the root contract,
|
replaces |
tuple[tuple[str, str], ...]
|
The steps of the base or of an extension this one
requires that it replaces, each |
deletes |
tuple[tuple[str, str], ...]
|
The steps of the base or of an extension this one
requires that it deletes, each |
outputs |
tuple[str, ...]
|
The paths the step writes, each relative to the root
or |
register_step ¶
register_step(record: StepRecord) -> None
Register record; a name already registered is replaced.
The mount registers each step a listed extension declares.
Replacing is how an extension swaps the step at an address, and
how a test injects a fake; a package step names at least one
extension, since a step that judges packages and applies to none
never runs. The step's address, <phase>.<step>, is a task's
address, so a dot inside the phase or the step's name refuses, and
a step named default refuses (that address is the phase verb's
own).
Source code in packages/workshop/src/livery/workshop/_steps.py
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 | |
option_addresses ¶
option_addresses(record: StepRecord) -> tuple[str, ...]
The tables that reach record's options, shallowest first.
phases.<phase>, the phase's table, which reaches every step of
the phase, then phases.<phase>.<step>, the step's own: the
later table wins key by key, since it names fewer steps.
Source code in packages/workshop/src/livery/workshop/_steps.py
option_value ¶
option_value(record: StepRecord, package: Package, name: str) -> object
What package sets for record's option name, or the option's default.
The deepest table that sets it wins (livery.workshop._steps.option_addresses). Refuses an option the record does not declare and a value of the wrong type, naming the record's options.
Source code in packages/workshop/src/livery/workshop/_steps.py
option_problems ¶
Every option table or key no registered step takes, one line each.
Read by layering.graph, so a package that addresses a phase or
a step that does not exist, or sets an option none of the steps it
reaches declares, is refused with the vocabulary named.
Source code in packages/workshop/src/livery/workshop/_steps.py
enabled ¶
packages minus those that turned the step name off, each skip printed.
Source code in packages/workshop/src/livery/workshop/_steps.py
tools_for ¶
The tools the steps judging packages that hold extensions run.
Each as a (tool, step) pair. A step judges such a package
when it names one of extensions; a workspace step names the
extensions its bodies judge the same way.
Source code in packages/workshop/src/livery/workshop/_steps.py
unregister_step ¶
unregister_step(name: str) -> None
Drop the step name; unknown names refuse naming the registry.
Source code in packages/workshop/src/livery/workshop/_steps.py
narrowings ¶
The gate's lines naming each step an extension registered.
A step the base did not register names its extension. Empty for the base alone.
Source code in packages/workshop/src/livery/workshop/_steps.py
step_names ¶
snapshot ¶
snapshot(*, initial: bool = False) -> dict[str, StepRecord]
The registry's state, for livery.workshop._steps.restore to put back.
With initial, the state importing this module leaves instead: the builtin steps alone, as a process starts with them.
Source code in packages/workshop/src/livery/workshop/_steps.py
restore ¶
restore(state: dict[str, StepRecord]) -> None
judged_files ¶
judged_files(record: StepRecord, package: Package) -> tuple[str, ...]
The files of package the step's claims reach, relative to it, sorted.
Every file git holds under the package directory is categorised and kept when a claim names its category and admits its suffix; a record without claims judges nothing by this measure, which is what a step that runs a tool over directories looks like from here.
Source code in packages/workshop/src/livery/workshop/_steps.py
claimants ¶
The steps whose claims reach path in package, by name, sorted.
Source code in packages/workshop/src/livery/workshop/_steps.py
per_file_ignores ¶
The per-file ignores the claims render, pattern to rule codes, sorted.
held is each set of extensions a present package holds. For
each set, every claim of a step that judges a package
holding it and withholds rules on a category maps to that
category's patterns in the tables that answer for such a package,
each under packages/**/, which reaches a member in a group
directory too. For the workspace's own unit, every step's claims map
to its table's patterns as they are. Two steps claiming one category
under different rules land in one entry with both sets.
Source code in packages/workshop/src/livery/workshop/_steps.py
steps_by_name ¶
steps_by_name() -> dict[str, StepRecord]
answering ¶
The step answering to address, its name; None when none is registered.
step_for ¶
step_for(name: str) -> StepRecord
The step named name, test.pytest.
Refusal names the registry.
Source code in packages/workshop/src/livery/workshop/_steps.py
phases ¶
judges_extensions ¶
judges_extensions(record: StepRecord, extensions: Iterable[str]) -> bool
Whether record judges a package holding extensions.
A step that names no extensions judges every package; one that names some judges a package holding one of them.
Source code in packages/workshop/src/livery/workshop/_steps.py
judges_unit ¶
judges_unit(record: StepRecord, unit: Package) -> bool
Whether record judges unit, by the extensions the unit holds.
A member holds its set, and the workspace's own tests hold the
root's set (extension_set). A step that names no extension judges
every unit; one that names some judges a unit holding one of them.
Source code in packages/workshop/src/livery/workshop/_steps.py
judged_by ¶
judged_by(record: StepRecord, packages: tuple[Package, ...], *, quiet: bool = False) -> tuple[Package, ...]
The packages record judges, by the extensions they hold; each other skips.
A package holding none of the step's extensions prints a skip naming the step, the package and the extensions, so a narrowed gate is visible in the output and never passes silently. quiet counts without printing.
Source code in packages/workshop/src/livery/workshop/_steps.py
judges_package ¶
judges_package(record: StepRecord, ctx: PhaseContext, package: Package) -> bool
Whether the package step record runs over package in this run.
The package holds an extension the step names; a change confined to the package's tests leaves the step out unless it is tests-only (livery.workshop._steps.StepRecord).
Source code in packages/workshop/src/livery/workshop/_steps.py
members ¶
members(ctx: PhaseContext) -> tuple[Package, ...]
The packages under judgment that are members: every one but the tests unit.
Source code in packages/workshop/src/livery/workshop/_steps.py
verb_tree ¶
verb_tree() -> dict[str, dict[str, StepRecord]]
Each phase's steps by name, sorted: the verbs the registry generates.
A phase that declares no verb is left out.
Source code in packages/workshop/src/livery/workshop/_steps.py
split_arguments ¶
A verb's positional words as its paths, then the words after --.
footman hands a task's variadic parameter the words after --
too, last, and names them through passthrough().
Source code in packages/workshop/src/livery/workshop/_steps.py
generate_verbs ¶
generate_verbs(into: Group | None = None) -> None
Make a verb per phase and a sub-task per step, from the registry.
fm test runs every step of the test phase and fm test.pytest
the one, each offering exactly the flags its steps read. A phase
or a sub-task whose address a verb already holds is served by that
verb, fm provenance, and nothing is
made there. Run again after extensions registered or withdrew steps,
it makes what is new, remakes a verb whose flags changed, and
removes a verb whose step is gone.
Source code in packages/workshop/src/livery/workshop/_steps.py
arguments_refusal ¶
arguments_refusal(verb: str, records: Iterable[StepRecord]) -> str
Why verb, which runs several steps, takes no arguments after --.
The words after -- are one tool's, so they go to a step's own
verb; the refusal names those of records that take them.
Source code in packages/workshop/src/livery/workshop/_steps.py
run_step ¶
run_step(name: str, ctx: PhaseContext, *, fix: bool = False) -> None
Run the step name over ctx through the walk: its judge, or its fix mode.
One step alone (livery.workshop._phases.walk_steps): a workspace
step runs once, a package step once per package it judges, and
a step without a fix mode runs nothing in fix mode. The steps
named in after are not run first: a caller running several
steps by hand orders them itself, and the gate's walk brings them
in (livery.workshop._steps.with_earlier).
Source code in packages/workshop/src/livery/workshop/_steps.py
with_earlier ¶
with_earlier(names: tuple[str, ...]) -> tuple[StepRecord, ...]
The records of names, and of every step one of them runs after.
Followed through after transitively, in registration order,
so a build's configure joins the walk that judges the build. An
after naming a step an installed extension declares and the
mount did not register orders nothing: clang-tidy's lint runs after
cmake's configure in a workspace whose packages hold cmake, and
alone in one whose packages do not.
Raises:
| Type | Description |
|---|---|
Failed
|
when an |
Source code in packages/workshop/src/livery/workshop/_steps.py
installed_step ¶
Whether an installed extension or the base declares the step name.
name is <phase>.<step>. Read from the declarations, so a step
the mount did not register, one of an extension the workspace does
not mount, is declared all the same.
Source code in packages/workshop/src/livery/workshop/_steps.py
workspace_selected ¶
workspace_selected(ctx: PhaseContext) -> tuple[str, ...]
The workspace steps with declared inputs that this run's changes select.
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
package_files ¶
The files directly in each package's directory, as patterns.
The contract and the native manifests are among them, whatever the package's kind calls its manifest, so the base names none of them.
Source code in packages/workshop/src/livery/workshop/_steps.py
graph_files ¶
What the graph is made of: the contracts, the native manifests, a root src/.
The layering steps over the sources widen on them: a change there moves what the rules read, so every source is judged again.
Source code in packages/workshop/src/livery/workshop/_steps.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
selected ¶
selected(record: StepRecord, ctx: PhaseContext) -> Selection
What record judges in this run, by its declared inputs.
Everything for a step that declares none. The run's changes
select, or the named files of fm check <paths> when there are no
changes; a run with neither judges everything.
Source code in packages/workshop/src/livery/workshop/_steps.py
catalogue ¶
Every file git holds under the root, by unit, each with its category.
Listed once per walk: tracked files and untracked ones git does not ignore, as the tools see them, or the run's named files alone. A package's files are relative to it and categorised by the tables of the extensions it holds; a file under no package belongs to [livery.workshop._steps.ROOT_UNIT], relative to the root and categorised by the workspace's table. None when the root is not a git checkout, and then every step that applies runs.
Source code in packages/workshop/src/livery/workshop/_steps.py
reads_files ¶
reads_files(record: StepRecord, ctx: PhaseContext, units: tuple[str, ...] | None = None) -> bool
Whether record's claims reach a file of units, or of its scope in this run.
A step without claims reads what its own body decides, and a run without a catalogue has no listing to judge by: both answer yes, except over named files, which a step without claims cannot say it reads.
Source code in packages/workshop/src/livery/workshop/_steps.py
claimed_files ¶
claimed_files(record: StepRecord, ctx: PhaseContext, unit: str | None = None) -> tuple[str, ...]
The files of the run's catalogue record's claims reach, as absolute paths.
For a run over named files: the ones a step takes. unit keeps one package's alone, for a package step.
Source code in packages/workshop/src/livery/workshop/_steps.py
with_files ¶
with_files(names: tuple[str, ...], ctx: PhaseContext) -> tuple[str, ...]
names less the steps with no file to read in this run, each skip said.
No process starts for a step whose claims reach nothing in scope.
Source code in packages/workshop/src/livery/workshop/_steps.py
on_this_shard ¶
on_this_shard(names: tuple[str, ...], ctx: PhaseContext) -> tuple[str, ...]
names less the steps this shard leaves to the first shard, each said.
A step that declares shard among its flags runs on every shard
of a sharded check leg and runs its share, the shard in its
context's shard. A step that does not runs whole, so it runs
on the first shard alone: on any other shard it is left out, and a
line says so. On the first shard, and on a run that is one shard
of one, every step stays and nothing is said.
Source code in packages/workshop/src/livery/workshop/_steps.py
rewriters ¶
rewriters(ctx: PhaseContext) -> tuple[str, ...]
The steps whose fix mode runs, serially and in order, under --fix.
Those of the gated phases; empty unless the gate runs in its fix
mode. They run in registration order, the base's first and then
each extension's in composition order, with each step after the
ones it names in after and the providers of the keys it reads.
Raises:
| Type | Description |
|---|---|
OrderCycle
|
when the rewriters' order has no start, naming the members of one cycle. |
Source code in packages/workshop/src/livery/workshop/_steps.py
judges ¶
judges(ctx: PhaseContext) -> tuple[str, ...]
The steps the gate judges together, in registration order.
Those of the gated phases. A step that rewrote in this run is not judged again: re-judging the style it just wrote would only spend time agreeing.
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_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_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
declared_step ¶
declared_step(name: str) -> StepRecord
The step name: its registered record, else the installed declaration's.
A process that mounted nothing holds the base's own steps alone,
so an extension's step is read from the installed extension that
declares it, the first by name (installed_record in the
extensions module).
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
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_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
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. |