opencode-python-sdk 0.2.0__py3-none-any.whl → 0.2.3__py3-none-any.whl

opencode/__init__.py

@@ -16,6 +16,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from . import service
+from ._aiohttp import DefaultAioHttpClient
 from ._client import AsyncOpencode, Opencode
 
 # <generated:error-imports>
@@ -74,10 +76,13 @@ from ._exceptions import (
     ServiceUnavailableError,
     UnprocessableEntityError,
 )
+from ._logs import setup_logging as _setup_logging
 from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
 from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
+from ._response import APIResponse, AsyncAPIResponse
 from ._server import AsyncOpencodeServer, OpencodeServer, ServerStartError
+from ._service import Endpoint, ServiceError
 from ._streaming import AsyncStream, Stream
 from ._types import NOT_GIVEN, NotGiven
 from ._version import __version__
@@ -121,10 +126,12 @@ __all__ = [
     "API_VERSION",
     "NOT_GIVEN",
     "APIConnectionError",
+    "APIResponse",
     "APIError",
     "APIResponseValidationError",
     "APIStatusError",
     "APITimeoutError",
+    "AsyncAPIResponse",
     "AsyncCursorPage",
     "AsyncOpencode",
     "AsyncOpencodeServer",
@@ -136,6 +143,8 @@ __all__ = [
     "BaseModel",
     "ConflictError",
     "ContentTooLargeError",
+    "DefaultAioHttpClient",
+    "Endpoint",
     "InternalServerError",
     "NotFoundError",
     "NotGiven",
@@ -148,11 +157,13 @@ __all__ = [
     "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
+    "ServiceError",
     "ServiceUnavailableError",
     "Stream",
     "SyncCursorPage",
     "UnprocessableEntityError",
     "__version__",
+    "service",
     "types",
     # Shared event stream and typed plugin RPC
     "SUBSCRIBER_CAPACITY",
@@ -219,3 +230,6 @@ def __getattr__(name: str) -> Any:
 
         return importlib.import_module(".types", __name__)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+_setup_logging()

opencode/_aiohttp.py

@@ -0,0 +1,44 @@
+"""Optional aiohttp-backed HTTP client for `AsyncOpencode`.
+
+Install the extra with ``pip install 'opencode-python-sdk[aiohttp]'`` and pass the client in::
+
+    async with AsyncOpencode(http_client=DefaultAioHttpClient()) as client:
+        ...
+
+The SDK still speaks httpx: ``httpx-aiohttp`` swaps the transport underneath, so retries, timeouts and event
+streams behave the same. aiohttp only runs on asyncio, so this client does not work under trio.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from . import _constants as constants
+
+if TYPE_CHECKING:
+    _Base = httpx.AsyncClient
+else:
+    try:
+        from httpx_aiohttp import HttpxAiohttpClient as _Base
+    except ImportError:  # pragma: no cover - only without the extra
+        _Base = httpx.AsyncClient
+
+
+class DefaultAioHttpClient(_Base):
+    """aiohttp-backed `httpx.AsyncClient` with the SDK's default connection limits and redirect handling.
+
+    Pass it to `AsyncOpencode` as ``http_client``. Keyword arguments go to `httpx.AsyncClient`. The SDK does not
+    close a client it was given, so close it yourself (``async with`` it) when you are done. Creating one without
+    the ``aiohttp`` extra installed raises `RuntimeError`.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        if _Base is httpx.AsyncClient:
+            raise RuntimeError(
+                "DefaultAioHttpClient needs the aiohttp extra: pip install 'opencode-python-sdk[aiohttp]'"
+            )
+        kwargs.setdefault("limits", constants.DEFAULT_CONNECTION_LIMITS)
+        kwargs.setdefault("follow_redirects", True)
+        super().__init__(**kwargs)

opencode/_base_client.py

@@ -37,12 +37,13 @@ from ._exceptions import (
     validation_summary,
 )
 from ._qs import encode_query, to_jsonable
+from ._response import APIResponse, AsyncAPIResponse, raw_mode
 from ._streaming import AsyncStream, Stream
 from ._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
 from ._version import __version__
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from collections.abc import Callable, Coroutine, Mapping
     from types import TracebackType
 
     from ._pagination import AsyncPaginator, SyncCursorPage
@@ -354,13 +355,13 @@ class SyncAPIClient(_BaseClient):
     ) -> None:
         self.close()
 
-    def _send(self, options: RequestOptions) -> httpx.Response:
+    def _send(self, options: RequestOptions, *, stream_body: bool = False) -> httpx.Response:
         attempt = 0
         while True:
             request = self._build_request(options)
             log.debug("Request %s %s (attempt %d)", request.method, request.url, attempt + 1)
             try:
-                response = self._http.send(request, stream=options.stream)
+                response = self._http.send(request, stream=options.stream or stream_body)
             except httpx.TransportError as exc:
                 if attempt < self.max_retries and self._should_retry_error(options, exc):
                     delay = self._retry_delay(attempt, None)
@@ -384,7 +385,7 @@ class SyncAPIClient(_BaseClient):
                 time.sleep(delay)
                 attempt += 1
                 continue
-            if options.stream:
+            if options.stream or stream_body:
                 response.read()
             raise self._status_error(response, self._decode_error_body(response))
 
@@ -397,13 +398,23 @@ class SyncAPIClient(_BaseClient):
         unwrap: bool = False,
     ) -> Any:
         """Sends a request and returns the decoded response."""
+        if raw_mode() is not None:
+            return self._raw(options, lambda response: self._parse(response, kind, response_type, unwrap))
         response = self._send(options)
         return self._parse(response, kind, response_type, unwrap)
 
+    def _raw(self, options: RequestOptions, parser: Callable[[httpx.Response], Any]) -> APIResponse[Any]:
+        response = self._send(options, stream_body=raw_mode() == "stream")
+        return APIResponse(response, parser, event_stream=options.stream)
+
     def stream(self, options: RequestOptions, *, item_type: type[_T] | Any) -> Stream[Any]:
         """Opens a server-sent event stream."""
         options.stream = True
-        response = self._send(options)
+        if raw_mode() is not None:
+            return cast("Stream[Any]", self._raw(options, lambda response: self._open_stream(response, item_type)))
+        return self._open_stream(self._send(options), item_type)
+
+    def _open_stream(self, response: httpx.Response, item_type: Any) -> Stream[Any]:
         content_type = response.headers.get("content-type", "")
         if content_type.split(";", 1)[0].strip().lower() != "text/event-stream":
             response.read()
@@ -413,10 +424,109 @@ class SyncAPIClient(_BaseClient):
             )
         return Stream(response, type_adapter(item_type))
 
