opencode-python-sdk 0.2.0__tar.gz → 0.2.3__tar.gz

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.3}/CHANGELOG.md

@@ -11,6 +11,15 @@ Releases are published automatically on every merge to `main`. Release notes for
 - `client.rpc(Definition)`: typed plugin RPC calls and event subscriptions declared with `RpcDefinition`,
   `rpc_method` and `rpc_event`; RPC failures raise `RpcCallError` / `RpcCallInternalError`.
 - `Stream.on_activity` and `Stream.interrupt()`.
+- `client.copy(...)`, an alias of `client.with_options(...)`; documented that copies share the connection pool
+  and do not close it.
+- `OPENCODE_LOG=debug|info` sends the `opencode` logger to stderr at that level.
+- `DefaultAioHttpClient`: an optional aiohttp transport for `AsyncOpencode`, installed with the `aiohttp` extra
+  (`pip install 'opencode-python-sdk[aiohttp]'`) and passed as `http_client=`.
+- `.with_raw_response` and `.with_streaming_response` on every resource (sync and async): return an
+  `APIResponse` / `AsyncAPIResponse` with `headers`, `status_code`, `http_response`, `request`, `text`, `json()`,
+  `iter_bytes()` / `iter_lines()` and `parse()` for the usual typed value.
+- `client.get` / `post` / `put` / `patch` / `delete` for endpoints the client has no method for.
 
 ## 0.1.0
 

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.2.0
+Version: 0.2.3
 Summary: Typed Python client for the OpenCode 2.x server API
 Project-URL: Homepage, https://github.com/shrijayan/opencode-python-sdk
 Project-URL: Documentation, https://shrijayan.github.io/opencode-python-sdk/
@@ -31,6 +31,8 @@ Requires-Dist: anyio<5,>=4.4
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2.12
 Requires-Dist: typing-extensions>=4.12
+Provides-Extra: aiohttp
+Requires-Dist: httpx-aiohttp<0.3,>=0.1.9; extra == 'aiohttp'
 Provides-Extra: pty
 Requires-Dist: websockets<17,>=14; extra == 'pty'
 Description-Content-Type: text/markdown
@@ -116,6 +118,27 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### aiohttp transport
+
+For high-concurrency asyncio code you can swap httpx's networking for [aiohttp](https://docs.aiohttp.org). Install
+the extra and pass `DefaultAioHttpClient` as `http_client`:
+
+```bash
+pip install 'opencode-python-sdk[aiohttp]'
+```
+
+```python
+from opencode import AsyncOpencode, DefaultAioHttpClient
+
+
+async def main() -> None:
+    async with DefaultAioHttpClient() as http, AsyncOpencode("http://127.0.0.1:4096", http_client=http) as client:
+        info = await client.server.info()
+```
+
+Retries, timeouts and event streams work the same. aiohttp runs on asyncio only, not trio. The client does not close
+an `http_client` you pass in, so close it yourself as above.
+
 ## Calling the API
 
 Methods mirror the official TypeScript client: `client.<group>.<operation>()`, with names in `snake_case`. Path
@@ -350,6 +373,15 @@ client.session.get("ses_...", timeout=5.0)  # per call
 
 The default timeout is 10 minutes with a 10 second connect timeout.
 
