sinatra-dev 0.1.0__py3-none-any.whl

sinatra_dev/_generated/models/ticket_search_result.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+if TYPE_CHECKING:
+    from ..models.ticket import Ticket
+    from ..models.ticket_search_result_github import TicketSearchResultGithub
+    from ..models.ticket_search_result_linear import TicketSearchResultLinear
+
+
+T = TypeVar("T", bound="TicketSearchResult")
+
+
+@_attrs_define
+class TicketSearchResult:
+    """The issues you could delegate, and how the workspace is connected to each tracker.
+
+    Attributes:
+        tickets (list[Ticket]): The issues you could delegate. Linear issues come first, then GitHub's, each with yours
+            before your team's unassigned ones.
+        linear (TicketSearchResultLinear): The workspace's Linear connection, as it applies to you.
+        github (TicketSearchResultGithub): The workspace's GitHub connection.
+    """
+
+    tickets: list[Ticket]
+    linear: TicketSearchResultLinear
+    github: TicketSearchResultGithub
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        tickets = []
+        for tickets_item_data in self.tickets:
+            tickets_item = tickets_item_data.to_dict()
+            tickets.append(tickets_item)
+
+        linear = self.linear.to_dict()
+
+        github = self.github.to_dict()
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "tickets": tickets,
+                "linear": linear,
+                "github": github,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        from ..models.ticket import Ticket
+        from ..models.ticket_search_result_github import TicketSearchResultGithub
+        from ..models.ticket_search_result_linear import TicketSearchResultLinear
+
+        d = dict(src_dict)
+        tickets = []
+        _tickets = d.pop("tickets")
+        for tickets_item_data in _tickets:
+            tickets_item = Ticket.from_dict(tickets_item_data)
+
+            tickets.append(tickets_item)
+
+        linear = TicketSearchResultLinear.from_dict(d.pop("linear"))
+
+        github = TicketSearchResultGithub.from_dict(d.pop("github"))
+
+        ticket_search_result = cls(
+            tickets=tickets,
+            linear=linear,
+            github=github,
+        )
+
+        ticket_search_result.additional_properties = d
+        return ticket_search_result
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

sinatra_dev/_generated/models/ticket_search_result_github.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Self, TypeVar, cast
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+T = TypeVar("T", bound="TicketSearchResultGithub")
+
+
+@_attrs_define
+class TicketSearchResultGithub:
+    """The workspace's GitHub connection.
+
+    Attributes:
+        connected (bool): Whether the workspace is connected to GitHub.
+        repo (None | str): The repository the GitHub search covered, when the `repo` query matched an enabled one and
+            had open issues. Otherwise `null`.
+    """
+
+    connected: bool
+    repo: None | str
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        connected = self.connected
+
+        repo: None | str
+        repo = self.repo
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "connected": connected,
+                "repo": repo,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        d = dict(src_dict)
+        connected = d.pop("connected")
+
+        def _parse_repo(data: object) -> None | str:
+            if data is None:
+                return data
+            return cast(None | str, data)
+
+        repo = _parse_repo(d.pop("repo"))
+
+        ticket_search_result_github = cls(
+            connected=connected,
+            repo=repo,
+        )
+
+        ticket_search_result_github.additional_properties = d
+        return ticket_search_result_github
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

sinatra_dev/_generated/models/ticket_search_result_linear.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Self, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+T = TypeVar("T", bound="TicketSearchResultLinear")
+
+
+@_attrs_define
+class TicketSearchResultLinear:
+    """The workspace's Linear connection, as it applies to you.
+
+    Attributes:
+        connected (bool): Whether the workspace is connected to Linear.
+        identity_linked (bool): Whether your Linear account is linked in this workspace. Linear issues are listed only
+            when it is.
+        identity_bound (bool): Whether your Linear identity is tied to your Sinatra user.
+    """
+
+    connected: bool
+    identity_linked: bool
+    identity_bound: bool
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        connected = self.connected
+
+        identity_linked = self.identity_linked
+
+        identity_bound = self.identity_bound
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "connected": connected,
+                "identityLinked": identity_linked,
+                "identityBound": identity_bound,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        d = dict(src_dict)
+        connected = d.pop("connected")
+
+        identity_linked = d.pop("identityLinked")
+
+        identity_bound = d.pop("identityBound")
+
+        ticket_search_result_linear = cls(
+            connected=connected,
+            identity_linked=identity_linked,
+            identity_bound=identity_bound,
+        )
+
+        ticket_search_result_linear.additional_properties = d
+        return ticket_search_result_linear
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