+    def get(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``GET path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(method="GET", path=path, extra_query=query, extra_headers=headers, timeout=timeout)
+        return self.request(options, response_type=cast_to)
+
+    def post(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``POST path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="POST", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return self.request(options, response_type=cast_to)
+
+    def put(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``PUT path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="PUT", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return self.request(options, response_type=cast_to)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``PATCH path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="PATCH", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return self.request(options, response_type=cast_to)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``DELETE path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(method="DELETE", path=path, extra_query=query, extra_headers=headers, timeout=timeout)
+        return self.request(options, response_type=cast_to)
+
     def page(self, options: RequestOptions, *, response_type: Any) -> SyncCursorPage[Any]:
         """Fetches the first page of a cursor-paginated list."""
         from ._pagination import SyncCursorPage
 
+        if raw_mode() is not None:
+            return cast(
+                "SyncCursorPage[Any]",
+                self._raw(
+                    options,
+                    lambda response: SyncCursorPage.build(
+                        self, options, response_type, self._parse(response, "json", response_type, False)
+                    ),
+                ),
+            )
         return SyncCursorPage.fetch(self, options, response_type)
 
 
@@ -473,13 +583,13 @@ class AsyncAPIClient(_BaseClient):
     ) -> None:
         await self.close()
 
-    async def _send(self, options: RequestOptions) -> httpx.Response:
+    async def _send(self, options: RequestOptions, *, stream_body: bool = False) -> httpx.Response:
         attempt = 0
         while True:
             request = self._build_request(options)
             log.debug("Request %s %s (attempt %d)", request.method, request.url, attempt + 1)
             try:
-                response = await self._http.send(request, stream=options.stream)
+                response = await self._http.send(request, stream=options.stream or stream_body)
             except httpx.TransportError as exc:
                 if attempt < self.max_retries and self._should_retry_error(options, exc):
                     delay = self._retry_delay(attempt, None)
@@ -503,7 +613,7 @@ class AsyncAPIClient(_BaseClient):
                 await anyio.sleep(delay)
                 attempt += 1
                 continue
-            if options.stream:
+            if options.stream or stream_body:
                 await response.aread()
             raise self._status_error(response, self._decode_error_body(response))
 
@@ -516,13 +626,31 @@ class AsyncAPIClient(_BaseClient):
         unwrap: bool = False,
     ) -> Any:
         """Sends a request and returns the decoded response."""
+        if raw_mode() is not None:
+            return await self._raw(options, lambda response: self._parse(response, kind, response_type, unwrap))
         response = await self._send(options)
         return self._parse(response, kind, response_type, unwrap)
 
+    async def _raw(self, options: RequestOptions, parser: Callable[[httpx.Response], Any]) -> AsyncAPIResponse[Any]:
+        response = await self._send(options, stream_body=raw_mode() == "stream")
+        return AsyncAPIResponse(response, parser, event_stream=options.stream)
+
     async def stream(self, options: RequestOptions, *, item_type: type[_T] | Any) -> AsyncStream[Any]:
         """Opens a server-sent event stream."""
         options.stream = True
-        response = await self._send(options)
+        if raw_mode() is not None:
+            raw = await self._raw(options, lambda response: self._open_stream(response, item_type))
+            return cast("AsyncStream[Any]", raw)
+        return await self._open_async_stream(await self._send(options), item_type)
+
+    @staticmethod
+    def _open_stream(response: httpx.Response, item_type: Any) -> AsyncStream[Any]:
+        content_type = response.headers.get("content-type", "")
+        if content_type.split(";", 1)[0].strip().lower() != "text/event-stream":
+            raise APIResponseValidationError(response, None, message=f"Expected an event stream, got {content_type!r}")
+        return AsyncStream(response, type_adapter(item_type))
+
+    async def _open_async_stream(self, response: httpx.Response, item_type: Any) -> AsyncStream[Any]:
         content_type = response.headers.get("content-type", "")
         if content_type.split(";", 1)[0].strip().lower() != "text/event-stream":
             await response.aread()
@@ -532,8 +660,106 @@ class AsyncAPIClient(_BaseClient):
             )
         return AsyncStream(response, type_adapter(item_type))
 
