# 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](https://sailfork.com/docs/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](https://sailfork.com/docs/sdk-reference) marks them "can be held".

| Result | Fields |
| --- | --- |
| `Done` | `status` is `"done"`; `value` is the model the method would have returned (`Pull`, or `AutoMerge`). |
| `Held` | `status` 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`.

```python
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`.

```python
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](https://sailfork.com/docs/caissons#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.

```python
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`:

| `kind` | Other keys | `until` |
| --- | --- | --- |
| `pull` | `owner`, `repo`, `number` | `checks`, `merged` or `reviewed` |
| `run` | `owner`, `repo`, `id` | leave it out: the wait ends when the run does |
| `caisson` | `owner`, `id` | the state to reach: `editing`, `waiting`, `review`, `merged` or `stopped` |
| `issue` | `owner`, `repo`, `number` | `open`, `closed` or a status such as `in-review` |
| `held` | `owner` (the organization), `id` | leave 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.

```python
answer = sf.wait(
    {"kind": "pull", "owner": "acme", "repo": "api", "number": 128},
    until="checks",
    timeout=600,
)
print(answer.state, answer.detail, answer.condition)
```

| `WaitAnswer` field | Meaning |
| --- | --- |
| `state` | `met`, `failed`, `pending` (the timeout passed first) or `none` (nothing to wait for, such as a repository without CI). |
| `detail` | The target's state in words, such as `pending (1 pass, 0 fail, 0 cancelled, 2 pending)`. |
| `condition` | What was waited on, such as `checks on #128`. |
| `value` | What the server last read, or `None`. |
| `baseline` | The 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](https://sailfork.com/docs/api-account#wait-for-a-change).

More ways to use it:

```python
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})
```

```python
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](https://sailfork.com/docs/sdk-typescript-held-and-waits).

---

Every docs page: https://sailfork.com/llms.txt
