opencode-python-sdk 0.1.0__py3-none-any.whl

opencode/_exceptions.py

@@ -0,0 +1,249 @@
+"""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):
+    status = 400
+
+
+class AuthenticationError(APIStatusError):
+    status = 401
+
+
+class PermissionDeniedError(APIStatusError):
+    status = 403
+
+
+class NotFoundError(APIStatusError):
+    status = 404
+
+
+class ConflictError(APIStatusError):
+    status = 409
+    tag = "ConflictError"
+
+
+class ContentTooLargeError(APIStatusError):
+    status = 413
+
+
+class UnprocessableEntityError(APIStatusError):
+    status = 422
+
+
+class RateLimitError(APIStatusError):
+    status = 429
+
+
+class InternalServerError(APIStatusError):
+    status = 500
+
+
+class NotImplementedServerError(InternalServerError):
+    status = 501
+
+
+class ServiceUnavailableError(InternalServerError):
+    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

opencode/_qs.py

@@ -0,0 +1,95 @@
+"""Request encoding: query strings, path segments and JSON bodies.
+
+The rules match the official TypeScript client so both send byte-identical requests:
+
+- ``None`` becomes the string ``"null"``; ``NOT_GIVEN`` leaves the parameter out;
+- booleans become ``"true"`` / ``"false"``;
+- lists repeat the key once per item;
+- objects use deep-object style, ``location[directory]=/repo``.
+"""
+
+from __future__ import annotations
+
+import base64
+import datetime as dt
+import enum
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+from urllib.parse import quote
+
+import pydantic
+
+from ._types import NotGiven
+
+__all__ = ["encode_path", "encode_path_segment", "encode_query", "to_jsonable"]
+
+
+def encode_query(params: Mapping[str, object]) -> list[tuple[str, str]]:
+    """Flattens query parameters into ordered ``(key, value)`` pairs."""
+    pairs: list[tuple[str, str]] = []
+    for key, value in params.items():
+        _append(pairs, key, to_jsonable(value))
+    return pairs
+
+
+def _append(pairs: list[tuple[str, str]], key: str, value: object) -> None:
+    if isinstance(value, NotGiven):
+        return
+    if value is None:
+        pairs.append((key, "null"))
+    elif isinstance(value, bool):
+        pairs.append((key, "true" if value else "false"))
+    elif isinstance(value, (list, tuple)):
+        for item in cast("Sequence[object]", value):
+            _append(pairs, key, item)
+    elif isinstance(value, dict):
+        for child, item in cast("dict[str, object]", value).items():
+            _append(pairs, f"{key}[{child}]", item)
+    else:
+        pairs.append((key, str(value)))
+
+
+def encode_path_segment(value: object) -> str:
+    """Encodes one path parameter, escaping ``/`` and every other reserved character.
+
+    ``.`` and ``..`` are percent-encoded too, so URL normalization cannot turn a parameter into a different route.
+    """
+    text = str(value)
+    if text == "":
+        raise ValueError("Path parameters must not be empty")
+    return _encode_part(text)
+
+
+def encode_path(value: str) -> str:
+    """Encodes a trailing wildcard path, keeping ``/`` separators and encoding dot segments."""
+    return "/".join(_encode_part(part) for part in value.split("/"))
+
+
+def _encode_part(part: str) -> str:
+    if part in (".", ".."):
+        return part.replace(".", "%2E")
+    return quote(part, safe="")
+
+
+def to_jsonable(value: Any) -> Any:
+    """Converts models and standard containers to plain JSON values, dropping ``NOT_GIVEN`` entries."""
+    if isinstance(value, pydantic.BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    if isinstance(value, NotGiven) or value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, Mapping):
+        mapping = cast("Mapping[object, object]", value)
+        return {str(key): to_jsonable(item) for key, item in mapping.items() if not isinstance(item, NotGiven)}
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return base64.b64encode(bytes(cast("bytes", value))).decode("ascii")
+    if isinstance(value, Sequence):
+        return [to_jsonable(item) for item in cast("Sequence[object]", value)]
+    if isinstance(value, (set, frozenset)):
+        return [to_jsonable(item) for item in cast("set[object]", value)]
+    if isinstance(value, enum.Enum):
+        return to_jsonable(value.value)
+    if isinstance(value, (dt.datetime, dt.date)):
+        return value.isoformat()
+    value_type: Any = value.__class__
+    adapter: pydantic.TypeAdapter[Any] = pydantic.TypeAdapter(value_type)
+    return adapter.dump_python(value, mode="json", by_alias=True)

opencode/_resource.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._types import NotGiven
+
+if TYPE_CHECKING:
+    from ._client import AsyncOpencode, Opencode
+
+__all__ = ["AsyncAPIResource", "SyncAPIResource"]
+
+
+class SyncAPIResource:
+    """Base class for generated resource groups of the sync client."""
+
+    _client: Opencode
+
+    def __init__(self, client: Opencode) -> None:
+        self._client = client
+
+    def _location(self, location: object) -> object:
+        """Falls back to the client's ``directory`` for endpoints that take a ``location``."""
+        return _default_location(location, self._client.directory)
+
+
+class AsyncAPIResource:
+    """Base class for generated resource groups of the async client."""
+
+    _client: AsyncOpencode
+
+    def __init__(self, client: AsyncOpencode) -> None:
+        self._client = client
+
+    def _location(self, location: object) -> object:
+        """Falls back to the client's ``directory`` for endpoints that take a ``location``."""
+        return _default_location(location, self._client.directory)
+
+
+def _default_location(location: object, directory: str | None) -> object:
+    if isinstance(location, NotGiven) and directory is not None:
+        return {"directory": directory}
+    return location