+    async def get(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``GET path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(method="GET", path=path, extra_query=query, extra_headers=headers, timeout=timeout)
+        return await self.request(options, response_type=cast_to)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``POST path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="POST", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return await self.request(options, response_type=cast_to)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``PUT path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="PUT", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return await self.request(options, response_type=cast_to)
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        body: object | NotGiven = NOT_GIVEN,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``PATCH path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(
+            method="PATCH", path=path, body=body, extra_query=query, extra_headers=headers, timeout=timeout
+        )
+        return await self.request(options, response_type=cast_to)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        cast_to: Any = object,
+        query: Query | None = None,
+        headers: Headers | None = None,
+        timeout: Timeout | NotGiven = NOT_GIVEN,
+    ) -> Any:
+        """Sends ``DELETE path`` (relative to ``base_url``) with the client's auth, retries and error mapping.
+
+        For endpoints this client does not cover yet. The JSON response is validated against ``cast_to``.
+        """
+        options = RequestOptions(method="DELETE", path=path, extra_query=query, extra_headers=headers, timeout=timeout)
+        return await self.request(options, response_type=cast_to)
+
     def page(self, options: RequestOptions, *, response_type: Any) -> AsyncPaginator[Any]:
         """Returns an awaitable, async-iterable paginator over a cursor-paginated list."""
-        from ._pagination import AsyncPaginator
-
+        from ._pagination import AsyncCursorPage, AsyncPaginator
+
+        if raw_mode() is not None:
+            # Awaited by the raw-response wrapper: the raw form of a list call is the first page's response.
+            raw: Coroutine[Any, Any, AsyncAPIResponse[Any]] = self._raw(
+                options,
+                lambda response: AsyncCursorPage.build(
+                    self, options, response_type, self._parse(response, "json", response_type, False)
+                ),
+            )
+            return cast("AsyncPaginator[Any]", raw)
         return AsyncPaginator(self, options, response_type)