+`with_options` (alias `copy`) returns a client with some options changed: `timeout`, `max_retries`, `base_url`,
+`password`, `directory`, `default_headers` and `default_query` (headers and query are merged over the current
+ones). The copy shares the original's connection pool, and closing it leaves the pool open.
+
+```python
+client.with_options(max_retries=0).session.create()  # no retries for this call
+scoped = client.with_options(directory="/other/repo", default_headers={"X-Trace": "1"})
+```
+
 ## Running an agent headless
 
 `client.session.run` does the usual "prompt an agent and wait" round trip in one call: it creates a session (or
@@ -419,6 +451,27 @@ with server:
 The server runs in `--stdio` mode, so it also exits when the Python process dies. `AsyncOpencodeServer` is the
 async equivalent.
 
+### The background service
+
+OpenCode can also run one shared background server per user (`opencode serve --service`), which registers itself in
+`$XDG_STATE_HOME/opencode/service.json`. `Opencode.from_service()` connects to it, starting it first if it is not
+running:
+
+```python
+from opencode import Opencode, service
+
+with Opencode.from_service(version="2.1.2") as client:  # replaces a service running another version
+    print(client.server.info().version)
+
+endpoint = service.discover()  # an Endpoint, or None; never starts anything
+service.stop(pty="handoff")  # hand persistent terminals to the next service instead of closing them
+```
+
+`service.ensure()` returns the `Endpoint` (URL and credentials) without creating a client, and `service.headers()`
+gives its `Authorization` header for other HTTP clients. Concurrent callers are safe: they race to start the service
+and all get the one that won. `await AsyncOpencode.from_service()`, `service.async_discover()`,
+`service.async_ensure()` and `service.async_stop()` are the async equivalents.
+
 ## Advanced
 
 ```python
@@ -436,7 +489,63 @@ client.session.create(title="t", extra_headers={"X-Trace": "1"}, extra_body={"fu
 ```
 
 Logs go to the `opencode` logger. `logging.getLogger("opencode").setLevel(logging.DEBUG)` shows every request and
-retry; credentials are never logged.
+retry; credentials are never logged. Set `OPENCODE_LOG=debug` (or `info`) to have the SDK attach a stderr handler at
+that level on import, without touching your own logging config.
+
+### Accessing raw response data
+
+Prefix any method with `.with_raw_response` to get the HTTP response (headers, status, request) instead of the
+parsed value. `.parse()` returns what the plain call would have returned:
+
+```python
+response = client.session.with_raw_response.get("ses_...")
+print(response.status_code, response.headers.get("content-type"))
+session = response.parse()  # SessionInfo
+```
+
+`.with_raw_response` reads the body before returning. `.with_streaming_response` does not: it is a context manager
+that sends the request on entry and closes the connection on exit, so you can read large bodies incrementally with
+`iter_bytes()`, `iter_text()` or `iter_lines()`, or still call `parse()`:
+
+```python
+with client.file.with_streaming_response.read("big.log") as response:
+    for line in response.iter_lines():
+        ...
+```
+
+Both exist on every resource and sub-resource of both clients (`async with` and `await response.parse()` on
+`AsyncOpencode`). `APIResponse` also has `.http_response`, `.request`, `.text`, `.json()` and `.read()`.
+
+- **List methods** give the response of the first page; `parse()` returns a `SyncCursorPage` / `AsyncCursorPage`
+  that fetches the following pages as usual.
+- **Event streams** are never read eagerly: `parse()` returns the `Stream` / `AsyncStream`, which reads events as
+  you iterate. Close the stream (or the response) when done.
+- Error statuses still raise `APIStatusError` subclasses; the response is on the exception as `error.response`.
+- Hand-written helpers such as `client.session.run()` and `client.pty.attach()` are not wrapped.
+
+### Making custom/undocumented requests
+
+Undocumented parameters go through `extra_headers`, `extra_query` and `extra_body` on every method (see above). For
+an endpoint the client has no method for, `client.get`, `post`, `put`, `patch` and `delete` send a request relative
+to `base_url` with the client's authentication, retries and typed errors, and return the decoded JSON:
+
+```python
+data = client.post("/api/new-endpoint", body={"key": "value"}, query={"directory": "/repo"})
+
+# Validate into a type, e.g. a response wrapped in {"data": ...}:
+from opencode.types import SessionInfo
+
+payload = client.get("/api/session/ses_...", cast_to=dict[str, SessionInfo])
+```
+
+### Determining the installed version
+
+```python
+import opencode
+
+print(opencode.__version__)  # this package
+print(opencode.API_VERSION)  # the OpenCode server version it was generated from
+```
 
 ## Versioning
 

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.3}/README.md

@@ -79,6 +79,27 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### aiohttp transport
+
+For high-concurrency asyncio code you can swap httpx's networking for [aiohttp](https://docs.aiohttp.org). Install
+the extra and pass `DefaultAioHttpClient` as `http_client`:
+
+```bash
+pip install 'opencode-python-sdk[aiohttp]'
+```
+
+```python
+from opencode import AsyncOpencode, DefaultAioHttpClient
+
+
+async def main() -> None:
+    async with DefaultAioHttpClient() as http, AsyncOpencode("http://127.0.0.1:4096", http_client=http) as client:
+        info = await client.server.info()
+```
+
+Retries, timeouts and event streams work the same. aiohttp runs on asyncio only, not trio. The client does not close
+an `http_client` you pass in, so close it yourself as above.
+
 ## Calling the API
 
 Methods mirror the official TypeScript client: `client.<group>.<operation>()`, with names in `snake_case`. Path
@@ -313,6 +334,15 @@ client.session.get("ses_...", timeout=5.0)  # per call
 
 The default timeout is 10 minutes with a 10 second connect timeout.
 
