livery.workshop._verdict¶
livery.workshop._verdict ¶
Where a branch's pull request stands, as one plain answer.
One read of the forge plus two local git probes, folded into a livery.workshop._verdict.Verdict that names the state and the exit code a caller branches on. The codes are stable interface: skills, hooks, and humans read them, so a new state gets a new code, never a reused one.
Exit codes
10: the merge would conflict; integrate the base and re-submit. 11: nothing will merge it; the pull request is not armed. 12: the pull request is closed unmerged. 13: CI is red; the message names the failing job. 14: still in flight when the watch deadline passed. 15: the forge was unreachable past the transient budget. 16: green and armed with no merge; the server lost the evaluation. 17: the head is behind the base; integrate and re-submit.
A required-review blocker is not an error: readable protection with
approvals outstanding reads as awaiting-approvals, exit 0, and
the message names the missing count and the eligible reviewers.
Protection the token cannot read is never asserted as a blocker; the
pull request reads as 16 and the message says what to check.
Classes:
| Name | Description |
|---|---|
Pace |
A watch's waits between polls of the forge. |
Transient |
A bounded run of unreadable polls: each printed once, the budget ends it. |
Pending |
What one poll answers while the thing followed is not there yet. |
FollowTimedOut |
A follow reached its deadline with the thing followed still pending. |
ForgeUnreachable |
A follow spent its transient budget on unreadable polls. |
Verdict |
One reading of where a branch's pull request stands. |
JobWatch |
The jobs of a head's runs, reported as they move, each line stamped. |
Functions:
| Name | Description |
|---|---|
paced |
The seconds to wait before the next poll, given what is left of the budget. |
wait_for_reset |
The seconds a watch waits for a spent budget: until it returns, and a margin. |
follow |
Poll read until it answers: the one wait on the forge. |
elapsed_label |
seconds as a person reads a wait: |
classify |
One reading of the branch, named and coded. |
follow_pull_request |
Watch until a terminal verdict, or raise SystemExit with its code. |
Attributes:
| Name | Type | Description |
|---|---|---|
EXIT_CONFLICTS |
|
|
EXIT_DISARMED |
|
|
EXIT_CLOSED |
|
|
EXIT_CI_FAILED |
|
|
EXIT_TIMEOUT |
|
|
EXIT_UNREACHABLE |
|
|
EXIT_STALLED |
|
|
EXIT_BEHIND |
|
|
EXIT_PENDING |
|
|
LOW_BUDGET |
|
|
REQUESTS_PER_POLL |
|
|
UNSAID_RESET |
|
Pace ¶
A watch's waits between polls of the forge.
The interval while the API budget is ample; slower while it is low (livery.workshop._verdict.paced), said once; and a spent budget waited out until it returns, said with the forge's own refusal.
Pace polls interval seconds apart while the budget allows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
interval
|
float
|
Seconds between polls while the budget is ample. |
required |
sleep
|
Callable[[float], None] | None
|
What waits; |
None
|
Methods:
| Name | Description |
|---|---|
rest |
Sleep until the next poll, slowed while repo's forge budget is low. |
wait_out |
Sleep until a spent budget returns; the seconds waited. |
Attributes:
| Name | Type | Description |
|---|---|---|
interval |
|
Source code in packages/workshop/src/livery/workshop/_verdict.py
rest ¶
rest(repo: Repository) -> None
Sleep until the next poll, slowed while repo's forge budget is low.
Source code in packages/workshop/src/livery/workshop/_verdict.py
wait_out ¶
wait_out(error: RateLimited) -> float
Sleep until a spent budget returns; the seconds waited.
A caller with a deadline moves it by the wait: the forge's budget, not the work being watched, took the time.
Source code in packages/workshop/src/livery/workshop/_verdict.py
Transient ¶
A bounded run of unreadable polls: each printed once, the budget ends it.
A transport error during a poll is a retry, not a verdict: the
server dropped a connection, answered 5xx, or timed out, and the
next poll may answer. note prints the error with its place in
the run and returns True when the run has reached the budget;
reset is the answered poll that ends the run. giving_up is
the last line a watcher prints before exiting 15.
Attributes:
| Name | Type | Description |
|---|---|---|
budget |
The consecutive failures the watcher tolerates. |
|
interval |
The seconds between polls, for the line that says how long the forge was unreachable. |
|
count |
The failures in the current run. |
|
last |
The last error's words. |
Methods:
| Name | Description |
|---|---|
note |
Print error as one failure of the run; True when the run is spent. |
reset |
An answered poll ends the run. |
giving_up |
The line for a spent budget: how long, the last error, and subject. |
Source code in packages/workshop/src/livery/workshop/_verdict.py
note ¶
Print error as one failure of the run; True when the run is spent.
Source code in packages/workshop/src/livery/workshop/_verdict.py
reset ¶
giving_up ¶
The line for a spent budget: how long, the last error, and subject.
Source code in packages/workshop/src/livery/workshop/_verdict.py
Pending
dataclass
¶
What one poll answers while the thing followed is not there yet.
Attributes:
| Name | Type | Description |
|---|---|---|
line |
str
|
The line the follow prints when the state changes, and again at its quiet cadence while the state holds; empty prints nothing. |
key |
str
|
What tells one pending state from another; the line when empty. |
FollowTimedOut ¶
Bases: Exception
A follow reached its deadline with the thing followed still pending.
Attributes:
| Name | Type | Description |
|---|---|---|
subject |
What was followed, in the caller's words. |
|
timeout |
The seconds the follow waited. |
|
last |
The last pending answer, for the caller's own line. |
Source code in packages/workshop/src/livery/workshop/_verdict.py
ForgeUnreachable ¶
Bases: Exception
A follow spent its transient budget on unreadable polls.
Attributes:
| Name | Type | Description |
|---|---|---|
line |
The giving-up line, how long and the last error, for the caller to print before it exits 15 or fails. |
|
error |
The last error. |
Source code in packages/workshop/src/livery/workshop/_verdict.py
Verdict
dataclass
¶
One reading of where a branch's pull request stands.
Attributes:
| Name | Type | Description |
|---|---|---|
state |
str
|
A short name: |
exit_code |
int
|
The stable code for the state; 0 when nothing is
wrong ( |
detail |
str
|
One sentence for a person, naming the evidence. |
pr_number |
int
|
The pull request, when one exists. |
JobWatch ¶
The jobs of a head's runs, reported as they move, each line stamped.
Each report reads every run for the head and the jobs of each, prints one line per job whose status or conclusion changed since the last report, and under a job that just failed the log's failure lines, when the forge already has the log. A report that finds nothing moved prints nothing. Every line opens with the time since the watch began, so a log read later shows where the minutes went; clock is the seam a test hands a clock of its own to.
Methods:
| Name | Description |
|---|---|
stamp |
The elapsed time since the watch began, padded for a line's head. |
report |
Print and return the lines for what moved since the last report. |
Attributes:
| Name | Type | Description |
|---|---|---|
seen |
dict[tuple[str, str], str]
|
|
Source code in packages/workshop/src/livery/workshop/_verdict.py
report ¶
report(repo: Repository, head_sha: str) -> list[str]
Print and return the lines for what moved since the last report.
Source code in packages/workshop/src/livery/workshop/_verdict.py
paced ¶
paced(interval: float, budget: RateBudget | None, *, now: float) -> float
The seconds to wait before the next poll, given what is left of the budget.
interval while the budget is ample or unknown. Below [livery.workshop._verdict.LOW_BUDGET] of it, the polls left are spread over the time until it renews, so the watch never spends it.
Source code in packages/workshop/src/livery/workshop/_verdict.py
wait_for_reset ¶
wait_for_reset(error: RateLimited, *, now: float) -> float
The seconds a watch waits for a spent budget: until it returns, and a margin.
Source code in packages/workshop/src/livery/workshop/_verdict.py
follow ¶
follow(repo: Repository | None, read: Callable[[], _T | Pending], *, subject: str | Callable[[], str], interval: float = 15, timeout: float | None = 1800, quiet: float | None = 60, transient: Transient | None = None, retried: tuple[type[Exception], ...] = (ForgeError,), clock: Callable[[], float] | None = None, sleep: Callable[[float], None] | None = None) -> _T
Poll read until it answers: the one wait on the forge.
read returns the answer, or a livery.workshop._verdict.Pending
while there is none yet. The follow prints a pending line when its
state changes and again every quiet seconds while it holds
(None prints on change alone), rests interval seconds between
polls, slower while repo's API budget is low, and waits out a
spent budget, moving the deadline by the wait. An error of a
retried type is a retry within transient's budget; a run of
them that spends it raises
livery.workshop._verdict.ForgeUnreachable with the giving-up
line. The deadline, timeout seconds from the start, raises
livery.workshop._verdict.FollowTimedOut; None waits as long
as the caller's own timeout allows. Without a repo the rests are
plain sleeps. The deadline and the quiet cadence read clock, and
every wait goes through sleep, so a caller that passes both
decides how much time each poll takes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repo
|
Repository | None
|
The repository polled, for its rate budget; None for a wait on something that is not a forge. |
required |
read
|
Callable[[], _T | Pending]
|
One poll: the answer, or a pending state. |
required |
subject
|
str | Callable[[], str]
|
What is followed, for the giving-up and timeout lines; a callable is asked only when a line needs it. |
required |
interval
|
float
|
Seconds between polls. |
15
|
timeout
|
float | None
|
Seconds until the follow gives up, or None for none. |
1800
|
quiet
|
float | None
|
Seconds after which a held pending line prints again. |
60
|
transient
|
Transient | None
|
The budget for unreadable polls; a fresh one at interval when None, shared across calls when given. |
None
|
retried
|
tuple[type[Exception], ...]
|
The exception types a poll may raise and be retried. |
(ForgeError,)
|
clock
|
Callable[[], float] | None
|
Seconds from a fixed start; |
None
|
sleep
|
Callable[[float], None] | None
|
What waits between polls; |
None
|
Returns:
| Type | Description |
|---|---|
_T
|
What read answered. |
Raises:
| Type | Description |
|---|---|
FollowTimedOut
|
The deadline passed with read still pending. |
ForgeUnreachable
|
read raised a retried error past the budget. |
Source code in packages/workshop/src/livery/workshop/_verdict.py
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 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 | |
elapsed_label ¶
seconds as a person reads a wait: 37s, 4m12s, 1h02m.
Source code in packages/workshop/src/livery/workshop/_verdict.py
classify ¶
classify(repo: Repository, branch: str, root: Path, *, grace_spent: bool = False) -> Verdict
One reading of the branch, named and coded.
grace_spent is the watcher's signal that a green-and-armed pull request has already been given time to merge, so the local probes (behind, conflicts) may now decide between 10, 16, and 17. A single un-watched read never reports 16: the server may simply not have evaluated yet.
Source code in packages/workshop/src/livery/workshop/_verdict.py
520 521 522 523 524 525 526 527 528 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 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 | |
follow_pull_request ¶
follow_pull_request(repo: Repository, branch: str, root: Path, *, interval: float = 15, timeout: float = 1800, clock: Callable[[], float] | None = None, sleep: Callable[[float], None] | None = None) -> Verdict
Watch until a terminal verdict, or raise SystemExit with its code.
Returns the merged verdict on success, or awaiting-approvals
once the arm holds and a review is what happens next. Every job's
status change prints as a line of its own as it happens
(livery.workshop._verdict.JobWatch), and a job that fails
prints its failure lines under its name. Every terminal blocker
(10-13, 16, 17) raises SystemExit carrying its code, after printing
the detail; the deadline raises 14; a forge unreachable past the
transient budget raises 15, naming the last error and the pull
request. The polls, the transient budget, the API budget, and the
clock and sleep the deadline and the waits use are
livery.workshop._verdict.follow's.
Source code in packages/workshop/src/livery/workshop/_verdict.py
732 733 734 735 736 737 738 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 | |