Skip to content

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.

HandleAsync twinGet it withBinds
RepoAsyncReposf.repo("owner/name")owner, repo
OrgAsyncOrgsf.org("handle")org
PullRequestAsyncPullRequestrepo.pull(n), repo.pulls.create(...), caisson.ship(...)owner, repo, number
CaissonAsyncCaissonrepo.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.

AttributeMethods
repo.issuescreate, create_batch, get, list, next, start, claim, release, comment, context, update, similar, subscribe, react, unreact, comment_react, comment_unreact
repo.pullscreate, list
repo.ciruns, run, logs, step_log, failures, rerun, cancel, dispatch, artifacts, approve_pull
repo.check_runscreate, get, list, update
repo.labels, repo.milestones, repo.notescreate, list, update, delete
repo.merge_queuestatus
repo.reposget, update
repo.symbolsfind, 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.

AttributeMethods
org.caissonslist, open, policy
org.heldorg, which lists the organization's held agent requests
org.sandboxescreate, 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.

MethodWhat 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_commentManage 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=.

MethodWhat 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:

MethodReturnsBound to
repo.pulls.create(title=, branch=, base=)PullRequestthe new pull request
repo.issues.start(number)Caissonthe caisson opened or reused for the issue
caisson.ship(message=)PullRequestthe 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.

Loading Sailfork