livery.workshop._workflow_state¶
livery.workshop._workflow_state ¶
Where each reserved-branch workflow sits in its lifecycle.
A workflow lives on a reserved branch whose name is its identity:
workflow/release/<members> (the set's directory names, sorted,
joined with +, or their count and a digest when that runs long) or
workflow/update/<slug>. Different names
coexist; this reader tells the truth per branch and never arbitrates
between them, which is the decision extension's job
(livery.workshop._workflow_decision.workflow_decision).
Classification is a pure function (classify) of gathered
signals, so every mapping is testable with no I/O; the gathering
(gather) isolates the network and answers None when the
forge cannot be read. UNKNOWN is a first-class state, not an error:
a blip must never read as "nothing running", so everything that
mutates refuses on it.
Classes:
| Name | Description |
|---|---|
WorkflowKind |
Which reserved-branch workflow a branch names. |
WorkflowState |
Where a workflow sits in its lifecycle. |
Blocker |
Why a workflow will not land by itself, data beside the state. |
WorkflowStatus |
The detector's verdict for one workflow. |
Signals |
The gathered inputs |
Functions:
| Name | Description |
|---|---|
kind_of |
The kind a workflow name declares by its first segment. |
members_of |
A release name's package directories; empty for an update. |
classify |
Map gathered sig to a lifecycle state. Pure, no I/O. |
blocker |
Why the workflow will not land by itself. Pure, no I/O. |
base_moved_in_paths |
Whether |
gather |
Gather one workflow's signals, or None when the forge is unreadable. |
status_of |
One workflow's |
active_workflow_names |
The distinct workflow names in play, local and remote united. |
workflow_states |
Every active workflow, each classified on its own signals. |
Attributes:
| Name | Type | Description |
|---|---|---|
WORKFLOW_PREFIX |
|
|
TEARDOWN_SAFE |
|
TEARDOWN_SAFE
module-attribute
¶
TEARDOWN_SAFE = frozenset({WorkflowState.NONE, WorkflowState.PREPARING, WorkflowState.FAILED, WorkflowState.SUCCEEDED})
WorkflowKind ¶
WorkflowState ¶
Bases: Enum
Where a workflow sits in its lifecycle.
UNKNOWN means the forge could not be read: callers that mutate treat it like a live state and refuse, never assuming "nothing running" from a blip.
Attributes:
| Name | Type | Description |
|---|---|---|
NONE |
|
|
PREPARING |
|
|
IN_PROGRESS |
|
|
AWAITING_REVIEW |
|
|
FAILED |
|
|
SUCCEEDED |
|
|
UNKNOWN |
|
Blocker ¶
Bases: Enum
Why a workflow will not land by itself, data beside the state.
Attributes:
| Name | Type | Description |
|---|---|---|
NONE |
|
|
CONFLICTS |
|
|
CI_FAILING |
|
|
DISARMED |
|
|
CLOSED |
|
|
BEHIND_BASE |
|
|
REVIEW_REQUIRED |
|
|
STALE_SET |
|
WorkflowStatus
dataclass
¶
WorkflowStatus(kind: WorkflowKind | None, state: WorkflowState, name: str = '', branch: str = '', members: tuple[str, ...] = (), detail: str = '', reopenable: bool = False, author: str = '', armed: bool | None = False, blocker: Blocker = NONE, pr_number: int = 0, head_sha: str = '', ci_state: str = '', tagged: tuple[str, ...] = ())
The detector's verdict for one workflow.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
WorkflowKind | None
|
Release or update; None on the NONE placeholder. |
state |
WorkflowState
|
The lifecycle state. |
name |
str
|
The workflow name, the branch without its prefix
( |
branch |
str
|
The reserved branch ( |
members |
tuple[str, ...]
|
A release's package directory names; empty for an update. |
detail |
str
|
A short hint (the failing leg, an unreadable-arm note). |
reopenable |
bool
|
FAILED from a closed-unmerged PR; reopening is an option. |
author |
str
|
Who opened the PR, the forge's login namespace. |
armed |
bool | None
|
True = a schedule is live; False = confirmed unarmed; None = unreadable, which watches like armed (a false "disarmed" is the proven wrong exit). |
blocker |
Blocker
|
Why it will not land by itself. |
pr_number |
int
|
The workflow's PR, when one exists. |
head_sha |
str
|
The commit whose CI matters. |
ci_state |
str
|
The combined CI verdict for that commit. |
tagged |
tuple[str, ...]
|
A release's members whose receipt tag is already cut. |
Signals
dataclass
¶
Signals(kind: WorkflowKind, remote_branch: bool, pr_state: str, ci_state: str, tagged: tuple[str, ...] = (), members: tuple[str, ...] = (), armed: bool | None = False, mergeable: bool | None = None, detail: str = '', author: str = '', pr_number: int = 0, head_sha: str = '', stale_set: bool = False)
kind_of ¶
kind_of(name: str) -> WorkflowKind
The kind a workflow name declares by its first segment.
members_of ¶
A release name's package directories; empty for an update.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
classify ¶
classify(sig: Signals) -> WorkflowState
Map gathered sig to a lifecycle state. Pure, no I/O.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
blocker ¶
Why the workflow will not land by itself. Pure, no I/O.
CONFLICTS first (fixing them re-triggers CI anyway), then CI red, then the stale set (re-preparing also re-runs CI, so it outranks the arm question), then unarmed.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
base_moved_in_paths ¶
Whether origin/<base> carries commits head lacks touching paths.
The staleness probe for a release set: pure local git, empty paths is never stale. Movement outside the set's paths is harmless by construction and reads False. head is the release branch's tip; the checkout the act runs from is usually the base itself, so its own HEAD says nothing about the branch. A tip this clone does not hold reads False: the release pull request's own freshness check is the guard that never guesses.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
gather ¶
gather(repo: Repository, root: Path, name: str, *, base: str = 'main') -> Signals | None
Gather one workflow's signals, or None when the forge is unreadable.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 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 | |
status_of ¶
status_of(sig: Signals | None, name: str) -> WorkflowStatus
One workflow's WorkflowStatus from its gathered signals.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
active_workflow_names ¶
active_workflow_names(repo: Repository, root: Path) -> tuple[str, ...]
The distinct workflow names in play, local and remote united.
The union, never local-else-remote: a colleague's live release exists only on the remote, and a local leftover of your own would hide it. The remote probe degrades to the local list when the forge is unreachable.
Source code in packages/workshop/src/livery/workshop/_workflow_state.py
workflow_states ¶
workflow_states(repo: Repository, root: Path, *, base: str = 'main') -> tuple[WorkflowStatus, ...]
Every active workflow, each classified on its own signals.
Coexistence is legitimate; multiple names are states to report, not a broken invariant. Releases sort first, then by name.