livery.workshop._e2e¶
livery.workshop._e2e ¶
fm ci.e2e: the CI and release story against a local forge.
The workshop's own development substrate: provision a scratch repository on the seeded local forge, and drive the emitted workflows through a real runner against the forge's own package registry, so the whole second world runs consequence-free before anything reaches a public forge. The loop's workspace splits its one runner's check leg into two shards, so every pass proves the slice, the gate job's fold and the durations row beside the gate itself.
The verb registers only where the workshop develops itself, the way
fm forge.fixtures.record does: a consumer checkout does not
carry it at all.
Classes:
| Name | Description |
|---|---|
RunCount |
How many runner runs the pass has followed so far; the timing table reads it. |
Current |
The environment a pass runs on, as the loop reads its forge from it. |
Lane |
One local forge the loop runs against, as the host and the runner reach it. |
LoopMember |
One member of the loop: its directory and the template it is born from. |
Pass |
What one pass carries between its scenarios. |
Timing |
What one scenario cost. |
Scenario |
One thing the loop proves, by name, with what must have run before it. |
Functions:
| Name | Description |
|---|---|
scrub_ci_markers |
Remove CI's markers from environ; the names removed, in declared order. |
child_environment |
The environment a child the pass starts by hand begins with, extra over it. |
edit_environments |
Write values and drop remove where this task and every child read them. |
dev_members |
The members whose dev wheels the loop eats: the workshop and what a birth lists. |
enter_environment |
Run the pass on environment name, brought up first; the environment. |
provision |
Ensure the loop's repository, idempotently, with its secrets. |
write_dev_index |
Lay wheels out at folder as a simple index uv reads; folder. |
checkout_index |
Build what a newborn installs from root as a local index at folder; its URL. |
build_content_named |
Build package's wheel into out, at a version naming its content; the wheel. |
require_dev_branch |
Refuse unless root stands on a branch whose release verb is the dev act. |
scratch_branch |
Run a pass from a scratch branch where a build would be the release train. |
start_over |
Delete the loop's repository, its registry releases, and root; the lines. |
judge_runs |
One line per run; red fails with every red run named. |
members_for |
The loop's members named names, in the loop's order; all when empty. |
landed_members |
The loop's members a pass lands for steps naming named, by name, in order. |
steps_declared_off |
The steps extension name declares |
extension_under_test |
The list a pass births to test extension name, and the members it lands. |
red_jobs_text |
The failed jobs of run with the last lines of each log, as text to print. |
loop_stack |
The extensions a plain pass's birth lists, as their canonical list. |
scenarios_for |
The scenarios spec names, their needs added, in the registry's order. |
daemon_needed |
Whether any of scenarios needs the runner's docker socket. |
run_scenario |
Run scenario for pass_, timed; a failure is timed and marked, then raised. |
timing_table |
The lines a pass ends with: each scenario's time and runs, then the total. |
record_pass |
Put the pass's timings on the local loop series; the line to print. |
e2e |
Exercise the CI and release story on a local environment, by scenario. |
Attributes:
| Name | Type | Description |
|---|---|---|
E2E_OWNER |
|
|
E2E_REPO |
|
|
DEV_MEMBER |
|
|
KEPT_BY_SYNC |
|
|
SHARDS |
|
|
RUNS |
|
|
CURRENT |
|
|
CI_MARKERS |
tuple[str, ...]
|
|
LANES |
dict[str, Lane]
|
|
GitlabCall |
|
|
LOOP_MEMBERS |
tuple[LoopMember, ...]
|
|
CONTRIBUTING_MEMBER |
|
|
CONTRIBUTED_POINT |
|
|
VERIFY_TASK |
|
|
RATCHET_MEMBER |
|
|
SITE |
|
|
SCENARIOS |
tuple[Scenario, ...]
|
|
SETS |
dict[str, tuple[str, ...]]
|
|
LOOP_SERIES |
|
CI_MARKERS
module-attribute
¶
LANES
module-attribute
¶
LANES: dict[str, Lane] = {'gitea': Lane('gitea', 'http://gitea:3000', 'GITEA_URL', 'GITEA_TOKEN', '/api/v1/version', 'act_runner'), 'gitlab': Lane('gitlab', 'http://gitlab:8929', 'GITLAB_URL', 'GITLAB_TOKEN', '/api/v4/version', 'gitlab-runner')}
GitlabCall
module-attribute
¶
LOOP_MEMBERS
module-attribute
¶
LOOP_MEMBERS: tuple[LoopMember, ...] = (LoopMember('loop-echo', 'python-library'), LoopMember('loop-native', 'nanobind-module'), LoopMember('loop-cpp', 'cpp-package'))
SCENARIOS
module-attribute
¶
SCENARIOS: tuple[Scenario, ...] = (Scenario('birth', (), _born), Scenario('verified-skip', ('birth',), lambda p: _prove_verified_skip(_at(p), p.forge)), Scenario('members', ('birth',), lambda p: _ensure_members(_at(p), p.members)), Scenario('ratchet', ('members',), lambda p: _prepare_ratchet(_at(p), p.forge)), Scenario('scoped-leg', ('ratchet',), lambda p: _prove_scoped_leg(_at(p), p.forge)), Scenario('unproven-push', ('scoped-leg',), lambda p: _prove_unproven_push(_at(p), p.forge)), Scenario('prose-leg', ('members',), lambda p: _prove_prose_leg(_at(p), p.forge)), Scenario('tests-leg', ('members',), lambda p: _prove_tests_leg(_at(p), p.forge)), Scenario('release', ('members',), lambda p: _release_act(_at(p), p.forge), daemon=True), Scenario('nightly', ('release',), lambda p: _prove_nightly(_at(p), p.forge)), Scenario('dispatched-gate', ('members',), lambda p: _prove_dispatched_gate(_at(p), p.forge)), Scenario('contributed-point', ('members',), lambda p: _prove_contributed_point(_at(p), p.forge)))
SETS
module-attribute
¶
SETS: dict[str, tuple[str, ...]] = {'develop': ('birth', 'verified-skip', 'members', 'scoped-leg', 'unproven-push'), 'release': ('birth', 'verified-skip', 'members', 'scoped-leg', 'unproven-push', 'release'), 'points': ('nightly', 'dispatched-gate', 'contributed-point'), 'extension': ('birth', 'members'), 'all': tuple(scenario.name for scenario in SCENARIOS)}
Current
dataclass
¶
Current(name: str = '', mode: str = '', url: str = '', token: str = '', label: str = 'ubuntu-latest')
The environment a pass runs on, as the loop reads its forge from it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The environment's name; empty outside a pass. |
mode |
str
|
|
url |
str
|
The forge's URL in host mode; empty in docker mode, where the cascade's shared file names it. |
token |
str
|
The seeded API token in host mode. |
label |
str
|
The runner label the loop's workspace names as its runner and its wheel platform; the hosted name in docker mode, the environment's own label in host mode. |
Lane
dataclass
¶
One local forge the loop runs against, as the host and the runner reach it.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
The forge kind, |
alias |
str
|
The forge as CI sees it, the compose service name and port, true on the host too through its hosts entry. |
url_var |
str
|
The shared env key the seed writes the host-side URL to. |
token_var |
str
|
The shared env key the seed writes the lane token to. |
version_path |
str
|
The API path the hosts-entry probe reads. |
runner |
str
|
The compose service of the lane's runner. |
Methods:
| Name | Description |
|---|---|
publish |
The PyPI upload base for the loop's packages at base, the alias by default. |
index |
The simple index the loop's packages are read from. |
publish ¶
The PyPI upload base for the loop's packages at base, the alias by default.
Gitea keeps an owner's registry; GitLab a project's, addressed by its URL-encoded path.
Source code in packages/workshop/src/livery/workshop/_e2e.py
LoopMember
dataclass
¶
One member of the loop: its directory and the template it is born from.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The member's directory under |
template |
str
|
The template whose verb, |
Methods:
| Name | Description |
|---|---|
listed |
The extensions the member's contract lists, from its template. |
needs |
The extensions the loop's root lists before the member is created. |
holds |
The extensions the member's set holds: its list and what it requires. |
listed ¶
The extensions the member's contract lists, from its template.
The template's extensions in their canonical form, which a
birth writes into the contract, so the loop and the birth name
one list. The template is read from every available one,
whatever the driving checkout's lists hold: the loop's
workspace, not the driver's, creates the member.
Source code in packages/workshop/src/livery/workshop/_e2e.py
needs ¶
The extensions the loop's root lists before the member is created.
Those its template's chain needs: each template's
extensions and the extension declaring it, since a creation
installs nothing.
Source code in packages/workshop/src/livery/workshop/_e2e.py
holds ¶
The extensions the member's set holds: its list and what it requires.
Source code in packages/workshop/src/livery/workshop/_e2e.py
Pass
dataclass
¶
Pass(forge: str, url: str, fresh: bool = False, root: Path | None = None, timings: list[Timing] = list(), extension: str = '', stack: tuple[str, ...] = (), members: tuple[str, ...] = ())
What one pass carries between its scenarios.
Attributes:
| Name | Type | Description |
|---|---|---|
forge |
str
|
The lane's kind, |
url |
str
|
The forge's host-side URL from the shared environment. |
fresh |
bool
|
Whether the pass starts over from nothing. |
root |
Path | None
|
The loop's workspace once |
timings |
list[Timing]
|
One entry per scenario run, in order. |
extension |
str
|
The extension under test; empty for a plain pass. |
stack |
tuple[str, ...]
|
The extensions the birth lists: the loop's own (livery.workshop._e2e.loop_stack) or the extension under test's; empty for the stock list. |
members |
tuple[str, ...]
|
The members the members scenario lands, by name; empty for all. |
Timing
dataclass
¶
Scenario
dataclass
¶
One thing the loop proves, by name, with what must have run before it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The name |
needs |
tuple[str, ...]
|
The scenarios this one builds on; a pass runs them first, once, whether or not they were named. |
run |
Callable[[Pass], None]
|
The proof, given the pass. |
daemon |
bool
|
Whether it needs the runner's docker socket: the release builds the native member's wheel through cibuildwheel on the runner, and nothing else does. |
scrub_ci_markers ¶
scrub_ci_markers(environ: MutableMapping[str, str]) -> tuple[str, ...]
Remove CI's markers from environ; the names removed, in declared order.
Source code in packages/workshop/src/livery/workshop/_e2e.py
child_environment ¶
The environment a child the pass starts by hand begins with, extra over it.
The process environment over the task's. The pass is a serial task, so the process environment is the real one, where the pass writes its forge's own token after the task started; the task's carries what the git plugin wrote at the task's start, the tools' identity and the unsigned setting, which the process environment lacks. A spawn given an explicit environment takes neither by itself.
Source code in packages/workshop/src/livery/workshop/_e2e.py
edit_environments ¶
Write values and drop remove where this task and every child read them.
The pass is a serial task, so os.environ in it is the real
environment, which a child given an explicit environment built from
it inherits; footman's own run and the store's tool handles
spawn from the task's ctx.env, the environment the task started
with, so the same edit lands there too. Without the second write a
git the pass runs through the store commits without the identity
and the unsigned setting, which a hosted runner showed. Returns the
names removed from the process environment, in remove's order.
Source code in packages/workshop/src/livery/workshop/_e2e.py
dev_members ¶
The members whose dev wheels the loop eats: the workshop and what a birth lists.
Directory names, the workshop first, then each member that ships an extension a birth lists, and each dependency after the first member that names it, once. An edge of every kind counts: the wheel the runner installs resolves all of them from the loop's registry, and a member the closure does not reach publishes nothing there. An extension depends on the workshop, never the other way round, so the workshop's closure alone leaves the newborn's listed extensions nothing to install. extensions is the stack a birth lists, the stock list when None.
Raises:
| Type | Description |
|---|---|
Failed
|
when root has no workshop member to eat. |
Source code in packages/workshop/src/livery/workshop/_e2e.py
enter_environment ¶
enter_environment(name: str, extensions: Sequence[str], *, fresh: bool = False) -> Environment
Run the pass on environment name, brought up first; the environment.
A host-mode environment is brought up; with fresh it is removed
first, so the pass gets a new forge, and so is a directory that a
refused removal left. A removal that cannot take the whole
directory refuses, and the pass stops there
(livery.workshop._devenv.remove). The forge's URL and token then
go into the pass's environment (_enter_host). A docker-mode
environment is the compose rig, used as it is, fresh or not.
In both modes the pass and every process it starts then run with
the variables the set of extensions, the list the loop's
workspace is born with, declares, each one naming {place}
placed in the environment's directory. A tool's home placed there
goes with the environment: a release writes a remote into it that
names the environment's forge, and a home shared with an earlier
pass would keep that remote after the forge is gone, so a later
install that asks the remotes tries it and fails. A fresh pass
starts with nothing an earlier one wrote there.
Source code in packages/workshop/src/livery/workshop/_e2e.py
provision ¶
provision(kind: str = 'gitea') -> None
Ensure the loop's repository, idempotently, with its secrets.
The repository is created on the seeded organisation when absent
and reused when present. UV_PUBLISH_TOKEN is written as an
Actions secret with the forge token's value, because the forge's
own package registry authenticates with the same credential as
its API. Re-running is the recovery procedure.
Source code in packages/workshop/src/livery/workshop/_e2e.py
write_dev_index ¶
write_dev_index(folder: Path, wheels: Collection[Path]) -> Path
Lay wheels out at folder as a simple index uv reads; folder.
One directory per project, named as PEP 503 normalises it, holding the project's wheels and a page that links them, and a root page that links the projects. Whatever folder held before goes, so a wheel an earlier pass built is never offered again.
Source code in packages/workshop/src/livery/workshop/_e2e.py
checkout_index ¶
Build what a newborn installs from root as a local index at folder; its URL.
The members are livery.workshop._e2e.dev_members: the workshop,
what it depends on, and the extensions a birth lists. Each is built
by build_content_named, at the version its manifest declares with
a local segment naming its content, and
livery.workshop._e2e.write_dev_index lays the wheels out. Named
first in UV_INDEX, the index serves every distribution it holds,
whatever its version, because uv takes a package from the first
index that has it; every other package comes from the next.
UV_FIND_LINKS would not do: a folder named there only adds
candidates, and a stable release on PyPI beats a dev wheel
(measured). This is how a workspace installs this checkout's code
before a release, never the dev act, which on a main-family branch
is the release train. extensions is the stack the birth lists,
the stock list when None.
Source code in packages/workshop/src/livery/workshop/_e2e.py
build_content_named ¶
Build package's wheel into out, at a version naming its content; the wheel.
The build reads a copy of the package's directory, without its build outputs and environments. The copy's version gains a local segment, a digest of the copy's files, so the wheel's file name changes whenever its content does. uv caches an installed wheel by its file name and the place it came from, and installs the cached copy again without reading a newer file of that name (measured). The package's own files stay as they are. root is the workspace package belongs to, whose stamp phase writes the version.
Raises:
| Type | Description |
|---|---|
Failed
|
when nothing in the package's set answers its version, or adds a step to the stamp phase. |
Source code in packages/workshop/src/livery/workshop/_e2e.py
require_dev_branch ¶
require_dev_branch(root: Path) -> None
Refuse unless root stands on a branch whose release verb is the dev act.
The loop builds the dev wheels it installs with workflow.release
in this checkout, and the branch decides that verb's act. On
main or a reserved workflow/ branch it is the release train,
which opens a real release on this repository's forge, and a merged
one publishes to the real index; a detached HEAD names no act at all.
Source code in packages/workshop/src/livery/workshop/_e2e.py
scratch_branch ¶
Run a pass from a scratch branch where a build would be the release train.
--from-main: a nightly's checkout stands on main, where the
loop's first build is the release train, so the pass moves to
chore/loop-<stamp> at the same commit before anything builds
and returns afterwards, deleting the branch when it gained no
commit. A checkout already on a dev branch, or none, is left
alone. A dirty tree refuses naming the paths, so the scratch branch
holds exactly the commit it started from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path | None
|
The driver checkout, None when the pass runs outside one. |
required |
enabled
|
bool
|
Whether |
required |
Yields:
| Type | Description |
|---|---|
None
|
Nothing; the pass runs inside. |
Source code in packages/workshop/src/livery/workshop/_e2e.py
start_over ¶
start_over(lane: Forge, token: str, root: Path, *, url: str, wait: float = 120.0, kind: str = 'gitea') -> list[str]
Delete the loop's repository, its registry releases, and root; the lines.
Refuses while root holds commits its origin has not seen, since the repository they would land in is about to go. A repository or a release already gone is not an error: the next birth wants them absent, and a re-run of the reset is the recovery procedure. A delete the forge answers too slowly for the client completes on the server anyway, so the reset waits up to wait seconds for the repository to be gone before it refuses.
Source code in packages/workshop/src/livery/workshop/_e2e.py
judge_runs ¶
One line per run; red fails with every red run named.
A failed run is red. A cancelled run is red too, unless a twin for the same head took over and completed green, in which case the twin's verdict stands and the line says so; a successor for a moved head means the watched sha is no longer the branch's and is named as red, since the loop watches a sha of its own. A cancellation nobody took over stays red rather than quietly passing.
Source code in packages/workshop/src/livery/workshop/_e2e.py
members_for ¶
members_for(names: Sequence[str] = ()) -> tuple[LoopMember, ...]
The loop's members named names, in the loop's order; all when empty.
Source code in packages/workshop/src/livery/workshop/_e2e.py
landed_members ¶
The loop's members a pass lands for steps naming named, by name, in order.
A member lands for an extension a step names that its set holds and that no member whose set lies within its own holds too: the smaller member stands for that extension. loop-native's set holds loop-echo's, so a step naming python lands loop-echo alone, and one naming conan lands loop-native and loop-cpp. A pass carries the members its steps were written for, and no slower one besides.
Source code in packages/workshop/src/livery/workshop/_e2e.py
steps_declared_off ¶
The steps extension name declares enabled = false, by <phase>.<step>.
An extension pass turns each on in the newborn's root contract, so every step of the extension under test registers and runs.
Source code in packages/workshop/src/livery/workshop/_e2e.py
extension_under_test ¶
The list a pass births to test extension name, and the members it lands.
The members are the loop's whose sets hold an extension name's
steps name, by name (landed_members), so each step has something
of its own to judge. The list is name and what those members'
templates need (LoopMember.needs), as their canonical list: a
creation installs nothing, so the root lists them before the
members are created, and the set takes in what each requires. The
steps name declares off are turned on in the newborn's contract
(steps_declared_off), so each of its steps registers.
Raises:
| Type | Description |
|---|---|
Failed
|
when no installed distribution declares name, naming the installed ones; when name registers no step. |
Source code in packages/workshop/src/livery/workshop/_e2e.py
red_jobs_text ¶
red_jobs_text(repo: Repository, run: Run, *, lines: int = 60) -> str
The failed jobs of run with the last lines of each log, as text to print.
A run that went red on the loop's forge is readable at its page on a desk; inside a hosted job the forge vanishes with the job, so the pass prints what the page would show. Every job that ended in failure is named with its log's tail; a run whose jobs all passed or never ran gives the header line alone.
Source code in packages/workshop/src/livery/workshop/_e2e.py
loop_stack ¶
The extensions a plain pass's birth lists, as their canonical list.
The stock list without the site, and what the loop's members'
templates need (LoopMember.needs): a creation installs nothing,
so the root lists them before the members are created. The site is
the docs extension and every stock entry whose declaration requires
it, directly or through another: the docs extension puts a docs job
on every run of the loop's project, for a site nothing in a pass
reads, and an extension that requires it brings it into the root's
set. The pass proves the gate, the release train and the points,
and fm ci.e2e --extension=docs proves the docs extension on its
own. A stock entry no installed distribution declares requires
nothing and stays.
Source code in packages/workshop/src/livery/workshop/_e2e.py
scenarios_for ¶
The scenarios spec names, their needs added, in the registry's order.
spec is comma-separated set names and scenario names. A name that is neither refuses naming both lists; an empty spec refuses too. A need is run once however many names reach it.
Source code in packages/workshop/src/livery/workshop/_e2e.py
daemon_needed ¶
Whether any of scenarios needs the runner's docker socket.
run_scenario ¶
Run scenario for pass_, timed; a failure is timed and marked, then raised.
Source code in packages/workshop/src/livery/workshop/_e2e.py
timing_table ¶
The lines a pass ends with: each scenario's time and runs, then the total.
Source code in packages/workshop/src/livery/workshop/_e2e.py
record_pass ¶
Put the pass's timings on the local loop series; the line to print.
Source code in packages/workshop/src/livery/workshop/_e2e.py
e2e ¶
e2e(forge: str = 'gitea', fresh: bool = False, scenario: str = '', env: str = 'e2e', purge_cache: bool = False, extension: str = '', from_main: bool = False) -> None
Exercise the CI and release story on a local environment, by scenario.
--env names the environment the pass runs on, e2e by
default: one that does not exist is brought up in host mode
with one runner, --fresh removes it and brings it up
again, so a fresh pass is a new forge, and --purge-cache
removes the rig's shared caches first. The docker-mode
environment dev is the compose rig, addressed as before.
Each variable an extension of the loop's set declares with a
directory of its own is placed inside the environment, so what a
release writes there goes with the environment's forge.
--scenario names what the pass proves: scenario names, set
names, or both, comma-separated. The sets are develop
(birth, the verified skip, the members, the scoped leg), the
default, release (develop and the release act), points
(the nightly, the dispatched gate, the contributed point),
extension (birth and the members) and all; a scenario's
needs run first, once. --extension tests one extension in
isolation, extension the default set: the birth lists that
extension and what it requires instead of the loop's stack, and
the members are the loop's whose sets hold an extension its steps
name. birth builds
this checkout's workshop, its dependencies and the extensions a
birth lists into a local index, births or resumes the loop's
workspace through fm new.project from that index (so an
extension the birth lists needs no release), with its
repository, protection and setup pull request, provisions the
secrets, wires the workspace to the dev wheels in the forge's
registry, and follows the pushed head's runs to their verdicts
on the real runner. Re-running is the recovery procedure at every
step. The pass ends with a table, each scenario's time and
runs, and records the same rows on the local loop series.
--fresh starts over from nothing: the loop's repository on
the dev forge, its releases in the forge's registry, and the
local workspace go, then the pass births everything anew. It
refuses while the workspace holds commits the forge has not
seen. --from-main moves a checkout standing on main or a
reserved workflow/ branch, where a build would be the release
train, to a scratch branch at the same commit for the pass and
back afterwards; the nightly's checkout is one.
Source code in packages/workshop/src/livery/workshop/_e2e.py
3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 | |