sinatra_dev/_generated/models/workspace.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Self, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+T = TypeVar("T", bound="Workspace")
+
+
+@_attrs_define
+class Workspace:
+    """A workspace you belong to.
+
+    Attributes:
+        id (str): The workspace's id. Use it as `workspaceId` in the workspace endpoints.
+        name (str): The workspace's name.
+        role (str): Your role in it: `owner`, `admin` or `member`. New roles can appear.
+    """
+
+    id: str
+    name: str
+    role: str
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        id = self.id
+
+        name = self.name
+
+        role = self.role
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "id": id,
+                "name": name,
+                "role": role,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        d = dict(src_dict)
+        id = d.pop("id")
+
+        name = d.pop("name")
+
+        role = d.pop("role")
+
+        workspace = cls(
+            id=id,
+            name=name,
+            role=role,
+        )
+
+        workspace.additional_properties = d
+        return workspace
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

sinatra_dev/_generated/types.py

@@ -0,0 +1,54 @@
+"""Contains some shared types for properties"""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import IO, BinaryIO, Generic, Literal, TypeVar
+
+from attrs import define
+
+
+class Unset:
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = IO[bytes] | bytes | str
+FileTypes = (
+    # (filename, file (or bytes), content_type)
+    tuple[str | None, FileContent, str | None]
+    # (filename, file (or bytes), content_type, headers)
+    | tuple[str | None, FileContent, str | None, Mapping[str, str]]
+)
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads"""
+
+    payload: BinaryIO
+    file_name: str | None = None
+    mime_type: str | None = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data"""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response(Generic[T]):
+    """A response from an endpoint"""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: T | None
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

sinatra_dev/_retry.py

