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