+`with_options` (alias `copy`) returns a client with some options changed: `timeout`, `max_retries`, `base_url`,
+`password`, `directory`, `default_headers` and `default_query` (headers and query are merged over the current
+ones). The copy shares the original's connection pool, and closing it leaves the pool open.
+
+```python
+client.with_options(max_retries=0).session.create()  # no retries for this call
+scoped = client.with_options(directory="/other/repo", default_headers={"X-Trace": "1"})
+```
+
 ## Running an agent headless
 
 `client.session.run` does the usual "prompt an agent and wait" round trip in one call: it creates a session (or
@@ -382,6 +412,27 @@ with server:
 The server runs in `--stdio` mode, so it also exits when the Python process dies. `AsyncOpencodeServer` is the
 async equivalent.
 
+### The background service
+
+OpenCode can also run one shared background server per user (`opencode serve --service`), which registers itself in
+`$XDG_STATE_HOME/opencode/service.json`. `Opencode.from_service()` connects to it, starting it first if it is not
+running:
+
+```python
+from opencode import Opencode, service
+
+with Opencode.from_service(version="2.1.2") as client:  # replaces a service running another version
+    print(client.server.info().version)
+
+endpoint = service.discover()  # an Endpoint, or None; never starts anything
+service.stop(pty="handoff")  # hand persistent terminals to the next service instead of closing them
+```
+
+`service.ensure()` returns the `Endpoint` (URL and credentials) without creating a client, and `service.headers()`
+gives its `Authorization` header for other HTTP clients. Concurrent callers are safe: they race to start the service
+and all get the one that won. `await AsyncOpencode.from_service()`, `service.async_discover()`,
+`service.async_ensure()` and `service.async_stop()` are the async equivalents.
+
 ## Advanced
 
 ```python
@@ -399,7 +450,63 @@ client.session.create(title="t", extra_headers={"X-Trace": "1"}, extra_body={"fu
 ```
 
 Logs go to the `opencode` logger. `logging.getLogger("opencode").setLevel(logging.DEBUG)` shows every request and
-retry; credentials are never logged.
+retry; credentials are never logged. Set `OPENCODE_LOG=debug` (or `info`) to have the SDK attach a stderr handler at
+that level on import, without touching your own logging config.
+
+### Accessing raw response data
+
+Prefix any method with `.with_raw_response` to get the HTTP response (headers, status, request) instead of the
+parsed value. `.parse()` returns what the plain call would have returned:
+
+```python
+response = client.session.with_raw_response.get("ses_...")
+print(response.status_code, response.headers.get("content-type"))
+session = response.parse()  # SessionInfo
+```
+
+`.with_raw_response` reads the body before returning. `.with_streaming_response` does not: it is a context manager
+that sends the request on entry and closes the connection on exit, so you can read large bodies incrementally with
+`iter_bytes()`, `iter_text()` or `iter_lines()`, or still call `parse()`:
+
+```python
+with client.file.with_streaming_response.read("big.log") as response:
+    for line in response.iter_lines():
+        ...
+```
+
+Both exist on every resource and sub-resource of both clients (`async with` and `await response.parse()` on
+`AsyncOpencode`). `APIResponse` also has `.http_response`, `.request`, `.text`, `.json()` and `.read()`.
+
+- **List methods** give the response of the first page; `parse()` returns a `SyncCursorPage` / `AsyncCursorPage`
+  that fetches the following pages as usual.
+- **Event streams** are never read eagerly: `parse()` returns the `Stream` / `AsyncStream`, which reads events as
+  you iterate. Close the stream (or the response) when done.
+- Error statuses still raise `APIStatusError` subclasses; the response is on the exception as `error.response`.
+- Hand-written helpers such as `client.session.run()` and `client.pty.attach()` are not wrapped.
+
+### Making custom/undocumented requests
+
+Undocumented parameters go through `extra_headers`, `extra_query` and `extra_body` on every method (see above). For
+an endpoint the client has no method for, `client.get`, `post`, `put`, `patch` and `delete` send a request relative
+to `base_url` with the client's authentication, retries and typed errors, and return the decoded JSON:
+
+```python
+data = client.post("/api/new-endpoint", body={"key": "value"}, query={"directory": "/repo"})
+
+# Validate into a type, e.g. a response wrapped in {"data": ...}:
+from opencode.types import SessionInfo
+
+payload = client.get("/api/session/ses_...", cast_to=dict[str, SessionInfo])
+```
+
+### Determining the installed version
+
+```python
+import opencode
+
+print(opencode.__version__)  # this package
+print(opencode.API_VERSION)  # the OpenCode server version it was generated from
+```
 
 ## Versioning
 

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.3}/pyproject.toml

@@ -43,21 +43,27 @@ Changelog = "https://github.com/shrijayan/opencode-python-sdk/blob/main/CHANGELO
 pty = [
     "websockets>=14,<17",
 ]
+aiohttp = [
+    "httpx-aiohttp>=0.1.9,<0.3",
+]
 
 [dependency-groups]
 dev = [
   "mypy>=1.18",
   "pyright>=1.1.408",
   "pytest>=8.4",
+  "httpx-aiohttp>=0.1.9",
   "pytest-cov>=7",
   "respx>=0.22",
   "ruff>=0.14",
   "trio>=0.31",
   "websockets>=14",
 ]
+# Pillow (via [imaging]) only ships patched releases for Python 3.11+, so docs builds need 3.11+.
 docs = [
-    "mkdocs-material[imaging]>=9.6",
-    "mkdocstrings[python]>=0.30",
+    "mkdocs-material[imaging]>=9.6; python_version >= '3.11'",
+    "mkdocstrings[python]>=0.30; python_version >= '3.11'",
+    "pillow>=13; python_version >= '3.11'",
 ]
 
 [build-system]

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.3}/src/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_python_sdk-0.2.3/src/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)