livery.workshop._phases¶
livery.workshop._phases ¶
The declared phases, the context a step receives, and the walk that runs steps.
A phase is declared, by the base in the [phases] section of its
contract.toml and by an extension under [phases.<phase>] in its
extension.toml, in one grammar (livery.workshop._phases.PhaseSpec):
the keys the engine running it gives its steps, typed; its level,
package for a phase whose steps run once per package and
workspace for one whose steps run once; whether fm check runs
it; the phases it follows in the train's order; and whether a verb is
generated for it. livery.workshop._phases.declared_phases is every
declared phase by name, the base's and then each installed
extension's; a phase nobody declares refuses naming the declared ones,
and two extensions declaring one phase refuse naming both.
Every phase's steps run through the one walk,
livery.workshop._phases.walk_steps: each step a footman step inside
one parallel() block, a workspace step once and a package step
once per package in scope, independent steps concurrently, a step
after the steps it names in after and after the providers of the
keys it reads. The gate runs its phases through it with its own
engine around it (livery.workshop._quality.walk); the release
train and fm run run a package's lifecycle phases through it
(livery.workshop._lifecycle), the steps those of the package's set
(livery.workshop._phases.phase_steps); fm sync runs the sync
phase's registered steps through it over the workspace, and
livery.workshop.run_phase those of any phase the gate never runs,
first removing what a step that stopped running declared it writes.
Each step receives the one context, livery.workshop.PhaseContext.
A step table's deletes names steps of other extensions, each
<owner>:<phase>.<step> with its reason, that never run for a
package whose set holds the deleting extension: the set's steps leave
them out, and the walk skips such a package for a registered step it
deletes, saying why. A package whose set does not hold the deleting
extension runs them.
The engine running a walk gives each phase its keys, by phase. The
train builds on the isolated side in the release configuration and
tests on the isolated side once per resolution it proves; the gate
builds on the tree side in the instrumented configuration, and
fm run on the tree side in debug. A phase whose declaration
holds isolated has two sides: the tree, and the isolated one, from
a copy of the sources in a fresh environment. A step that declares
isolated serves the side it names alone, and one that declares
nothing serves both (livery.workshop._phases.serves).
Two steps providing one key, a key nobody provides, a step declaring a
side of a phase that has one side, and an order with no start refuse
before any step runs (livery.workshop._phases.phase_problems);
layering.graph names them for each package.
Classes:
| Name | Description |
|---|---|
PhaseSpec |
A phase as its declarer declares it: one |
PhaseError |
A phase whose steps cannot run as declared, or a step's misuse of the context. |
PhaseContext |
What a run hands a step: the workspace, the run's scope, and the phase's keys. |
Functions:
| Name | Description |
|---|---|
base_phases |
The base's phases, read from the |
declared_phases |
Every declared phase by name: the base's, then each installed extension's. |
phase_spec |
The declared phase name; refuses naming the declared ones. |
lifecycle_phases |
The package-level phases, in declaration order: a package's lifecycle. |
phase_steps |
The steps the extensions members add to phase, in their order. |
step_address |
record's address among every extension's steps: |
deletions |
The steps the extensions members delete, by address, to the deleter and why. |
set_deletions |
The steps package's set deletes, by address, to the deleter and why. |
serves |
Whether record runs on the side of its phase the engine's given keys name. |
phase_order |
steps in the order the walk starts them. |
phase_problems |
Why steps cannot run as phase; empty when they can. |
walk_steps |
Run steps as footman steps inside one |
run_registered |
Run the steps registered for the phase ctx names, through the walk. |
output_refusal |
Why output cannot name what a step writes, or |
run_phase |
Run a phase the gate never runs over the workspace at root; the shared context. |
Attributes:
| Name | Type | Description |
|---|---|---|
PACKAGE_LEVEL |
|
|
WORKSPACE_LEVEL |
|
|
LEVELS |
|
|
TYPES |
|
|
BASE |
|
|
ISOLATED |
|
|
OUTPUTS_RECORD |
|
|
IN_EACH_PACKAGE |
|
PhaseSpec
dataclass
¶
PhaseSpec(name: str, keys: Mapping[str, str] = dict[str, str](), level: str = PACKAGE_LEVEL, gated: bool = False, after: tuple[str, ...] = (), verb: bool = False, extension: str = BASE)
A phase as its declarer declares it: one [phases.<phase>] table.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The phase's name, |
keys |
Mapping[str, str]
|
The keys the engine running the phase gives its steps, each to its type; a step reads one like any key, and no step provides one. |
level |
str
|
|
gated |
bool
|
Whether |
after |
tuple[str, ...]
|
The phases this one follows in the train's order. |
verb |
bool
|
Whether a verb is generated for the phase, |
extension |
str
|
The extension that declares the phase; the base for its own. |
keys
class-attribute
instance-attribute
¶
PhaseError ¶
Bases: RuntimeError
A phase whose steps cannot run as declared, or a step's misuse of the context.
Raised before any step runs for the phase's own problems, and from livery.workshop.PhaseContext.provide or livery.workshop.PhaseContext.read for a key the running step's table does not declare, or a value of another type.
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
base_phases
cached
¶
The base's phases, read from the [phases] section of its contract file.
In the file's order, each spec naming the base as its declarer.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a section is off the shape a phase's declaration has. |
Source code in packages/workshop/src/livery/workshop/_phases.py
declared_phases
cached
¶
Every declared phase by name: the base's, then each installed extension's.
An installed extension's declaration is read whether the workspace
lists it or not, so a step into its phase reads the same anywhere;
the mount refuses the step while the declarer is not listed. Each
phase's after names declared phases, and the order they give
has a start.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when two extensions declare one phase, a phase follows one nobody declares, or the order has no start. |
Source code in packages/workshop/src/livery/workshop/_phases.py
phase_spec ¶
The declared phase name; refuses naming the declared ones.
Raises:
| Type | Description |
|---|---|
PhaseError
|
when no extension declares name. |
Source code in packages/workshop/src/livery/workshop/_phases.py
lifecycle_phases ¶
The package-level phases, in declaration order: a package's lifecycle.
phase_steps ¶
The steps the extensions members add to phase, in their order.
Each member's steps in declaration order, the members in the order
given, which for a package's set is its composition order. A step
one of members deletes is left out, so it never runs for the set
(deletions).
Source code in packages/workshop/src/livery/workshop/_phases.py
step_address ¶
step_address(record: StepRecord) -> str
record's address among every extension's steps: <owner>:<phase>.<step>.
deletions ¶
The steps the extensions members delete, by address, to the deleter and why.
An address is <owner>:<phase>.<step>, as a step table's
deletes names it; the first of members to delete a step is
its deleter.
Source code in packages/workshop/src/livery/workshop/_phases.py
set_deletions ¶
The steps package's set deletes, by address, to the deleter and why.
Source code in packages/workshop/src/livery/workshop/_phases.py
serves ¶
serves(record: StepRecord, given: Mapping[str, object]) -> bool
Whether record runs on the side of its phase the engine's given keys name.
given are the keys the engine gives the step's phase. A step
declaring isolated = true runs when the engine gives
isolated true; one declaring false runs when the engine gives
false or nothing; one declaring neither runs on both sides.
Source code in packages/workshop/src/livery/workshop/_phases.py
phase_order ¶
phase_order(steps: Iterable[StepRecord], *, after: bool = True) -> tuple[StepRecord, ...]
steps in the order the walk starts them.
Each step after the providers of the keys it reads, in its own
phase, and, with after, after the steps it names in after;
otherwise in the given order. An after naming a step outside
steps orders nothing.
Raises:
| Type | Description |
|---|---|
OrderCycle
|
when the order has no start, naming the members of one cycle. |
Source code in packages/workshop/src/livery/workshop/_phases.py
phase_problems ¶
phase_problems(phase: str, steps: Iterable[StepRecord]) -> list[str]
Why steps cannot run as phase; empty when they can.
Two extensions declaring one step, two steps providing one key, a
step providing a key the phase's engine gives, a step declaring a
side of a phase whose declaration gives no isolated, a key a
step reads and no step provides, and an order with no start.
Raises:
| Type | Description |
|---|---|
PhaseError
|
when no extension declares phase. |
Source code in packages/workshop/src/livery/workshop/_phases.py
walk_steps ¶
walk_steps(ctx: PhaseContext, steps: Iterable[StepRecord], *, inputs: Mapping[str, Mapping[str, object]] | None = None, fixing: bool = False) -> PhaseContext
Run steps as footman steps inside one parallel() block.
A step runs on the side of its phase the engine gives
(livery.workshop._phases.serves), and a step serving the other
side is not run. A workspace step runs once. A package step runs
once per package in scope (the context's judged) it judges:
one whose set holds an extension the step names and none that
deletes the step, that has not turned the step off, that has a
file the step's claims reach, and whose change is not confined to
its tests unless the step is tests-only; each other package is
said and not run. Independent
steps run concurrently, and a step starts once the steps it names
in after and the providers of the keys it reads have run, for
the same package. A step whose earlier step failed is not run and
says so; the earlier failure is the verdict, and the steps that
depend on nothing failed still run, as footman runs a block.
inputs are the keys the engine gives each phase, by phase, each
phase's judged against its declaration before any step runs.
fixing runs each step's fix body instead of its main, a step
without one running nothing, in the given order: a fix rewrites
what its own tool reads, and the gate runs its fixers one at a
time, so after orders nothing there.
Returns:
| Type | Description |
|---|---|
PhaseContext
|
The context the steps shared, which the engine reads a provided |
PhaseContext
|
key or the exit code back from. |
Raises:
| Type | Description |
|---|---|
PhaseError
|
before any step runs, when the context or inputs names a phase nobody declares, when inputs gives a phase a key it does not take or a value of another type, or when the steps cannot run as declared (livery.workshop._phases.phase_problems). |
Exception
|
the first failing step's, raised again once every step ran. |
Source code in packages/workshop/src/livery/workshop/_phases.py
739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 | |
run_registered ¶
run_registered(ctx: PhaseContext) -> PhaseContext
Run the steps registered for the phase ctx names, through the walk.
The steps the mount registered for ctx.phase, in registration
order: each listed extension's own, and those of the
[for.<target>] tables that apply. They run as walk_steps runs
any steps, so a phase the gate never runs, one declared with
gated = false, runs this way over the workspace its context
names. A workspace step that names extensions runs once while a
package the context judges 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.
Returns:
| Type | Description |
|---|---|
PhaseContext
|
The context the steps shared. |
Raises:
| Type | Description |
|---|---|
PhaseError
|
when ctx names no phase, or one nobody declares. |
Exception
|
the first failing step's, raised again once every step ran. |
Source code in packages/workshop/src/livery/workshop/_phases.py
output_refusal ¶
Why output cannot name what a step writes, or "" when it can.
An output is a path relative to the workspace root, or
package/<path> for that path in each package; a directory ends
in /. It lies below the root, or below the package, and it is
never docs/ itself, the root's or a package's, which holds the
authored pages. The text completes a sentence about the output.
Source code in packages/workshop/src/livery/workshop/_phases.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 | |