# Python handles

Repo, Org, PullRequest and Caisson handles, in sync and async form, the ids each one binds and the methods that return the next handle.

A handle binds the ids a call would repeat, so code names the repository once. Get one from the client or from another handle, then call the same methods without those ids.

| Handle | Async twin | Get it with | Binds |
| --- | --- | --- | --- |
| `Repo` | `AsyncRepo` | `sf.repo("owner/name")` | `owner`, `repo` |
| `Org` | `AsyncOrg` | `sf.org("handle")` | `org` |
| `PullRequest` | `AsyncPullRequest` | `repo.pull(n)`, `repo.pulls.create(...)`, `caisson.ship(...)` | `owner`, `repo`, `number` |
| `Caisson` | `AsyncCaisson` | `repo.caisson(id)`, `repo.issues.start(n)` | `owner`, `repo`, `id` |

The async twins have the same methods as coroutines. `sf.repo` raises `ValueError` for a name that is not `owner/name`. The handle classes are importable from `sailfork._generated.api`, though code seldom needs the names.

## Repo

`sf.repo("acme/api")` fills in `owner` and `repo` on everything under it.

| Attribute | Methods |
| --- | --- |
| `repo.issues` | `create`, `create_batch`, `get`, `list`, `next`, `start`, `claim`, `release`, `comment`, `context`, `update`, `similar`, `subscribe`, `react`, `unreact`, `comment_react`, `comment_unreact` |
| `repo.pulls` | `create`, `list` |
| `repo.ci` | `runs`, `run`, `logs`, `step_log`, `failures`, `rerun`, `cancel`, `dispatch`, `artifacts`, `approve_pull` |
| `repo.check_runs` | `create`, `get`, `list`, `update` |
| `repo.labels`, `repo.milestones`, `repo.notes` | `create`, `list`, `update`, `delete` |
| `repo.merge_queue` | `status` |
| `repo.repos` | `get`, `update` |
| `repo.symbols` | `find`, `refs` |
| `repo.pull(number)` | a `PullRequest` |
| `repo.caisson(id)` | a `Caisson` |

```python
from sailfork import Sailfork

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

    info = repo.repos.get()
    print(info.default_branch)

    for issue in repo.issues.list(state="open", limit=10).items:
        print(issue.number, issue.title)

    failing = repo.ci.failures(1234)  # a run id
    refs = repo.symbols.refs("charge")
```

The names above are the ones on the handle. A few take a leading positional, such as `repo.issues.get(42)` and `repo.issues.claim(42, minutes=30)`.

## Org

`sf.org("acme")` fills in `org`, for what belongs to the owner rather than one repository.

| Attribute | Methods |
| --- | --- |
| `org.caissons` | `list`, `open`, `policy` |
| `org.held` | `org`, which lists the organization's held agent requests |
| `org.sandboxes` | `create`, `list` |

```python
org = sf.org("acme")

policy = org.caissons.policy()
live = org.caissons.list(state="editing", limit=20)

caisson = org.caissons.open(
    repo="api",
    title="Round charges",
    scope=["src/charge.py"],
)
print(caisson.id, caisson.branch)

print(len(org.held.org().pending))
```

`org.caissons.open` answers with the caisson model. To get a `Caisson` handle, wrap its id with `sf.repo("acme/api").caisson(caisson.id)`.

## PullRequest

A pull request handle fills in `owner`, `repo` and `number`.

| Method | What it does |
| --- | --- |
| `get()` | The pull request with its threads, mergeability and blockers. |
| `checks(waited=None)` | The checks on its head commit and their state. |
| `comment(body=, ...)` | Start a thread or reply to one, on a line when `path` and `line` are given. |
| `review(verdict=, body=, comments=)` | Approve, request changes or comment. |
| `update(...)` | Change the title, body, state, reviewer, lock or base. |
| `merge(method=, delete_branch=, expected_head=)` | Merge it. Returns `Done` or `Held`. |
| `auto_merge_enable(...)`, `auto_merge_disable()`, `auto_merge()` | Merge when checks pass. |
| `stack()` | The pull requests stacked on and under this one. |
| `update_branch()` | Bring the branch up to date with its base. |
| `resolve_thread(thread=, resolved=)`, `edit_comment`, `delete_comment`, `hide_comment` | Manage threads and comments. |
| `dismiss()`, `approve_pull()` | Dismiss a review, approve a pull request's CI. |

