Skip to content

Python operations and types

How catalog operations become Python methods, how results come back as pydantic models, how to page a list by hand, and how to follow live events.

Every operation in the catalog is a method on the client, grouped by area. Arguments are keywords, and results are pydantic models.

Names and arguments

An operation is a method named after its catalog id, with the verb in snake case: issues.create_batch is sf.issues.create_batch(...). Arguments are keywords in snake case (delete_branch, expected_head) and become the camel case names on the wire. A few methods take one leading positional, usually the number or id. On the client every id is a keyword; a handle supplies the ones it binds.

from sailfork import Sailfork

sf = Sailfork()

issue = sf.issues.get(42, owner="acme", repo="api")
print(issue.title)

repo = sf.repo("acme/api")
same = repo.issues.get(42)

sf.issues.comment(42, owner="acme", repo="api", body="Picking this up.")

An argument left out or set to None is not sent. A name the operation does not take, or a required one you omit, raises Python's own TypeError before any request, such as missing 1 required keyword-only argument: 'org'.

The areas on the client:

AttributeOperations
sf.issuescreate, create_batch, get, list, claim, start, next, comment, update, release, similar, subscribe, react
sf.pullscreate, get, list, merge, review, comment, checks, stack, update and more
sf.caissonsopen, list, get, read, batch, patch, ship, commit, diff, bash, test, fork, stop and more
sf.ciruns, run, logs, failures, rerun, cancel, dispatch, artifacts
sf.check_runs, sf.labels, sf.milestones, sf.notes, sf.merge_queueone resource each
sf.repos, sf.search, sf.symbolsrepositories, code search, symbol lookup
sf.sandboxescreate, list, exec and more
sf.held, sf.inbox, sf.events, sf.me, sf.tokens, sf.keys, sf.github, sf.waitsaccount and agent resources

The SDK reference lists every method with the scope it needs.

Results are pydantic models

A method returns a pydantic model, or a list of them, built from the answer. Read fields as attributes in snake case, and use pydantic to turn one back into data. Fields the server adds later are kept, so an older SDK does not lose them.

page = sf.repo("acme/api").pulls.list(state="merged", limit=1)
pull = page.items[0]

print(pull.number, pull.state, pull.head_sha)

pull.model_dump()                 # snake case keys
pull.model_dump(by_alias=True)    # the wire's camel case: headSha
pull.model_dump(mode="json")      # plain JSON types
pull.model_dump_json(indent=2)
WhereRule
Field namesSnake case: head_sha, next_cursor, created_at.
Reserved wordsPullChecks.pass_ is pass; CaissonChanged.from_ is from.
Optional fieldsPresent with the value None when the server omits them.
Unknown fieldsKept, and readable as attributes.
ListsA method that answers a list returns list[Model], as caisson.diff() does.
No bodyA method that answers 204 returns None.

The model classes live in sailfork._generated.models. The package does not re-export them, so treat that path as internal. You rarely need it: attribute access works without an import, and annotations can name the result of the method.

A few answers are plain dicts, because the catalog gives them no fixed shape. caisson.read(...).files is a list of dicts with path, oid, lines and text, or path and error for a file that could not be read.

Models as arguments

Arguments that take structured data accept plain dicts with the wire's camel case keys, or model instances. A model sends only the fields you set, under their camel case aliases, so the two forms put the same body on the wire.

caisson.batch(
    changes=[
        {"path": "src/old.py", "moveTo": "src/new.py"},
        {"path": "src/new.py", "edits": [{"insertAfter": 3, "text": "import os"}]},
    ],
)

Paging by hand

No method pages for you. A list answers one page, with next_cursor set when more follow. Pass it back as cursor, and stop when it is None.

repo = sf.repo("acme/api")
cursor = None
while True:
    page = repo.pulls.list(state="open", limit=100, cursor=cursor)
    for pull in page.items:
        print(pull.number, pull.title)
    cursor = page.next_cursor
    if cursor is None:
        break

The async version is the same loop with await on the call.

async def open_pulls(repo):
    cursor = None
    while True:
        page = await repo.pulls.list(state="open", limit=100, cursor=cursor)
        for pull in page.items:
            yield pull
        cursor = page.next_cursor
        if cursor is None:
            return

limit is 1 to 100 for pull requests and issues. A cursor works only with the filters that produced it. See Paging.

The event feed

sf.events.list(...) reads the event feed a page at a time. It takes repo, org, types, after, since, limit and number, and answers with events, cursor and more; pass cursor back as after for the next page.

feed = sf.events.list(org="acme", types="ci,mention", limit=20)
for event in feed.events:
    print(event.action, event.id)

Following events live

sf.stream_events(...) follows the live event stream and yields SSEEvent objects. AsyncSailfork.stream_events(...) does the same as an async iterator. Each event has event (the type, message when the server names none), data (the raw text), id and .json(). Keywords are the stream's query filters, such as org and types.

The loop blocks while the feed is quiet and ends only when you break out of it or the stream fails: a connection the server closes cleanly is opened again too, so the iterator does not finish by itself. When the connection drops, the stream reconnects with Last-Event-ID and resumes after the last event you got, waiting the server's retry hint or a growing pause. It gives up with the last error after max_retries failed attempts in a row. An answer that is not retryable, such as a 401, raises at once.

from sailfork import Sailfork

with Sailfork() as sf:
    for event in sf.stream_events(org="acme", types="ci,mention"):
        print(event.event, event.json())
from sailfork import AsyncSailfork


async def follow(sf: AsyncSailfork) -> None:
    async for event in sf.stream_events(org="acme", types="ci,mention"):
        print(event.event, event.json())

Next to the TypeScript version of this page: TypeScript operations and types.

Loading Sailfork