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

```sh
uv add sailfork       # in a uv project
pip install sailfork  # anywhere else
```

```python
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](https://sailfork.com/docs/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.

```python
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:

```python
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

| Page | What it covers |
| --- | --- |
| [Client and sign-in](https://sailfork.com/docs/sdk-python-client) | Constructor arguments, how the token and host are found, closing the client, headers. |
| [Operations and types](https://sailfork.com/docs/sdk-python-calls) | Method names, keyword arguments, the pydantic models, paging and live events. |
| [Handles](https://sailfork.com/docs/sdk-python-handles) | `Repo`, `Org`, `PullRequest` and `Caisson`, and the methods that return the next one. |
| [Agent workflow](https://sailfork.com/docs/sdk-python-workflow) | An issue taken through a caisson, a pull request and a merge, sync and async. |
| [Held writes and waits](https://sailfork.com/docs/sdk-python-held-and-waits) | `Done` and `Held`, and `sf.wait`. |
| [Errors and retries](https://sailfork.com/docs/sdk-python-errors) | Every exception, the retry rules and idempotency. |
| [Tools for models](https://sailfork.com/docs/sdk-python-tools) | Tool definitions for Anthropic and OpenAI, and `run`. |
| [Testing](https://sailfork.com/docs/sdk-python-testing) | Answering from `httpx.MockTransport`. |

Every method is listed in the [SDK reference](https://sailfork.com/docs/sdk-reference), and the two-language overview is [SDKs for TypeScript and Python](https://sailfork.com/docs/sdk).

---

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