```python
pr = sf.repo("acme/api").pull(128)

detail = pr.get()
print(detail.title, detail.mergeable, detail.merge_blockers)

checks = pr.checks()
print(checks.state, checks.pass_, checks.fail, checks.pending)

pr.review(verdict="approve", body="Looks right.")

merge = pr.merge(method="squash", delete_branch=True)
```

## Caisson

A caisson is a server-side worktree on a branch. The handle binds its id, its repository and the owner it sits under, so its methods take no `org`. They read and change files, run code, and hand the work over. Calls on the unbound `sf.caissons.*` resource still take `org=`.

| Method | What it does |
| --- | --- |
| `get()` | The caisson with its diff, commits and session log. |
| `read(paths=[...])` | Read several files, with uncommitted edits applied. |
| `glob(pattern=)`, `grep(pattern=)` | Find files and search their contents. |
| `symbols(q)`, `symbol_refs(name)` | Find definitions and references. |
| `batch(changes=[...])` | Apply edits, writes, deletes, moves and restores all together or not at all. |
| `patch(diff=)` | Apply a unified diff all together or not at all. |
| `diff()` | The changes, file by file, against the base. |
| `commit(message=)` | Commit the pending changes to the branch. |
| `ship(message=, closes=, refs=)` | Commit and open the pull request. Returns a `PullRequest`. |
| `pull()` | Open a pull request from the branch. |
| `bash(script=)`, `test(command=)` | Run a script or a command in a sandbox over the caisson's files. |
| `review()`, `review_submit(...)`, `review_resolve(...)`, `review_status()` | The review packet and its findings. |
| `fork()` | A new caisson starting from this one's files. |
| `stop()` | Stop it and drop uncommitted changes. |
| `affected()`, `locate()` | Which steps its changes affect; which owner its routes sit under. |

`batch` and `patch` take `dry_run=True` to answer the diffs without changing anything. A `batch` change sets exactly one of `edits`, `content`, `delete`, `moveTo` or `restore`.

```python
caisson = sf.repo("acme/api").caisson("c_8f2a")

files = caisson.read(paths=["src/charge.py"]).files
caisson.batch(
        changes=[{"path": "src/charge.py", "edits": [{"old": "int(total)", "new": "round(total)"}]}],
    dry_run=True,
)
caisson.patch(diff=open("fix.diff").read())
```

## Methods that return the next handle

Three methods answer with a handle in place of a model, so the next call needs no ids:

| Method | Returns | Bound to |
| --- | --- | --- |
| `repo.pulls.create(title=, branch=, base=)` | `PullRequest` | the new pull request |
| `repo.issues.start(number)` | `Caisson` | the caisson opened or reused for the issue |
| `caisson.ship(message=)` | `PullRequest` | the pull request the ship opened or found open |

`sf.pulls.create(owner=, repo=, ...)`, `sf.issues.start(number, owner=, repo=)` and `sf.caissons.ship(id, org=, ...)` on the client return the same handles. The handle keeps only ids. Call `pr.get()` for the pull request's fields; `number` is not an attribute of the handle.

```python
repo = sf.repo("acme/api")

pr = repo.pulls.create(title="Round charges", branch="fix/charges", base="main")
print(pr.get().number)

caisson = repo.issues.start(42)
pr = caisson.ship(message="fix(charge): round to the cent", closes=[42])
```

Next to the TypeScript version of this page: [TypeScript handles](https://sailfork.com/docs/sdk-typescript-handles).

---

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