# 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](https://sailfork.com/docs/sdk-python-handles) supplies the ones it binds.

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

| Attribute | Operations |
| --- | --- |
| `sf.issues` | create, create_batch, get, list, claim, start, next, comment, update, release, similar, subscribe, react |
| `sf.pulls` | create, get, list, merge, review, comment, checks, stack, update and more |
| `sf.caissons` | open, list, get, read, batch, patch, ship, commit, diff, bash, test, fork, stop and more |
| `sf.ci` | runs, run, logs, failures, rerun, cancel, dispatch, artifacts |
| `sf.check_runs`, `sf.labels`, `sf.milestones`, `sf.notes`, `sf.merge_queue` | one resource each |
| `sf.repos`, `sf.search`, `sf.symbols` | repositories, code search, symbol lookup |
| `sf.sandboxes` | create, list, exec and more |
| `sf.held`, `sf.inbox`, `sf.events`, `sf.me`, `sf.tokens`, `sf.keys`, `sf.github`, `sf.waits` | account and agent resources |

The [SDK reference](https://sailfork.com/docs/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.

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

| Where | Rule |
| --- | --- |
| Field names | Snake case: `head_sha`, `next_cursor`, `created_at`. |
| Reserved words | `PullChecks.pass_` is `pass`; `CaissonChanged.from_` is `from`. |
| Optional fields | Present with the value `None` when the server omits them. |
| Unknown fields | Kept, and readable as attributes. |
| Lists | A method that answers a list returns `list[Model]`, as `caisson.diff()` does. |
| No body | A 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.

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

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

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

## The event feed

`sf.events.list(...)` reads the [event feed](https://sailfork.com/docs/api-account#read-events) 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.

```python
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](https://sailfork.com/docs/api-account#follow-events-live) 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.

```python
from sailfork import Sailfork

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

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

---

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