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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.2.0
+Version: 0.2.2
 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/
@@ -419,6 +419,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

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

@@ -382,6 +382,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

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

@@ -55,9 +55,11 @@ dev = [
   "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.2}/src/opencode/__init__.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from . import service
 from ._client import AsyncOpencode, Opencode
 
 # <generated:error-imports>
@@ -78,6 +79,7 @@ from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
 from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
 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__
@@ -136,6 +138,7 @@ __all__ = [
     "BaseModel",
     "ConflictError",
     "ContentTooLargeError",
+    "Endpoint",
     "InternalServerError",
     "NotFoundError",
     "NotGiven",
@@ -148,11 +151,13 @@ __all__ = [
     "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
+    "ServiceError",
     "ServiceUnavailableError",
     "Stream",
     "SyncCursorPage",
     "UnprocessableEntityError",
     "__version__",
+    "service",
     "types",
     # Shared event stream and typed plugin RPC
     "SUBSCRIBER_CAPACITY",

{opencode_python_sdk-0.2.0 → opencode_python_sdk-0.2.2}/src/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`."""
@@ -189,6 +259,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`."""