@@ -0,0 +1,72 @@
+"""When a request is retried, and how long the client waits first."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from datetime import UTC
+from email.utils import parsedate_to_datetime
+
+import httpx
+
+MAX_RETRIES = 3
+"""At most this many retries after the first attempt."""
+BACKOFF_SECONDS = 0.5
+"""The first ``503`` backoff; it doubles on each retry (0.5s, 1s, 2s)."""
+MAX_RETRY_AFTER_SECONDS = 60.0
+"""A ``Retry-After`` longer than this is cut to it."""
+
+RETRY_IDEMPOTENT = frozenset({429, 503})
+"""GETs, DELETE, and POSTs that carry an ``Idempotency-Key``."""
+RETRY_UNAVAILABLE = frozenset({503})
+"""``tasks.stop``: a stop is safe to repeat after a ``503``, but not after a ``429``."""
+RETRY_NEVER: frozenset[int] = frozenset()
+"""POSTs without an ``Idempotency-Key``: never retried."""
+
+# The tests replace this with a fake clock.
+sleep: Callable[[float], None] = time.sleep
+
+
+def with_retries(retry_on: frozenset[int], attempt: Callable[[], httpx.Response]) -> httpx.Response:
+    """Sends ``attempt()`` until it succeeds, fails with a status ``retry_on``
+    doesn't cover, or runs out of retries, and returns the last response.
+
+    Every attempt must send the same request: callers compute the
+    ``Idempotency-Key`` once, outside ``attempt``. Exceptions (network errors,
+    timeouts) are never retried.
+    """
+    retry = 0
+    while True:
+        response = attempt()
+        if response.is_success or retry >= MAX_RETRIES or response.status_code not in retry_on:
+            return response
+        sleep(retry_delay(response, retry))
+        retry += 1
+
+
+def retry_delay(response: httpx.Response, retry: int) -> float:
+    if response.status_code == 429:
+        after = parse_retry_after(response.headers.get("retry-after"))
+        if after is not None:
+            return min(after, MAX_RETRY_AFTER_SECONDS)
+    return float(BACKOFF_SECONDS * 2**retry)
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """``Retry-After`` is either seconds or an HTTP date. Returns seconds."""
+    if value is None or not value.strip():
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        pass
+    else:
+        return max(0.0, seconds) if math.isfinite(seconds) else None
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:  # "-0000": HTTP dates are always GMT
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, when.timestamp() - time.time())

sinatra_dev-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: sinatra-dev
+Version: 0.1.0
+Summary: Python client for the Sinatra API: start, follow and stop Sinatra tasks, and delegate Linear and GitHub issues.
+Project-URL: Homepage, https://sinatra.dev
+Project-URL: Documentation, https://docs.sinatra.dev/docs/api-reference
+Project-URL: Repository, https://github.com/sinatra-dev/sinatra-python
+Project-URL: Issues, https://github.com/sinatra-dev/sinatra-python/issues
+Author-email: Sinatra <contact@sinatra.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,coding-agent,sdk,sinatra,sinatra.dev
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.1
+Description-Content-Type: text/markdown
+
+# sinatra-dev
+
+A Python client for the [Sinatra API](https://docs.sinatra.dev/docs/api-reference): start, follow and stop Sinatra tasks, and delegate Linear and GitHub issues.
+
+It runs on Python 3.11 and later, is typed (`py.typed`), and depends only on `httpx` and `attrs`. The client is generated from the API's [OpenAPI spec](https://api.sinatra.dev/openapi.json) and released automatically when the spec changes.
+
+## Install
+
+```sh
+pip install sinatra-dev
+```
+
+## Quick start
+
+```python
+import time
+
+from sinatra_dev import Sinatra
+
+# The turn is done when the task leaves these statuses (for example, it reaches replied or pr_open).
+WORKING = {"pending", "investigating", "implementing", "rework"}
+
+with Sinatra() as sinatra:  # reads SINATRA_TOKEN
+    me = sinatra.me.get()
+    if not me.workspaces:
+        raise SystemExit("The token's user isn't in any workspace yet.")
+    workspace = me.workspaces[0]
+
+    task = sinatra.tasks.create(
+        workspace.id, "Fix the flaky login test", repo="acme/web", idempotency_key="fix-flaky-login-1"
+    ).task
+
+    after = None
+    while True:
+        status = sinatra.tasks.get(workspace.id, task.id).status
+        for m in sinatra.messages.list_all(workspace.id, task.id, after=after):
+            print(f"{m.role}: {m.body}")
+            after = m.id
+        if status not in WORKING:
+            break
+        time.sleep(3)
+    print(f"Task {task.id} is {status}.")
+```
+
+The API has no streaming. To wait for a reply, read the conversation after the last entry you've seen, and check the task's `status`: the agent posts one reply per turn, and the turn is done when the task stops working. The loop reads the status before the conversation, so it never stops before printing the reply that ended the turn. An unknown status counts as done, so the loop can't wait forever on a status added after this was written. See [How replies work](https://docs.sinatra.dev/docs/cli-and-api#how-replies-work).
+
+## Authentication
+
+Create a personal access token on the [Access tokens](https://app.sinatra.dev/tokens) page (**CLI & API** in the dashboard). It starts with `sntr_` and acts as you in every workspace you belong to. The client reads it from the `SINATRA_TOKEN` environment variable, or you can pass it:
+
+```python
+sinatra = Sinatra(token=os.environ["MY_TOKEN"])
+```
+
+The constructor raises `ValueError` if it finds no token. Other options:
+
+- `base_url`: defaults to `https://api.sinatra.dev`.
+- `timeout`: seconds each attempt may wait to connect, and for each chunk of the response, before httpx raises `httpx.TimeoutException`. Defaults to 60; `None` turns it off. An `httpx.Timeout` works too.
+- `http_client`: an `httpx.Client` to send requests with, for example one with a proxy. The client doesn't close it.
+
+Every method takes a `timeout` keyword that overrides the client's for that call:
+
+```python
+sinatra.tasks.get(workspace_id, task_id, timeout=5)
+```
+
+Use the client as a context manager, or call `sinatra.close()`, to release its connections.
+
+## Operations
+
+The namespaces mirror the API's operation ids:
+
+| Method | Request |
+| --- | --- |
+| `me.get()` | `GET /v1/me` |
+| `me.revoke_token()` | `DELETE /v1/me/token` |
+| `tasks.list(workspace_id, status=, limit=, cursor=)` | `GET /v1/workspaces/{workspaceId}/tasks` |
+| `tasks.get(workspace_id, task_id)` | `GET /v1/workspaces/{workspaceId}/tasks/{taskId}` |
+| `tasks.create(workspace_id, prompt, title=, repo=, idempotency_key=)` | `POST /v1/workspaces/{workspaceId}/tasks` |
+| `tasks.stop(workspace_id, task_id)` | `POST /v1/workspaces/{workspaceId}/tasks/{taskId}/stop` |
+| `messages.create(workspace_id, task_id, text, idempotency_key=)` | `POST /v1/workspaces/{workspaceId}/tasks/{taskId}/messages` |
+| `messages.list(workspace_id, task_id, after=, limit=)` | `GET /v1/workspaces/{workspaceId}/tasks/{taskId}/messages` |
+| `tickets.search(workspace_id, q=, repo=)` | `GET /v1/workspaces/{workspaceId}/tickets` |
+| `tickets.delegate(workspace_id, source="linear", id=)` or `(workspace_id, source="github", repo=, number=)` | `POST /v1/workspaces/{workspaceId}/tickets/delegate` |
+
+Responses are typed objects with snake_case attributes (`task.pull_request`, `page.next_cursor`). Fields the API added after this release are kept in each object's `additional_properties`.
+
+`tasks.list_all` and `messages.list_all` page through everything for you:
+
+```python
+for task in sinatra.tasks.list_all(workspace_id, status="pr_open"):
+    print(task.id, task.title)
+```
+
+Fields such as `status`, `source`, `role`, `kind` and the error `code` are plain strings, and the API adds new values over time. Handle values you don't recognise.
+
+## Retries and idempotency
+
+`tasks.create` and `messages.create` always send an `Idempotency-Key`. If you don't pass one, the client makes a random UUID. Every retry of a call sends the same key, so a retried start never starts a second task. Pass your own key to make a retry safe across process restarts too.
+
+The client retries a request up to 3 times when it's safe to repeat:
+
+- `429`: after the `Retry-After` the server sends, at most 60 seconds.
+- `503`: after 0.5s, then 1s, then 2s.
+
+GETs, `me.revoke_token`, `tasks.create` and `messages.create` retry on both. `tasks.stop` retries on `503` only. `tickets.delegate` takes no idempotency key and is never retried. Other errors, timeouts and network failures are never retried.
+
+## Errors
+
+An error response raises a `SinatraError`:
+
+```python
+from sinatra_dev import SinatraError
+
+try:
+    sinatra.tasks.stop(workspace_id, task_id)
+except SinatraError as err:
+    if err.code != "not_running":  # not_running: the task had already stopped
+        raise
+```
+
+| Attribute | |
+| --- | --- |
+| `status` | The HTTP status. |
+| `code` | The API's `error` code, such as `capacity_full`. `http_error` when the response carried none, such as an HTML error page from a proxy. |
+| `reason` | A sentence for a person. Don't branch on it. |
+| `request_id` | The request's id. Include it when you contact support. |
+| `body` | The response body: the parsed JSON, or the text. Refusals carry extra fields here, such as `billingUrl`. |
+| `headers` | The response headers. |
+
+Network failures and timeouts are not wrapped: they raise the `httpx.HTTPError` (for example `httpx.TimeoutException`) that httpx raised.
+
+The [API reference](https://docs.sinatra.dev/docs/api-reference) lists every operation's error codes.
+
+## Versions
+
+Releases follow semver. While the version is `0.x`, a breaking API change bumps the minor version and anything else bumps the patch. From `1.0`, breaking changes bump the major version and additions bump the minor.
+
+## Development
+
+Needs [uv](https://docs.astral.sh/uv/), and Node 24 for the contract tests.
+
+```sh
+uv sync
+bash scripts/install-oasdiff.sh   # installs the pinned oasdiff into .tools/bin
+bash scripts/generate.sh          # regenerates src/sinatra_dev/_generated from openapi.json
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                     # wrapper tests against a local stub server
+bash scripts/contract.sh          # every operation against a Prism mock of openapi.json
+PATH="$PWD/.tools/bin:$PATH" bash scripts/next-version.test.sh
+bash scripts/build.sh             # sdist and wheel in dist/, build backend pinned by hash
+```
+
+`src/sinatra_dev/_generated` is written by `openapi-python-client` and never edited by hand; CI fails if it differs from what `openapi.json` generates (`bash scripts/check-generated.sh`). `openapi.json` is updated by the release workflow. See [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT