opencode-python-sdk 0.0.1.dev1__py3-none-any.whl

opencode/_exceptions.py

@@ -0,0 +1,271 @@
+"""Exception hierarchy.
+
+Every error raised by the client derives from :class:`OpencodeError`::
+
+    OpencodeError
+    └── APIError
+        ├── APIConnectionError
+        │   └── APITimeoutError
+        ├── APIResponseValidationError
+        └── APIStatusError
+            ├── BadRequestError            400
+            ├── AuthenticationError        401
+            ├── PermissionDeniedError      403
+            ├── NotFoundError              404
+            ├── ConflictError              409
+            ├── ContentTooLargeError       413
+            ├── UnprocessableEntityError   422
+            ├── RateLimitError             429
+            └── InternalServerError        5xx
+                ├── NotImplementedServerError  501
+                └── ServiceUnavailableError    503
+
+The server tags each declared error with a ``_tag`` such as ``"SessionNotFoundError"``. Tagged errors are raised
+as the matching subclass from :mod:`opencode._errors` (for example ``SessionNotFoundError(NotFoundError)``), so
+callers can catch a precise error or any error of that status.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar, cast
+
+import pydantic
+from typing_extensions import override
+
+if TYPE_CHECKING:
+    import httpx
+
+_M = TypeVar("_M", bound=pydantic.BaseModel)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "ContentTooLargeError",
+    "InternalServerError",
+    "NotFoundError",
+    "NotImplementedServerError",
+    "OpencodeError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "UnprocessableEntityError",
+]
+
+
+class OpencodeError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class APIError(OpencodeError):
+    """An error that happened while talking to the OpenCode server."""
+
+    message: str
+    request: httpx.Request
+    body: object | None
+    """The decoded JSON error body, the raw text when it is not JSON, or ``None``."""
+
+    def __init__(self, message: str, request: httpx.Request, *, body: object | None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+        self.body = body
+
+
+class APIConnectionError(APIError):
+    """The request could not reach the server, or the connection broke before a response arrived."""
+
+    def __init__(self, *, request: httpx.Request, message: str = "Connection error.") -> None:
+        super().__init__(message, request, body=None)
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out."""
+
+    def __init__(self, request: httpx.Request) -> None:
+        super().__init__(request=request, message="Request timed out.")
+
+
+class APIResponseValidationError(APIError):
+    """The server answered, but the response does not match the expected shape."""
+
+    response: httpx.Response
+    status_code: int
+
+    def __init__(self, response: httpx.Response, body: object | None, *, message: str | None = None) -> None:
+        super().__init__(
+            message or "The server response did not match the expected schema.", response.request, body=body
+        )
+        self.response = response
+        self.status_code = response.status_code
+
+
+class APIStatusError(APIError):
+    """The server returned a non-success HTTP status."""
+
+    status: ClassVar[int | None] = None
+    """The HTTP status this class represents, or ``None`` for the generic base."""
+
+    tag: ClassVar[str | None] = None
+    """The server ``_tag`` this class represents, or ``None`` for status-only classes."""
+
+    response: httpx.Response
+    status_code: int
+    error_tag: str | None
+    """The ``_tag`` the server sent, which can be a tag this client version does not know yet."""
+
+    def __init__(self, message: str, *, response: httpx.Response, body: object | None) -> None:
+        super().__init__(message, response.request, body=body)
+        self.response = response
+        self.status_code = response.status_code
+        self.error_tag = _string_field(body, "_tag")
+
+    def _typed_body(self, model: type[_M]) -> _M:
+        raw: object = self.body
+        body: dict[str, Any] = cast("dict[str, Any]", raw) if isinstance(raw, dict) else {}
+        try:
+            return model.model_validate(body)
+        except pydantic.ValidationError:
+            # Keep the error usable even when the body does not match this client's schema.
+            return model.model_construct(**body)
+
+    @property
+    def request_id(self) -> str | None:
+        """The server's request identifier, when it sends one."""
+        value: str | None = self.response.headers.get("x-request-id")
+        return value
+
+    @override
+    def __str__(self) -> str:
+        detail = f"{self.status_code} {self.error_tag}" if self.error_tag else str(self.status_code)
+        return f"{self.message} ({detail})"
+
+
+class BadRequestError(APIStatusError):
+    """The server rejected the request as malformed (400)."""
+
+    status = 400
+
+
+class AuthenticationError(APIStatusError):
+    """The password was missing or wrong (401)."""
+
+    status = 401
+
+
+class PermissionDeniedError(APIStatusError):
+    """The request is not allowed (403)."""
+
+    status = 403
+
+
+class NotFoundError(APIStatusError):
+    """The requested resource does not exist (404)."""
+
+    status = 404
+
+
+class ConflictError(APIStatusError):
+    """The request conflicts with the current state, for example a busy session (409)."""
+
+    status = 409
+    tag = "ConflictError"
+
+
+class ContentTooLargeError(APIStatusError):
+    """The request body is too large (413)."""
+
+    status = 413
+
+
+class UnprocessableEntityError(APIStatusError):
+    """The request was well formed but could not be processed (422)."""
+
+    status = 422
+
+
+class RateLimitError(APIStatusError):
+    """Too many requests (429). Retried automatically, honoring ``Retry-After``."""
+
+    status = 429
+
+
+class InternalServerError(APIStatusError):
+    """The server failed (500, and the base class for every 5xx)."""
+
+    status = 500
+
+
+class NotImplementedServerError(InternalServerError):
+    """The server does not implement this endpoint (501)."""
+
+    status = 501
+
+
+class ServiceUnavailableError(InternalServerError):
+    """The server is temporarily unavailable (503). Retried automatically."""
+
+    status = 503
+    tag = "ServiceUnavailableError"
+
+
+_STATUS_ERRORS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: ContentTooLargeError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+    500: InternalServerError,
+    501: NotImplementedServerError,
+    503: ServiceUnavailableError,
+}
+
+
+def status_error_class(
+    status_code: int, tag: str | None, tagged: dict[str, type[APIStatusError]]
+) -> type[APIStatusError]:
+    """Picks the most specific error class for a status code and server tag."""
+    # The tag is the server's own classification, so it wins over the status code.
+    if tag is not None and tag in tagged:
+        return tagged[tag]
+    if status_code in _STATUS_ERRORS:
+        return _STATUS_ERRORS[status_code]
+    if status_code >= 500:
+        return InternalServerError
+    return APIStatusError
+
+
+def error_message(body: object | None, status_code: int) -> str:
+    """Extracts a human-readable message from an error body."""
+    message = _string_field(body, "message")
+    if message is None and isinstance(body, dict):
+        message = _string_field(cast("dict[str, Any]", body).get("data"), "message")
+    if message:
+        return message
+    if isinstance(body, str) and body.strip():
+        return body.strip()[:500]
+    return f"Request failed with status {status_code}"
+
+
+def validation_summary(error: pydantic.ValidationError, limit: int = 5) -> str:
+    """Describes a validation failure by location and reason only, never echoing response values."""
+    issues = error.errors(include_input=False, include_url=False)
+    parts = [f"{'.'.join(str(item) for item in issue['loc']) or '<root>'}: {issue['msg']}" for issue in issues[:limit]]
+    more = f" (+{len(issues) - limit} more)" if len(issues) > limit else ""
+    return f"Response did not match the expected schema: {'; '.join(parts)}{more}"
+
+
+def _string_field(body: object | None, key: str) -> str | None:
+    if isinstance(body, dict):
+        value: object = cast("dict[str, Any]", body).get(key)
+        if isinstance(value, str):
+            return value
+    return None

