Skip to content

Python SDK

Install the sailfork package, make a first call from sync or async code, and find the page for clients, handles, waits, errors, tools and tests.

The Python SDK is generated from the same operation catalog as the REST API, the CLI and the MCP server, so a method here does what the command and the tool of the same name do. It has a synchronous client and an asyncio client with the same methods, and returns pydantic models.

Install and requirements

The package needs Python 3.11 or later. It depends on httpx and pydantic v2, and ships type hints.

uv add sailfork       # in a uv project
pip install sailfork  # anywhere else
import sailfork

print(sailfork.__version__)

The CLI is optional. If it is installed and signed in, the client uses its token when it finds none of its own. Create a token with the scopes your code needs on Access tokens.

A first call

The client finds its token and host on its own. This reads the writes waiting for a person, then lists a repository's open pull requests.

from sailfork import Sailfork

with Sailfork() as sf:
    for request in sf.held.mine().pending:
        print(request.summary)

    page = sf.repo("acme/api").pulls.list(state="open", limit=5)
    for pull in page.items:
        print(pull.number, pull.title)

The same thing with asyncio:

import asyncio

from sailfork import AsyncSailfork


async def main() -> None:
    async with AsyncSailfork() as sf:
        page = await sf.repo("acme/api").pulls.list(state="open", limit=5)
        for pull in page.items:
            print(pull.number, pull.title)


asyncio.run(main())

In this section

PageWhat it covers
Client and sign-inConstructor arguments, how the token and host are found, closing the client, headers.
Operations and typesMethod names, keyword arguments, the pydantic models, paging and live events.
HandlesRepo, Org, PullRequest and Caisson, and the methods that return the next one.
Agent workflowAn issue taken through a caisson, a pull request and a merge, sync and async.
Held writes and waitsDone and Held, and sf.wait.
Errors and retriesEvery exception, the retry rules and idempotency.
Tools for modelsTool definitions for Anthropic and OpenAI, and run.
TestingAnswering from httpx.MockTransport.

Every method is listed in the SDK reference, and the two-language overview is SDKs for TypeScript and Python.

Loading Sailfork