livery.workshop._points¶
livery.workshop._points ¶
CI as points: what each point is, what it runs, and the verb that runs it.
A consumer never thinks about CI. They reason about a named point in
the process and attach a task to it. The four points are gate
(a pull request, or a dispatch by hand), merge (main after a
merge), nightly (the clock), and release (dispatched by the
merge point). A point is a declaration, livery.workshop._points.Point:
its workflow file, its events, and its jobs, each job stating what it
needs in the workshop's words (livery.workshop._points.Job); each
forge's renderer says those in its own. The emitted workflow is a
static shell, one fm ci.run --point=<p> --job=<j> per job, with
--shard=<i>of<n> on a check leg the contract splits, and what a
job does is data: the builtin schedule below, plus the
[[ci.schedule]] entries a workspace declares in workshop.toml.
The matrix shape belongs to a point's job, never to a task.
Reach for livery.workshop._points.run_point to run a job's
entries, and schedule to see them. Every entry runs as a child of
the runner's own command, so a scheduled task is any task the
workspace mounts, and the child's exit is the entry's.
The merge point inherits the gate's jobs: a push to main runs the
same checks, plus the jobs only a merge has (the docs deploy, the
governance reconcile). A shell spells --point=gate on the shared
jobs and the verb promotes the point on a push, so the YAML carries
no decision.
A package contributes a point of its own through [[ci.point]] in
its workshop.toml: a scheduled point with a dispatch entry, one
job on the runners and Pythons it names, running the task it names
with the job token and nothing more. points is every point a
workspace has, the builtin four first; every reader takes that set.
Classes:
| Name | Description |
|---|---|
Input |
One input a dispatched point takes, as the forge prompts for it. |
Job |
One job of a point's shell, in the workshop's words. |
Point |
One point: its workflow file, its events, and its jobs. |
Contribution |
A point a package contributes, and the entry that runs it. |
JobContribution |
One job a mounted extension adds to a builtin point, with its entries. |
Entry |
One scheduled task: at which point and job, which task, which arguments. |
Functions:
| Name | Description |
|---|---|
verify_points |
Refuse a set of declarations a shell cannot be rendered from. |
contributed |
The |
point_has_job |
Whether the builtin point has the job name, declared, inherited or added. |
verdict_jobs |
Each builtin point that declares a verdict job of its own, with the job's name. |
judges_refusal |
Why judges may not join job of point; empty when they may. |
contribute_job |
Add job to the builtin point on behalf of extension, or join one. |
snapshot |
The jobs the extensions added and joined, and the kept task tree, for restore. |
restore |
Put the added jobs, the joins and the kept task tree back to state. |
contributed_jobs |
The jobs the extensions contributed to point, in contribution order. |
joined_jobs |
The joins the extensions made to point's jobs, in contribution order. |
contributor_of |
The extension that contributed job to point; the base for its own jobs. |
verdict_needs |
What point's verdict waits for: its declared needs, then the gating jobs. |
composed_points |
The builtin points with the extensions' contributed jobs in place. |
points |
Every point root has: the builtin four, then the ones its packages contribute. |
emitted_points |
|
inherited_jobs |
The jobs point runs before its own, from the point it inherits. |
point_by_name |
|
jobs_reading |
The jobs whose declared inputs read path, each |
unread_by_the_job |
The line that skips job of point when nothing it reads changed, or empty. |
job_installs |
What each job installs before it enters, by its point and its name. |
job_seams |
The seam each deploying job publishes through, by its point and its name. |
job_runners |
The runner labels each job's |
events_of |
The events that start point's runs; refuses a name that is not a point. |
dispatchable |
The points a person starts by hand: a dispatch entry and no input to supply. |
profile_box |
The job's drop box, where every entry leaves its own timeline. |
trace_file |
The file an entry's own trace is written to, named after the task. |
due |
Whether a cadence runs on on, and the day it runs next. |
declared |
The |
builtin_schedule |
The builtin entries with the extensions' contributed jobs' entries in place. |
schedule |
Every entry: the builtin ones, the packages' contributed ones, the contract's. |
recording |
The record ending every job of each point of root with no verdict job. |
half_writers |
The jobs of point that put a half of the run's row, by their schedule names. |
workflow_of |
The workflow file point's shell is; refuses a name that is not a point. |
jobs_of |
The jobs point has: declared ones, inherited first, then any an entry names. |
first_leg |
The first leg of job at point: its first runner and its first Python. |
entries_for |
The entries job of point runs, in order; refuses an unknown job. |
scheduled_tasks |
Every task point runs, across its jobs, in schedule order, once each. |
asked_tasks |
The tasks a dispatch's only names, judged against what point runs. |
pull_request_runners |
The runners a pull request's check legs fan out to. |
pull_request_listed |
Name the list a pull request's runners come from, for a shard refusal. |
pull_request_legs |
Name the check legs a pull request's run produces, |
check_legs |
Name the check legs the gate produces, |
shards_max |
The most shards a runner may take: |
shard_counts |
The shards per runner |
check_shards |
Name the shard legs the gate produces, split as |
pull_request_shards |
Name the shard legs a pull request's run produces, split as the contract says. |
sharded_legs |
The platform legs the contract splits into shards, on any event. |
effective_point |
The point a shell's |
run_point |
Run every entry of job at point, in order; a red entry fails the job. |
Attributes:
| Name | Type | Description |
|---|---|---|
EVENT_NAMES |
|
|
ONLY |
|
|
CLOCK |
|
|
DECLARED |
tuple[Point, ...]
|
|
POINT_BY_NAME |
dict[str, Point]
|
|
POINTS |
|
|
POINT_NAME |
|
|
MOUNTED |
Tasks | None
|
|
EVENTS |
|
|
DISPATCHABLE |
|
|
INHERITS |
|
|
TRACE |
|
|
CADENCES |
|
|
today |
Callable[[], date]
|
The day a run judges a cadence on, UTC as the runners keep it. |
COLLECT |
|
|
DROP_TASK |
|
|
RECORD_TASK |
|
|
BUILTIN |
tuple[Entry, ...]
|
|
EVERY_RUNNER_LABEL |
|
|
SHARDS_MAX |
|
EVENT_NAMES
module-attribute
¶
DECLARED
module-attribute
¶
DECLARED: tuple[Point, ...] = (Point('gate', 'ci.yml', ('pull_request', 'workflow_dispatch'), note='A pull request, a push to main, and a dispatch by hand. A dispatched run pays the full gate: the check verb reads the event and narrows on a pull request alone, so every event spells the same call.', jobs=(Job('check', matrix='legs', fetch='full', writes=True, note="The check legs: each runs the gate, and its row rides its per-run ref on the state store, in one write with the files its other entries left, for the gate job. The scoped gate measures from the proved tree nearest the checkout's, an earlier push's merge rebuilt from its two commits among them, or from the merge base with the pull request's base branch; each needs history a shallow clone lacks."), Job('gate', needs=('check',), always=True, fetch='full', token='job', writes=True, dispatches=True, step='Verdict', note="The one required context. Branch protection points here, so the matrix can grow or shrink without touching repository settings. Its entries run the judges the extensions add, collect the run's timing rows, ask the forge for the jobs it needs, and stamp the tree a green run proved; a red run is judged too. The stamp composes a narrowed run with the record of the tree its legs measured from, and names the two commits a merge checkout joined. On a push to main the same job then dispatches the release wave, runs what the extensions add to the merge point, and runs the janitor."))), Point('merge', 'ci.yml', ('push',), inherits='gate', jobs=(Job('govern', fetch='2', token='admin', note="The repository settings reconciled when the merge changed a contract or the owners file. The commit's own file list decides whether anything is governed; a depth of one would read a squash as a root."),)), Point('nightly', 'nightly.yml', ('schedule', 'workflow_dispatch'), inputs=(Input(ONLY, 'the scheduled tasks to run, comma-separated; empty runs the whole schedule'),), cron=CLOCK, note="The nightly point: the clock and a dispatch entry, one call per Python. What runs is the workshop's builtin schedule plus [[ci.schedule]] in workshop.toml, and the tests that declare the nightly point are selected in.", jobs=(Job('nightly', matrix='pythons', fetch='full', token='repository', writes=True, note="A verification checks the tree out at a release tag. A pull request a scheduled task opens with the job token starts no workflow, so the repository's token carries the nightly where there is one. The job's profile trace rides the state store at its end, which needs the write grant as the check legs' puts do."),)), Point('release', 'release.yml', ('workflow_dispatch',), inputs=(Input('ref', 'the release squash to publish', required=True), Input('workshop', "a released livery-workshop version to drive the wave; empty runs the squash's own")), ref_input='ref', note="The train: a workflow.release PR merges, this publishes its squash, and the receipt tags are cut only after the index confirms each member. A tag is a receipt, never a trigger: the merge point's dispatch job starts the wave at the release squash, and a hand dispatch with --ref is the recovery entry when a publish died mid-wave; --workshop names a released driver for a wave whose own workshop was the fault.", jobs=(Job('publish', fetch='full', token='repository', writes=True, pushes=True, publishes_index=True, environment='pypi', step='Publish the wave', note="The wave: publish the ref, cut the receipt tags after the index confirms each member. The receipt push carries the repository's token where there is one: the job token may not push a ref whose commit carries a workflow file that differs from the tip's."),)))
POINT_BY_NAME
module-attribute
¶
DISPATCHABLE
module-attribute
¶
DISPATCHABLE = tuple(point.name for point in DECLARED if 'workflow_dispatch' in point.events and not any(item.required for item in point.inputs))
INHERITS
module-attribute
¶
INHERITS = {point.name: point.inherits for point in DECLARED if point.inherits}
today
module-attribute
¶
The day a run judges a cadence on, UTC as the runners keep it.
A variable, not a function, so a test fixes the day instead of waiting for a Monday.
BUILTIN
module-attribute
¶
BUILTIN: tuple[Entry, ...] = (Entry('gate', 'check', 'check', sharded=True), Entry('gate', 'check', 'ci.leg', ('--job={display}',), last=True), Entry('gate', 'gate', 'workflow.release.check-title'), Entry('gate', 'gate', 'ci.fold'), Entry('gate', 'gate', COLLECT), Entry('gate', 'gate', 'speed.judge'), Entry('gate', 'gate', 'ci.verdict', ('--needs=check',)), Entry('gate', 'gate', 'ci.verified.stamp'), Entry('gate', 'gate', 'workflow.release.check-fresh'), Entry('gate', 'gate', DROP_TASK, ('--point=gate', '--job={display}'), last=True), Entry('merge', 'govern', 'workflow.configure', ('--if-changed',)), Entry('merge', 'gate', 'workflow.release.dispatch'), Entry('merge', 'gate', 'janitor', last=True), Entry('nightly', 'nightly', 'doctor', ('--fix',)), Entry('nightly', 'nightly', 'check'), Entry('release', 'publish', 'workflow.release.publish', ('--ref={ref}',)))
Input
dataclass
¶
One input a dispatched point takes, as the forge prompts for it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The input's name, as the dispatch passes it. |
description |
str
|
What the input is, for the person dispatching. |
required |
bool
|
Whether a dispatch without it is refused. |
default |
str
|
The value an absent optional input takes. |
Job
dataclass
¶
Job(name: str, matrix: str = '', runners: tuple[str, ...] = (), pythons: tuple[str, ...] = (), labels: Callable[[Path], Sequence[str]] | None = None, needs: tuple[str, ...] = (), always: bool = False, fetch: str = '', token: str = '', writes: bool = False, pushes: bool = False, publishes_index: bool = False, installs: Callable[[Path], Sequence[str]] | None = None, conan_cache: bool = False, deploy: Callable[[Path], str] | None = None, publishes: str = '', paths: tuple[str, ...] = (), collects: str = '', environment: str = '', dispatches: bool = False, inputs: Inputs | None = None, step: str = '', note: str = '', joins: bool = False)
One job of a point's shell, in the workshop's words.
Each forge's renderer says these in that forge's words: a grant, a step, an action, an image. Nothing here is forge-shaped.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The job's name, and the |
matrix |
str
|
The legs the job fans out to: |
runners |
tuple[str, ...]
|
The runners a |
pythons |
tuple[str, ...]
|
The Pythons a |
labels |
Callable[[Path], Sequence[str]] | None
|
The function naming the runner labels a |
needs |
tuple[str, ...]
|
The jobs of the point this one waits for. |
always |
bool
|
Whether the job runs when a job it needs was red, the verdict job's shape. |
fetch |
str
|
How deep the checkout is: |
token |
str
|
The credential the verb sees as |
writes |
bool
|
Whether the job pushes to the repository (the state store, a receipt tag), which needs the write grant. |
pushes |
bool
|
Whether the job pushes through git itself, so the checkout carries the credential the push needs. |
publishes_index |
bool
|
Whether the job uploads to a package index,
so the index token reaches it as |
installs |
Callable[[Path], Sequence[str]] | None
|
The function naming the system packages the job installs before it enters, given the workspace's root; None for none. The extension that contributes the job names it, so the render installs them without knowing what they are for. |
conan_cache |
bool
|
Whether the job builds native packages, so the lane restores and saves conan's home around it. |
deploy |
Callable[[Path], str] | None
|
The function naming the seam the job publishes a site
through after the call, given the workspace's root; None
for a job that publishes none. A |
publishes |
str
|
The artifact the job uploads, |
paths |
tuple[str, ...]
|
The paths the uploaded artifact carries, as the forge
globs them; |
collects |
str
|
The artifact the job downloads first, |
environment |
str
|
The named deployment environment the job runs in,
|
dispatches |
bool
|
Whether the job starts another workflow through the
forge's API, which GitHub's workflow token may do only with
the |
inputs |
Inputs | None
|
The files the job's entries read, declared as a step declares its own: a pull request's run that changed none of them skips the entries. None for a job that always runs. |
step |
str
|
What the forge's run page calls the one call; the job's name capitalised when empty. |
note |
str
|
The comment the rendered shell prints above the job. |
joins |
bool
|
Whether the job is a contribution to a job the point already has, declared or inherited. It renders as no job of its own: its entries follow that job's, and its plumbing, what it collects and publishes, the seam it deploys through and the packages it installs, renders on that job under the contributing point's own event condition. |
installs
class-attribute
instance-attribute
¶
Point
dataclass
¶
Point(name: str, workflow: str, events: tuple[str, ...], jobs: tuple[Job, ...] = (), inherits: str = '', inputs: tuple[Input, ...] = (), ref_input: str = '', cron: str = '', note: str = '')
One point: its workflow file, its events, and its jobs.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The point's name, and the |
workflow |
str
|
The workflow file the point's shell is, as GitHub and Gitea address a dispatch and name a run. Two points may share one, the gate and the merge point do, when their events do not overlap. GitLab has one pipeline document and names a dispatched pipeline after this. |
events |
tuple[str, ...]
|
The events that start the point's runs, from
|
jobs |
tuple[Job, ...]
|
The point's own jobs, in order. |
inherits |
str
|
A point whose jobs this one runs first, the gate's
for the merge point; |
inputs |
tuple[Input, ...]
|
The inputs a dispatch takes. A point with a required
one is dispatched by a verb that supplies it, never by
hand. Every job of a point that takes a |
ref_input |
str
|
The input naming the commit the jobs check out,
|
cron |
str
|
When the clock starts the point, for a point whose
events include |
note |
str
|
The comment the rendered shell prints under its name. |
Contribution
dataclass
¶
JobContribution
dataclass
¶
JobContribution(point: str, job: Job, entries: tuple[Entry, ...] = (), gates: bool = False, extension: str = '')
One job a mounted extension adds to a builtin point, with its entries.
Attributes:
| Name | Type | Description |
|---|---|---|
point |
str
|
The builtin point the job joins. |
job |
Job
|
The job, as the point would declare it. |
entries |
tuple[Entry, ...]
|
The tasks the job runs, each naming the point and the job. |
gates |
bool
|
Whether the point's verdict waits for the job. |
extension |
str
|
The extension that contributed it, for a refusal. |
Entry
dataclass
¶
Entry(point: str, job: str, task: str, args: tuple[str, ...] = (), source: str = 'builtin', every: str = '', once: bool = False, last: bool = False, judges: bool = False, sharded: bool = False)
One scheduled task: at which point and job, which task, which arguments.
Attributes:
| Name | Type | Description |
|---|---|---|
point |
str
|
One of |
job |
str
|
The job of the point the entry runs in. |
task |
str
|
The task's dotted address, as the workspace mounts it. |
args |
tuple[str, ...]
|
The arguments, each formatted with the run's facts:
|
source |
str
|
Where the entry was declared. |
every |
str
|
The cadence, |
once |
bool
|
Whether the entry runs on a matrix job's first leg alone, the first runner and the first Python, and on that leg's first shard alone; every leg and shard otherwise. |
sharded |
bool
|
Whether the entry takes the leg's shard,
|
last |
bool
|
Whether the entry runs after every entry an extension adds to the job, the janitor's shape; the added entries go before the first such entry. |
judges |
bool
|
Whether the entry judges the run before the verdict: a judge an extension adds to a point's verdict job runs before the job collects the run's rows, and a red one stops the job there, as a red builtin entry does. |
verify_points ¶
Refuse a set of declarations a shell cannot be rendered from.
A point name declared twice, an event outside EVENT_NAMES, a
point inheriting one that is not declared, two points sharing a
workflow file whose events overlap (a run would belong to both),
a job name declared twice in one point, a job needing a job the
point does not have, a job collecting an artifact no job of the
point publishes, and a job collecting an artifact from jobs it
does not wait for each refuse naming the point and the fault. A
job starts once the jobs it needs end, so a job it does not wait
for may not have uploaded the artifact yet. A join waits for what
the job it joins waits for.
Source code in packages/workshop/src/livery/workshop/_points.py
389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 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 | |
contributed ¶
contributed(root: Path, *, mounted: Callable[[str], bool] | None = None) -> tuple[Contribution, ...]
The [[ci.point]] declarations of root's packages, refusing bad ones.
Each table names a name (the point's, a workflow file name and
a job name at once), a task, and optionally args,
every (a cadence from CADENCES), runners (the root
contract's when absent) and pythons (the newest gate Python
when absent). A name that is a builtin point or that two packages
claim, a name POINT_NAME refuses, a cadence that is not one, a
task mounted does not know (the runner's own registry when
absent), and a permission, secret or environment key each refuse
at load, naming the package and the point.
Source code in packages/workshop/src/livery/workshop/_points.py
529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 | |
point_has_job ¶
Whether the builtin point has the job name, declared, inherited or added.
Source code in packages/workshop/src/livery/workshop/_points.py
verdict_jobs ¶
Each builtin point that declares a verdict job of its own, with the job's name.
A verdict job runs whatever the jobs it needs did; the judges an extension adds join one of these.
Source code in packages/workshop/src/livery/workshop/_points.py
judges_refusal ¶
Why judges may not join job of point; empty when they may.
Judges join a point's own verdict job alone: they run before it collects the run's rows, and a red one stops it before the verdict and the stamp.
Source code in packages/workshop/src/livery/workshop/_points.py
contribute_job ¶
contribute_job(point: str, job: Job, *, entries: tuple[Entry, ...] = (), gates: bool = False, extension: str) -> None
Add job to the builtin point on behalf of extension, or join one.
The job sits before the first job of the point that needs it, else
before the point's verdict job, else last (composed_points), so a
contributed job renders before the jobs that wait for it and where
a declared one would; a gating job joins the verdict's needs. A
job that joins names a job the point already has
(point_has_job): its entries follow that job's own, before any
the job runs last, its plumbing renders on that job, and its needs
join the needs of a job the point has of its own. Refuses a point
that is not builtin, a job name the point already has when the job
does not join, a join of a job the point does not have, a join that
gates, a name another extension contributed, an entry naming
another point or job, and a judge on a job that is not the point's
own verdict job (judges_refusal).
Source code in packages/workshop/src/livery/workshop/_points.py
snapshot ¶
snapshot(*, initial: bool = False) -> tuple[dict[tuple[str, str], JobContribution], dict[tuple[str, str, str], JobContribution], Tasks | None]
The jobs the extensions added and joined, and the kept task tree, for restore.
Judges ride their joins' entries. livery.workshop._points.restore puts all three back. With initial, the state a process starts with instead: no job added or joined, and no task tree kept.
Source code in packages/workshop/src/livery/workshop/_points.py
restore ¶
restore(state: tuple[dict[tuple[str, str], JobContribution], dict[tuple[str, str, str], JobContribution], Tasks | None]) -> None
Put the added jobs, the joins and the kept task tree back to state.
Source code in packages/workshop/src/livery/workshop/_points.py
contributed_jobs ¶
contributed_jobs(point: str) -> tuple[JobContribution, ...]
The jobs the extensions contributed to point, in contribution order.
joined_jobs ¶
joined_jobs(point: str) -> tuple[JobContribution, ...]
The joins the extensions made to point's jobs, in contribution order.
contributor_of ¶
The extension that contributed job to point; the base for its own jobs.
Source code in packages/workshop/src/livery/workshop/_points.py
verdict_needs ¶
What point's verdict waits for: its declared needs, then the gating jobs.
Source code in packages/workshop/src/livery/workshop/_points.py
composed_points ¶
The builtin points with the extensions' contributed jobs in place.
A contributed job sits before the first job of its point that needs
it, else before the point's verdict job, else last: a job renders
before the jobs that wait for it, and where a declared one would.
The verdict waits for what verdict_needs names. A join's needs
join the needs of the job it joins when the point has that job of
its own, declared or contributed; the read of a declaration refuses
needs on a join of a job the point inherits, whose needs are the
point's it inherits from.
Source code in packages/workshop/src/livery/workshop/_points.py
points ¶
Every point root has: the builtin four, then the ones its packages contribute.
None is a process outside any workspace, which has the builtin
four alone, with the jobs the mounted extensions contributed in place.
The whole set is verified as one: a contributed point cannot
share a file or a name with another.
Source code in packages/workshop/src/livery/workshop/_points.py
emitted_points ¶
points, plus a job for each name only the contract's entries give.
A [[ci.schedule]] entry in the root contract may name a job its
point does not declare (jobs_of lists it); the shell needs that
job to call it. The job runs on one runner, the newest gate
Python, with the checkout depth, token and write grant of the
point's first job: the root contract is where a grant is decided,
so this widens nothing a package could reach.
Source code in packages/workshop/src/livery/workshop/_points.py
inherited_jobs ¶
The jobs point runs before its own, from the point it inherits.
Source code in packages/workshop/src/livery/workshop/_points.py
point_by_name ¶
jobs_reading ¶
The jobs whose declared inputs read path, each <point>/<job>.
Source code in packages/workshop/src/livery/workshop/_points.py
unread_by_the_job ¶
The line that skips job of point when nothing it reads changed, or empty.
Only a job that declares inputs skips, and only on a pull
request's run in a workspace declaring [ci] affected-legs, the
terms the check legs narrow on: a push, a dispatch, the clock and a
person's own run always run every entry. The changes are the run's
own (livery.workshop.ci_changes), read the way the check legs
read them, and the inputs select as a step's do, so a change to
the sources of the extension that contributed the job runs it.
Source code in packages/workshop/src/livery/workshop/_points.py
job_installs ¶
job_installs(root: Path, everything: tuple[Point, ...] | None = None) -> dict[tuple[str, str], tuple[str, ...]]
What each job installs before it enters, by its point and its name.
Only a job that names an installs function has an entry. Its
packages are sorted and named once, so the rendered file is the
same on every run. everything is the points to read; root's
when absent.
Source code in packages/workshop/src/livery/workshop/_points.py
job_seams ¶
The seam each deploying job publishes through, by its point and its name.
Only a job that names a deploy function has an entry.
everything is the points to read; root's when absent.
Source code in packages/workshop/src/livery/workshop/_points.py
job_runners ¶
job_runners(root: Path, everything: tuple[Point, ...] | None = None) -> dict[tuple[str, str], tuple[str, ...]]
The runner labels each job's labels function names, by point and job.
Only a job that names a labels function has an entry: the
labels the function names for root, in its order and each once,
so the rendered file is the same on every run. An empty entry is a
runners job this workspace renders no job for. everything is
the points to read; root's when absent.
Source code in packages/workshop/src/livery/workshop/_points.py
events_of ¶
The events that start point's runs; refuses a name that is not a point.
Source code in packages/workshop/src/livery/workshop/_points.py
dispatchable ¶
The points a person starts by hand: a dispatch entry and no input to supply.
An optional input, the nightly's only, leaves a point
dispatchable; a required one, the release's ref, does not.
Source code in packages/workshop/src/livery/workshop/_points.py
profile_box ¶
profile_box() -> AbstractContextManager[Path]
The job's drop box, where every entry leaves its own timeline.
The plugin owns the directory and its sweeping; this names it to the entries through the environment the runner already builds for them, which is why nothing here writes this process's own.
Source code in packages/workshop/src/livery/workshop/_points.py
trace_file ¶
The file an entry's own trace is written to, named after the task.
One file per entry rather than one per job: the leg's timing row reads the gate's own file, and a person reading a runner's working directory can tell which entry a trace belongs to.
Source code in packages/workshop/src/livery/workshop/_points.py
due ¶
Whether a cadence runs on on, and the day it runs next.
A weekly entry runs on Mondays; a two-weekly entry on the Monday of an even ISO week, so every workspace agrees on the day without a record of the last run. An empty cadence is due on every run.
Source code in packages/workshop/src/livery/workshop/_points.py
declared ¶
The [[ci.schedule]] entries of root's contract, refusing bad ones.
Each entry names a point (one of points), a task, and
optionally a job (the point's own name when absent), args
and every, a cadence from CADENCES. An unknown point, a
missing task, arguments that are not strings, or a cadence that
is not one refuse at load, naming the entry.
Source code in packages/workshop/src/livery/workshop/_points.py
builtin_schedule ¶
The builtin entries with the extensions' contributed jobs' entries in place.
A contributed job's entries follow the declared entries of its
point's jobs before the verdict, and the verdict's --needs
names the composed list.
Source code in packages/workshop/src/livery/workshop/_points.py
schedule ¶
Every entry: the builtin ones, the packages' contributed ones, the contract's.
Then the record each job of a point without a verdict job ends
with (recording), after every entry the contract gave the job.
Source code in packages/workshop/src/livery/workshop/_points.py
recording ¶
The record ending every job of each point of root with no verdict job.
A verdict job collects what its point's legs put; a point without
one (the nightly, the release, every point a package contributes)
would leave no row of its run, so each of its jobs ends with
RECORD_TASK, which puts the job's own half, collects the run's
row and drops the per-run refs when it is the run's last green
job. The jobs are the point's declared ones and any a
[[ci.schedule]] entry in scheduled names.
Source code in packages/workshop/src/livery/workshop/_points.py
half_writers ¶
The jobs of point that put a half of the run's row, by their schedule names.
The check legs of a point with a verdict job (ci.leg), and every
job of a point without one (RECORD_TASK). A forge lists a matrix
job's legs under the job's name with the leg in brackets, so a
reader matches by prefix.
Source code in packages/workshop/src/livery/workshop/_points.py
workflow_of ¶
The workflow file point's shell is; refuses a name that is not a point.
Source code in packages/workshop/src/livery/workshop/_points.py
jobs_of ¶
The jobs point has: declared ones, inherited first, then any an entry names.
A [[ci.schedule]] entry may name a job no declaration has; it
is listed after the declared jobs, in schedule order.
Source code in packages/workshop/src/livery/workshop/_points.py
first_leg ¶
The first leg of job at point: its first runner and its first Python.
An axis the job does not have is empty. The check legs fan out
over [ci] runners and the gate's Pythons, the nightly over every
Python on the first runner, a declared job over its own lists. A
runners job's call names no leg and a job with no matrix has
none, so neither has a leg to name.
Source code in packages/workshop/src/livery/workshop/_points.py
entries_for ¶
The entries job of point runs, in order; refuses an unknown job.
A point's own name is always a job of it, with nothing scheduled until an entry attaches: the nightly shell exists before its first entry, and runs green and empty until then.
Source code in packages/workshop/src/livery/workshop/_points.py
scheduled_tasks ¶
Every task point runs, across its jobs, in schedule order, once each.
Source code in packages/workshop/src/livery/workshop/_points.py
asked_tasks ¶
The tasks a dispatch's only names, judged against what point runs.
Empty for an empty only, which runs the whole schedule.
Raises:
| Type | Description |
|---|---|
Failed
|
when only names a task the point does not run, naming the ones it does. |
Source code in packages/workshop/src/livery/workshop/_points.py
pull_request_runners ¶
The runners a pull request's check legs fan out to.
[ci] pull-request-runners when the contract declares it, else
the first runner [ci] runners names (ubuntu-latest without
that key). A one-runner pull request carries the other legs'
coverage rows from main's record, so a package whose floor needs
the platform legs' fresh rows on a pull request lists every runner.
A label the runners list does not name refuses naming both lists,
since a pull request's legs run on runners every event runs on; an
empty list refuses too.
Source code in packages/workshop/src/livery/workshop/_points.py
pull_request_listed ¶
Name the list a pull request's runners come from, for a shard refusal.
[ci] pull-request-runners when the contract declares it. When
the key is absent the refusal names it and the first runner
[ci] runners names, which stands in for it.
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
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
shards_max ¶
The most shards a runner may take: [ci] shards-max, SHARDS_MAX when absent.
A value that is not a whole number, or is below 1, fails naming it.
Source code in packages/workshop/src/livery/workshop/_points.py
shard_counts ¶
shard_counts(ci: dict[str, Any], *, key: str, runners: Sequence[str], listed: str) -> dict[str, int]
The shards per runner [ci] <key> gives, one for a runner it does not name.
runners are the labels the legs fan out to and listed names the
key they came from, for the refusal. The task fails, naming the key
and the runner, when the table names a runner runners does not
hold, gives a count below 1 or above shards_max, or gives one
that is not a whole number.
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_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
sharded_legs ¶
The platform legs the contract splits into shards, on any event.
Each platform leg once, in matrix order: one [ci] shards or
[ci] pull-request-shards gives above one
(livery.workshop.check_shards,
livery.workshop.pull_request_shards). Empty without a root
contract. The task fails as those fail, naming the key and the
runner.
Source code in packages/workshop/src/livery/workshop/_points.py
effective_point ¶
The point a shell's gate means on a push: the merge point.
The shared jobs spell --point=gate; inside CI, a push event
is the merge point, so the promotion happens here and never in
the YAML. Outside CI, and on every other event, the point stands.
Source code in packages/workshop/src/livery/workshop/_points.py
run_point ¶
run_point(root: Path, point: str, job: str, *, os_label: str = '', python: str = '', shard: str = '', spawn: Callable[[list[str], dict[str, str]], int] = _spawn) -> None
Run every entry of job at point, in order; a red entry fails the job.
A red builtin entry stops the job at once, since the entries after
it read its verdict, and so does a red judge an extension adds to
the verdict job; a red entry of the contract's schedule stands
on its own, so the scheduled entries after it still run, and the
job fails at the end naming each red one. A dispatch that names
tasks in the nightly's only input runs those alone, builtin or
scheduled, and says what it skipped.
os_label and python are the matrix facts the shell passes for
a matrix job; they format the entries' arguments and name the
leg. shard is the leg's shard, 2of4, on a check leg the
contract splits; empty runs as one shard of one. A count above
one ends the label and the display name
(check-windows-latest-3.14-2of4, check (windows-latest,
3.14, 2of4), and on GitLab check: [2of4], as it lists a job
run as parallel: matrix), and an entry declared sharded
takes --shard=2of4; one shard of one leaves the label, the
display name and every call as the unsplit leg's. A spelling outside
<i>of<n> fails naming it, before any entry runs. An entry
with once runs on the first leg's first shard alone, and the
skip line names the shard when the leg is the first. An entry
with a cadence runs only on its day, judged by
today, and says when it runs next otherwise. Every entry runs
under --profile, writing its own trace beside the others, and
the job's box collects them into one timeline, which the runner
pushes where [ci] profile asks; [ci] timing = false does
none of that. Every child's
environment names the leg in
livery.workshop._ci_context.LEG_VARIABLE, the key of the leg's rows
and stamps, and the resolved point in
livery.workshop.POINT_VARIABLE, which selects the tests a point
runs. A job that declares inputs runs no entry on
a pull request that changed nothing it reads (unread_by_the_job).
spawn runs one entry's command in that environment and returns
its exit code; the default is the runner's own child.
Source code in packages/workshop/src/livery/workshop/_points.py
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 | |