opencode/_client.py

@@ -9,12 +9,21 @@ from ._base_client import AsyncAPIClient, SyncAPIClient
 from ._constants import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_USERNAME
 from ._events import AsyncEventHub, EventHub
 from ._rpc import AsyncTypedRpcResource, TypedRpcResource
+from ._service import (
+    EnsureReason,
+    ServiceError,
+    Version,
+    async_discover,
+    async_ensure,
+    discover as discover_service,
+    ensure as ensure_service,
+)
 from ._types import NOT_GIVEN, NotGiven, Timeout
 from .resources import AsyncResources, SyncResources
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Iterable, Mapping
+    from collections.abc import Callable, Iterable, Mapping, Sequence
 
     import httpx
 
@@ -82,6 +91,67 @@ class Opencode(SyncAPIClient, SyncResources):
             transport=transport,
         )
 
+    @classmethod
+    def from_service(
+        cls,
+        *,
+        start: bool = True,
+        file: str | os.PathLike[str] | None = None,
+        version: Version | None = None,
+        command: Sequence[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        on_start: Callable[[EnsureReason, str | None], None] | None = None,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Connect to the local background service, starting ``opencode serve --service`` if needed.
+
+        Uses :func:`opencode.service.ensure`, or :func:`opencode.service.discover` when ``start`` is false, and
+        sends the service's password with every request.
+
+        Args:
+            start: Start or replace the service when no matching one is running. When false, raise instead.
+            file: Registration file. Defaults to ``$XDG_STATE_HOME/opencode/service.json``.
+            version: Required exact version, or a predicate on the service version.
+            command: Service command and arguments, used when starting it.
+            env: Variables added to the environment of a started service.
+            on_start: Called once before a service process is started.
+            directory: Default project directory, as in the constructor.
+            timeout: Default request timeout, as in the constructor.
+            max_retries: Retries for failed requests, as in the constructor.
+            default_headers: Headers sent with every request.
+            default_query: Query parameters sent with every request.
+
+        Raises:
+            ServiceError: No matching service is running and ``start`` is false, or it could not be started.
+
+        Example::
+
+            with Opencode.from_service() as client:
+                print(client.server.info().version)
+        """
+        if start:
+            endpoint = ensure_service(file, version, command=command, env=env, on_start=on_start)
+        else:
+            found = discover_service(file, version)
+            if found is None:
+                raise ServiceError("No matching OpenCode background service is running")
+            endpoint = found
+        return cls(
+            endpoint.url,
+            # An empty password sends no credentials instead of falling back to OPENCODE_PASSWORD.
+            password="" if endpoint.auth is None else endpoint.auth.password,
+            username=DEFAULT_USERNAME if endpoint.auth is None else endpoint.auth.username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+        )
+
     @cached_property
     def events(self) -> EventHub:
         """The shared event stream: one connection for every subscriber. See :class:`opencode.EventHub`."""
@@ -132,7 +202,8 @@ class Opencode(SyncAPIClient, SyncResources):
     ) -> Self:
         """Returns a client with some options changed. It shares this client's connection pool.
 
-        ``default_headers`` and ``default_query`` are merged over the current values.
+        ``default_headers`` and ``default_query`` are merged over the current values. Closing the copy leaves the
+        pool open; it closes with this client. Also available as ``copy``.
         """
         client = type(self)(
             base_url=base_url or self.base_url,
@@ -147,6 +218,8 @@ class Opencode(SyncAPIClient, SyncResources):
         )
         return client
 
+    copy = with_options
+
 
 class AsyncOpencode(AsyncAPIClient, AsyncResources):
     """Asynchronous client for an OpenCode server. Works with asyncio and trio.
@@ -189,6 +262,42 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
             transport=transport,
         )
 
+    @classmethod
+    async def from_service(
+        cls,
+        *,
+        start: bool = True,
+        file: str | os.PathLike[str] | None = None,
+        version: Version | None = None,
+        command: Sequence[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        on_start: Callable[[EnsureReason, str | None], None] | None = None,
+        directory: str | os.PathLike[str] | None = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+    ) -> Self:
+        """Async version of :meth:`Opencode.from_service`. Await it: ``client = await AsyncOpencode.from_service()``."""
+        if start:
+            endpoint = await async_ensure(file, version, command=command, env=env, on_start=on_start)
+        else:
+            found = await async_discover(file, version)
+            if found is None:
+                raise ServiceError("No matching OpenCode background service is running")
+            endpoint = found
+        return cls(
+            endpoint.url,
+            # An empty password sends no credentials instead of falling back to OPENCODE_PASSWORD.
+            password="" if endpoint.auth is None else endpoint.auth.password,
+            username=DEFAULT_USERNAME if endpoint.auth is None else endpoint.auth.username,
+            directory=directory,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+        )
+
     @cached_property
     def events(self) -> AsyncEventHub:
         """The shared event stream: one connection for every subscriber. See :class:`opencode.AsyncEventHub`."""
@@ -239,7 +348,8 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
     ) -> Self:
         """Returns a client with some options changed. It shares this client's connection pool.
 
-        ``default_headers`` and ``default_query`` are merged over the current values.
+        ``default_headers`` and ``default_query`` are merged over the current values. Closing the copy leaves the
+        pool open; it closes with this client. Also available as ``copy``.
         """
         client = type(self)(
             base_url=base_url or self.base_url,
@@ -253,3 +363,5 @@ class AsyncOpencode(AsyncAPIClient, AsyncResources):
             http_client=self._http,
         )
         return client
+
+    copy = with_options

opencode/_logs.py

@@ -0,0 +1,29 @@
+"""``OPENCODE_LOG`` support: configure the ``opencode`` logger from the environment."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger("opencode")
+
+_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO}
+
+
+def setup_logging() -> None:
+    """Attach a stderr handler to the ``opencode`` logger when ``OPENCODE_LOG`` is ``debug`` or ``info``.
+
+    Does nothing when the variable is unset or has any other value. The OpenCode CLI reads
+    ``OPENCODE_LOG_LEVEL``, not ``OPENCODE_LOG``, so the two do not clash.
+    """
+    level = _LEVELS.get(os.environ.get("OPENCODE_LOG", "").strip().lower())
+    if level is None:
+        return
+    if not any(getattr(h, "_opencode_env", False) for h in logger.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(
+            logging.Formatter("[%(asctime)s - %(name)s:%(lineno)d - %(levelname)s] %(message)s", "%Y-%m-%d %H:%M:%S")
+        )
+        handler._opencode_env = True  # type: ignore[attr-defined]
+        logger.addHandler(handler)
+    logger.setLevel(level)

opencode/_pagination.py

@@ -79,6 +79,13 @@ class SyncCursorPage(_PageBase[_T]):
     @classmethod
     def fetch(cls, client: SyncAPIClient, options: RequestOptions, response_type: Any) -> SyncCursorPage[Any]:
         payload = client.request(options, response_type=response_type)
+        return cls.build(client, options, response_type, payload)
+
+    @classmethod
+    def build(
+        cls, client: SyncAPIClient, options: RequestOptions, response_type: Any, payload: Any
+    ) -> SyncCursorPage[Any]:
+        """Builds a page from an already parsed response."""
         data, next_cursor, previous_cursor = _page_parts(payload)
         return cls(
             client=client,
@@ -134,6 +141,13 @@ class AsyncCursorPage(_PageBase[_T]):
     @classmethod
     async def fetch(cls, client: AsyncAPIClient, options: RequestOptions, response_type: Any) -> AsyncCursorPage[Any]:
         payload = await client.request(options, response_type=response_type)
+        return cls.build(client, options, response_type, payload)
+
+    @classmethod
+    def build(
+        cls, client: AsyncAPIClient, options: RequestOptions, response_type: Any, payload: Any
+    ) -> AsyncCursorPage[Any]:
+        """Builds a page from an already parsed response."""
         data, next_cursor, previous_cursor = _page_parts(payload)
         return cls(
             client=client,