opencode/_models.py

@@ -0,0 +1,54 @@
+"""Base model for every OpenCode API type."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+import pydantic
+from pydantic import ConfigDict
+from typing_extensions import override
+
+__all__ = ["BaseModel", "is_none"]
+
+
+def is_none(value: object) -> bool:
+    """Field ``exclude_if`` predicate: optional fields that are not nullable are left out instead of sent as null."""
+    return value is None
+
+
+class BaseModel(pydantic.BaseModel):
+    """Base class for OpenCode API models.
+
+    Attributes use ``snake_case`` while the wire format uses OpenCode's ``camelCase`` names. Models accept either
+    spelling on input and always serialize to the wire names.
+
+    Unknown fields are kept rather than rejected, so a client keeps working against a newer server. They are
+    available through ``model_extra`` and attribute access.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        validate_by_name=True,
+        validate_by_alias=True,
+        serialize_by_alias=True,
+        defer_build=True,
+        protected_namespaces=(),
+        use_enum_values=True,
+        coerce_numbers_to_str=False,
+    )
+
+    __opencode_always_set__: ClassVar[tuple[str, ...]] = ()
+    """Fields serialized even when left at their default, such as a union member's ``type`` tag."""
+
+    @override
+    def model_post_init(self, context: Any, /) -> None:
+        if self.__opencode_always_set__:
+            self.__pydantic_fields_set__.update(self.__opencode_always_set__)
+
+    def to_dict(self, *, exclude_unset: bool = True) -> dict[str, Any]:
+        """Returns the model as a JSON-compatible dict using wire field names."""
+        return self.model_dump(mode="json", by_alias=True, exclude_unset=exclude_unset)
+
+    def to_json(self, *, indent: int | None = None, exclude_unset: bool = True) -> str:
+        """Returns the model as JSON text using wire field names."""
+        return self.model_dump_json(by_alias=True, exclude_unset=exclude_unset, indent=indent)

