Skip to content

Python held writes and waits

How a write that needs a person comes back as Done or Held, and how sf.wait holds until checks finish, a pull request merges or a request is decided.

An organization can hold some writes for a person, and some things take longer than one request. This page covers the two result types for held writes, and sf.wait for everything that takes time.

Writes a person must approve

Two methods can be held by an organization's agent permissions: pulls.merge and pulls.auto_merge_enable, on the client and on PullRequest. They return Done or Held and never both. The SDK reference marks them "can be held".

ResultFields
Donestatus is "done"; value is the model the method would have returned (Pull, or AutoMerge).
Heldstatus is "held"; held is the request's id; url is the full address where a person approves it; message says why it waits; kind (such as merge) and summary (a one-line description) are None when the server sends none.

Both are frozen dataclasses exported from sailfork. Check status or use isinstance.

from sailfork import Done, Held, Sailfork

with Sailfork() as sf:
    merge = sf.repo("acme/api").pull(128).merge()

    if merge.status == "held":
        print(merge.url)          # hand this to a person
        print(merge.message)
        print(merge.held, merge.kind, merge.summary)
    elif isinstance(merge, Done):
        print(merge.value.state)  # merged

url is made absolute against the client's host, so it opens as it is. Hand it to the person, wait for the request to be decided (below) and call the method again. A person who declines makes the next call raise HeldDeclinedError.

from sailfork import Held, HeldDeclinedError

pr = sf.repo("acme/api").pull(128)
merge = pr.merge(method="squash")

if isinstance(merge, Held):
    answer = sf.wait({"kind": "held", "owner": "acme", "id": merge.held}, timeout=3600)
    if answer.met:
        try:
            merge = pr.merge(method="squash")
        except HeldDeclinedError as err:
            print("declined:", err)

The writes waiting for you to decide are sf.held.mine(), and an organization's are sf.org("acme").held.org(). Each answers with pending and decided lists of requests with id, kind, summary, actor, org, repo and approved.

Caisson writes

A caisson write can also be held, when a path rule says ask (see Writes held for a person). Those methods are not declared as holdable, so a caisson.batch or caisson.patch answered with 202 raises UnexpectedHeldError, exported from sailfork, with status == 202 and code == "held". The server's answer is in err.body, with err.body["url"] the address for the person.

from sailfork import UnexpectedHeldError

try:
    caisson.batch(changes=[{"path": "infra/prod.tf", "content": text}])
except UnexpectedHeldError as err:
    print("waiting for a person:", err.body["url"])

Wait for a change

sf.wait(target, until=None, timeout=600) holds until something reaches a state, and answers with a WaitAnswer. target is a dict with a kind:

kindOther keysuntil
pullowner, repo, numberchecks, merged or reviewed
runowner, repo, idleave it out: the wait ends when the run does
caissonowner, idthe state to reach: editing, waiting, review, merged or stopped
issueowner, repo, numberopen, closed or a status such as in-review
heldowner (the organization), idleave it out: the wait ends when a person decides

timeout is the total number of seconds to wait. The server holds each request for at most 55 seconds, so the client asks again, window after window, and carries the baseline a reviewed wait needs between them, until the answer is final or timeout has passed. A window that fails with a retryable error is retried like any read.

answer = sf.wait(
    {"kind": "pull", "owner": "acme", "repo": "api", "number": 128},
    until="checks",
    timeout=600,
)
print(answer.state, answer.detail, answer.condition)
WaitAnswer fieldMeaning
statemet, failed, pending (the timeout passed first) or none (nothing to wait for, such as a repository without CI).
detailThe target's state in words, such as pending (1 pass, 0 fail, 0 cancelled, 2 pending).
conditionWhat was waited on, such as checks on #128.
valueWhat the server last read, or None.
baselineThe state the next window compares against, or None.

answer.met, answer.failed, answer.pending and answer.none are booleans for state. AsyncSailfork.wait is awaited. Access follows the target: a private repository you cannot read is a NotFoundError. The route is described under Wait for a change.

More ways to use it:

sf.wait({"kind": "pull", "owner": "acme", "repo": "api", "number": 128}, until="merged", timeout=1800)
sf.wait({"kind": "issue", "owner": "acme", "repo": "api", "number": 42}, until="closed")
sf.wait({"kind": "caisson", "owner": "acme", "id": "c_8f2a"}, until="merged")
sf.wait({"kind": "run", "owner": "acme", "repo": "api", "id": 1234})
answer = await sf.wait(target, until="checks", timeout=900)
if answer.pending:
    print("still running after 15 minutes")

Next to the TypeScript version of this page: TypeScript held writes and waits.

Loading Sailfork