opencode/_pagination.py

@@ -0,0 +1,192 @@
+"""Cursor pagination.
+
+OpenCode list endpoints return ``{"data": [...], "cursor": {"previous": ..., "next": ...}}``. A page iterates over
+every item of every following page, fetching lazily::
+
+    for message in client.message.list("ses_..."):
+        ...
+
+Use :meth:`SyncCursorPage.iter_pages` or the cursor properties for manual control.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Generator, Iterator
+
+    from ._base_client import AsyncAPIClient, RequestOptions, SyncAPIClient
+
+__all__ = ["AsyncCursorPage", "AsyncPaginator", "SyncCursorPage"]
+
+_T = TypeVar("_T")
+
+
+def _page_parts(payload: Any) -> tuple[list[Any], str | None, str | None]:
+    cursor = payload.cursor
+    return list(payload.data), getattr(cursor, "next", None), getattr(cursor, "previous", None)
+
+
+def _follow(options: RequestOptions, cursor: str) -> RequestOptions:
+    query = {key: value for key, value in options.query.items() if key != "order"}
+    # The server rejects `order` together with a cursor: the cursor already encodes the direction.
+    query["cursor"] = cursor
+    return dataclasses.replace(options, query=query)
+
+
+class _PageBase(Generic[_T]):
+    data: list[_T]
+    """Items on this page."""
+    next_cursor: str | None
+    """Cursor for the following page, or ``None`` on the last page."""
+    previous_cursor: str | None
+    """Cursor for the preceding page, or ``None`` on the first page."""
+
+    def __init__(
+        self, *, data: list[_T], next_cursor: str | None, previous_cursor: str | None, options: RequestOptions
+    ) -> None:
+        self.data = data
+        self.next_cursor = next_cursor
+        self.previous_cursor = previous_cursor
+        self._options = options
+
+    def has_next_page(self) -> bool:
+        return bool(self.next_cursor)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+
+class SyncCursorPage(_PageBase[_T]):
+    """One page of results. Iterating it walks this page and every page after it."""
+
+    def __init__(
+        self,
+        *,
+        client: SyncAPIClient,
+        data: list[_T],
+        next_cursor: str | None,
+        previous_cursor: str | None,
+        options: RequestOptions,
+        response_type: Any,
+    ) -> None:
+        super().__init__(data=data, next_cursor=next_cursor, previous_cursor=previous_cursor, options=options)
+        self._client = client
+        self._response_type = response_type
+
+    @classmethod
+    def fetch(cls, client: SyncAPIClient, options: RequestOptions, response_type: Any) -> SyncCursorPage[Any]:
+        payload = client.request(options, response_type=response_type)
+        data, next_cursor, previous_cursor = _page_parts(payload)
+        return cls(
+            client=client,
+            data=data,
+            next_cursor=next_cursor,
+            previous_cursor=previous_cursor,
+            options=options,
+            response_type=response_type,
+        )
+
+    def next_page(self) -> SyncCursorPage[_T]:
+        """Fetches the following page. Raises ``StopIteration`` on the last page."""
+        if not self.next_cursor:
+            raise StopIteration("No more pages")
+        return SyncCursorPage.fetch(self._client, _follow(self._options, self.next_cursor), self._response_type)
+
+    def previous_page(self) -> SyncCursorPage[_T]:
+        """Fetches the preceding page. Raises ``StopIteration`` on the first page."""
+        if not self.previous_cursor:
+            raise StopIteration("No previous page")
+        return SyncCursorPage.fetch(self._client, _follow(self._options, self.previous_cursor), self._response_type)
+
+    def iter_pages(self) -> Generator[SyncCursorPage[_T], None, None]:
+        """Yields this page and then each following page."""
+        page: SyncCursorPage[_T] = self
+        yield page
+        while page.has_next_page():
+            page = page.next_page()
+            yield page
+
+    def __iter__(self) -> Iterator[_T]:
+        for page in self.iter_pages():
+            yield from page.data
+
+
+class AsyncCursorPage(_PageBase[_T]):
+    """One page of results. ``async for`` walks this page and every page after it."""
+
+    def __init__(
+        self,
+        *,
+        client: AsyncAPIClient,
+        data: list[_T],
+        next_cursor: str | None,
+        previous_cursor: str | None,
+        options: RequestOptions,
+        response_type: Any,
+    ) -> None:
+        super().__init__(data=data, next_cursor=next_cursor, previous_cursor=previous_cursor, options=options)
+        self._client = client
+        self._response_type = response_type
+
+    @classmethod
+    async def fetch(cls, client: AsyncAPIClient, options: RequestOptions, response_type: Any) -> AsyncCursorPage[Any]:
+        payload = await client.request(options, response_type=response_type)
+        data, next_cursor, previous_cursor = _page_parts(payload)
+        return cls(
+            client=client,
+            data=data,
+            next_cursor=next_cursor,
+            previous_cursor=previous_cursor,
+            options=options,
+            response_type=response_type,
+        )
+
+    async def next_page(self) -> AsyncCursorPage[_T]:
+        """Fetches the following page. Raises ``StopAsyncIteration`` on the last page."""
+        if not self.next_cursor:
+            raise StopAsyncIteration("No more pages")
+        return await AsyncCursorPage.fetch(self._client, _follow(self._options, self.next_cursor), self._response_type)
+
+    async def previous_page(self) -> AsyncCursorPage[_T]:
+        """Fetches the preceding page. Raises ``StopAsyncIteration`` on the first page."""
+        if not self.previous_cursor:
+            raise StopAsyncIteration("No previous page")
+        return await AsyncCursorPage.fetch(
+            self._client, _follow(self._options, self.previous_cursor), self._response_type
+        )
+
+    async def iter_pages(self) -> AsyncIterator[AsyncCursorPage[_T]]:
+        """Yields this page and then each following page."""
+        page: AsyncCursorPage[_T] = self
+        yield page
+        while page.has_next_page():
+            page = await page.next_page()
+            yield page
+
+    async def __aiter__(self) -> AsyncIterator[_T]:
+        async for page in self.iter_pages():
+            for item in page.data:
+                yield item
+
+
+class AsyncPaginator(Generic[_T]):
+    """Returned by async list methods.
+
+    ``await`` it for the first page, or ``async for`` over it to walk every item across pages.
+    """
+
+    def __init__(self, client: AsyncAPIClient, options: RequestOptions, response_type: Any) -> None:
+        self._client = client
+        self._options = options
+        self._response_type = response_type
+
+    def __await__(self) -> Generator[Any, None, AsyncCursorPage[_T]]:
+        return AsyncCursorPage.fetch(self._client, self._options, self._response_type).__await__()
+
+    async def __aiter__(self) -> AsyncIterator[_T]:
+        page: AsyncCursorPage[_T] = await self
+        async for item in page:
+            yield item