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

opencode/_server.py

@@ -0,0 +1,335 @@
+"""Starts and stops a local ``opencode serve`` process."""
+
+from __future__ import annotations
+
+import collections
+import contextlib
+import json
+import os
+import queue
+import secrets
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, cast
+
+import anyio.to_thread
+import httpx
+from typing_extensions import Self
+
+from ._client import AsyncOpencode, Opencode
+from ._constants import DEFAULT_USERNAME
+from ._exceptions import OpencodeError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from types import TracebackType
+
+    from ._types import Timeout
+
+__all__ = ["AsyncOpencodeServer", "OpencodeServer", "ServerStartError"]
+
+_ISOLATION_ENV = {
+    # Ignore the working directory's opencode.json, AGENTS.md and .opencode folder.
+    "OPENCODE_CONFIG_PROJECT_DISABLE": "1",
+    # Ignore Claude Code skills and instructions found in the project or home directory.
+    "OPENCODE_DISABLE_CLAUDE_CODE": "1",
+}
+
+
+class ServerStartError(OpencodeError):
+    """``opencode serve`` could not be started or did not report its address in time."""
+
+    def __init__(self, message: str, *, output: str = "") -> None:
+        super().__init__(f"{message}\n\nServer output:\n{output}" if output else message)
+        self.output = output
+
+
+class OpencodeServer:
+    """Runs ``opencode serve`` as a child process for the lifetime of a ``with`` block.
+
+    The server listens on a free local port and requires a random password, which is passed to clients created
+    with :meth:`client`. It runs in ``--stdio`` mode, so it also exits if this process dies.
+
+    Args:
+        cwd: Directory the server runs in, which is its default project location.
+        config: OpenCode configuration as a mapping, passed through ``OPENCODE_CONFIG_CONTENT``.
+        isolated: Ignore project and Claude Code configuration found on disk, for reproducible embedded use.
+        env: Extra environment variables for the server.
+        hostname: Interface to bind. Keep ``127.0.0.1`` unless the server must be reachable from other hosts.
+        port: Port to bind. ``0`` picks a free port.
+        password: Server password. A random one is generated by default.
+        binary: The ``opencode`` executable, looked up on ``PATH`` by default.
+        startup_timeout: Seconds to wait for the server to report its address.
+
+    Example::
+
+        with OpencodeServer(cwd="/path/to/repo", isolated=True) as server:
+            client = server.client()
+            print(client.server.info().version)
+    """
+
+    def __init__(
+        self,
+        *,
+        cwd: str | os.PathLike[str] | None = None,
+        config: Mapping[str, Any] | None = None,
+        isolated: bool = False,
+        env: Mapping[str, str] | None = None,
+        hostname: str = "127.0.0.1",
+        port: int = 0,
+        password: str | None = None,
+        binary: str | os.PathLike[str] = "opencode",
+        startup_timeout: float = 60.0,
+    ) -> None:
+        self.cwd = Path(cwd) if cwd is not None else None
+        self.config = dict(config) if config is not None else None
+        self.isolated = isolated
+        self.env = dict(env or {})
+        self.hostname = hostname
+        self.port = port
+        self.password = password if password is not None else secrets.token_urlsafe(32)
+        self.binary = os.fspath(binary)
+        self.startup_timeout = startup_timeout
+        self._process: subprocess.Popen[str] | None = None
+        self._url: str | None = None
+        self._output: collections.deque[str] = collections.deque(maxlen=200)
+        self._lock = threading.Lock()
+        self._threads: list[threading.Thread] = []
+
+    @property
+    def url(self) -> str:
+        """The server's base URL. Available once started."""
+        if self._url is None:
+            raise OpencodeError("The OpenCode server is not running. Call start() or use it as a context manager.")
+        return self._url
+
+    @property
+    def process(self) -> subprocess.Popen[str] | None:
+        """The ``opencode serve`` child process, or ``None`` before it starts."""
+        return self._process
+
+    @property
+    def running(self) -> bool:
+        """Whether the server process is alive."""
+        return self._process is not None and self._process.poll() is None
+
+    def client(self, *, directory: str | os.PathLike[str] | None = None, timeout: Timeout | None = None) -> Opencode:
+        """Returns a sync client connected to this server."""
+        kwargs: dict[str, Any] = {} if timeout is None else {"timeout": timeout}
+        return Opencode(self.url, password=self.password, username=DEFAULT_USERNAME, directory=directory, **kwargs)
+
+    def async_client(
+        self, *, directory: str | os.PathLike[str] | None = None, timeout: Timeout | None = None
+    ) -> AsyncOpencode:
+        """Returns an async client connected to this server."""
+        kwargs: dict[str, Any] = {} if timeout is None else {"timeout": timeout}
+        return AsyncOpencode(self.url, password=self.password, username=DEFAULT_USERNAME, directory=directory, **kwargs)
+
+    def _command(self) -> list[str]:
+        executable = shutil.which(self.binary)
+        if executable is None:
+            raise ServerStartError(
+                f"Could not find the {self.binary!r} executable. Install OpenCode (https://opencode.ai) "
+                "or pass binary= with its path."
+            )
+        return [executable, "serve", "--stdio", "--hostname", self.hostname, "--port", str(self.port)]
+
+    def _environment(self) -> dict[str, str]:
+        environment = dict(os.environ)
+        # The server reads its password from the environment and removes it from what its tools inherit.
+        environment.pop("OPENCODE_SERVER_PASSWORD", None)
+        environment["OPENCODE_PASSWORD"] = self.password
+        if self.isolated:
+            environment.update(_ISOLATION_ENV)
+        if self.config is not None:
+            environment["OPENCODE_CONFIG_CONTENT"] = json.dumps(self.config)
+        environment.update(self.env)
+        return environment
+
+    def start(self) -> Self:
+        """Starts the server and waits until it reports its address."""
+        with self._lock:
+            if self.running:
+                return self
+            self._output.clear()
+            command = self._command()
+            try:
+                process = subprocess.Popen(
+                    command,
+                    cwd=self.cwd,
+                    env=self._environment(),
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    bufsize=1,
+                    # Keep Ctrl+C in a terminal from reaching the server before we can shut it down cleanly.
+                    start_new_session=sys.platform != "win32",
+                )
+            except OSError as exc:
+                raise ServerStartError(f"Could not start {command[0]}: {exc}") from exc
+            self._process = process
+            lines: queue.Queue[str | None] = queue.Queue()
+            assert process.stdout is not None
+            assert process.stderr is not None
+            self._pump(process.stdout, lines)
+            self._pump(process.stderr, None)
+
+            url = self._wait_for_url(process, lines)
+            if url is None:
+                output = "\n".join(self._output)
+                self._shutdown(process)
+                self._process = None
+                raise ServerStartError("OpenCode server did not start", output=output)
+            self._url = url
+            return self
+
+    def _pump(self, stream: IO[str], lines: queue.Queue[str | None] | None) -> None:
+        def run() -> None:
+            try:
+                for line in stream:
+                    stripped = line.rstrip("\n")
+                    self._output.append(stripped)
+                    if lines is not None:
+                        lines.put(stripped)
+            except (OSError, ValueError):
+                pass
+            finally:
+                if lines is not None:
+                    lines.put(None)
+
+        thread = threading.Thread(target=run, name="opencode-server-output", daemon=True)
+        thread.start()
+        self._threads.append(thread)
+
+    def _wait_for_url(self, process: subprocess.Popen[str], lines: queue.Queue[str | None]) -> str | None:
+        deadline = time.monotonic() + self.startup_timeout
+        while (remaining := deadline - time.monotonic()) > 0:
+            try:
+                line = lines.get(timeout=min(remaining, 0.5))
+            except queue.Empty:
+                if process.poll() is not None:
+                    return None
+                continue
+            if line is None:
+                return None
+            try:
+                message = json.loads(line)
+            except ValueError:
+                continue
+            url: object = cast("dict[str, Any]", message).get("url") if isinstance(message, dict) else None
+            if isinstance(url, str):
+                return str(httpx.URL(url))
+        return None
+
+    def stop(self, timeout: float = 10.0) -> None:
+        """Stops the server: closes its stdin, then terminates it if it has not exited within ``timeout``."""
+        with self._lock:
+            process = self._process
+            self._process = None
+            self._url = None
+            if process is not None:
+                self._shutdown(process, timeout)
+
+    def _shutdown(self, process: subprocess.Popen[str], timeout: float = 10.0) -> None:
+        self._terminate(process, timeout)
+        # The output threads finish at end of file; then the pipes can be closed.
+        for thread in self._threads:
+            thread.join(timeout=2)
+        self._threads.clear()
+        for stream in (process.stdout, process.stderr):
+            if stream is not None:
+                with contextlib.suppress(OSError):
+                    stream.close()
+
+    @staticmethod
+    def _terminate(process: subprocess.Popen[str], timeout: float = 10.0) -> None:
+        if process.stdin is not None:
+            with contextlib.suppress(OSError):
+                process.stdin.close()
+        try:
+            process.wait(timeout=timeout)
+            return
+        except subprocess.TimeoutExpired:
+            process.terminate()
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+
+    @property
+    def output(self) -> str:
+        """The last lines the server wrote, for diagnostics."""
+        return "\n".join(self._output)
+
+    def __enter__(self) -> Self:
+        return self.start()
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.stop()
+
+
+class AsyncOpencodeServer:
+    """Async wrapper around :class:`OpencodeServer`; takes the same arguments.
+
+    Example::
+
+        async with AsyncOpencodeServer(isolated=True) as server:
+            async with server.client() as client:
+                info = await client.server.info()
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._server = OpencodeServer(**kwargs)
+
+    @property
+    def url(self) -> str:
+        """The server's base URL. Available once started."""
+        return self._server.url
+
+    @property
+    def password(self) -> str:
+        """The server password clients authenticate with."""
+        return self._server.password
+
+    @property
+    def running(self) -> bool:
+        """Whether the server process is alive."""
+        return self._server.running
+
+    @property
+    def output(self) -> str:
+        """The last lines the server wrote, for diagnostics."""
+        return self._server.output
+
+    def client(
+        self, *, directory: str | os.PathLike[str] | None = None, timeout: Timeout | None = None
+    ) -> AsyncOpencode:
+        """Returns an async client connected to this server."""
+        return self._server.async_client(directory=directory, timeout=timeout)
+
+    async def start(self) -> Self:
+        """Starts the server and waits until it reports its address."""
+        await anyio.to_thread.run_sync(self._server.start)
+        return self
+
+    async def stop(self, timeout: float = 10.0) -> None:
+        """Stops the server: closes its stdin, then terminates it if it has not exited within ``timeout``."""
+        await anyio.to_thread.run_sync(lambda: self._server.stop(timeout))
+
+    async def __aenter__(self) -> Self:
+        return await self.start()
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.stop()

opencode/_streaming.py

@@ -0,0 +1,248 @@
+"""Server-sent event streams."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import re
+import socket
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+import httpx
+import pydantic
+from typing_extensions import Self
+
+from ._exceptions import APIConnectionError, APIResponseValidationError, validation_summary
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, AsyncIterator, Callable, Generator, Iterator
+    from types import TracebackType
+
+__all__ = ["AsyncStream", "ServerSentEvent", "Stream"]
+
+_T = TypeVar("_T")
+
+MAX_EVENT_BYTES = 16 * 1024 * 1024
+"""Upper bound for one buffered event, matching the official TypeScript client."""
+
+
+@dataclass(frozen=True)
+class ServerSentEvent:
+    """One decoded server-sent event."""
+
+    data: str
+    event: str | None = None
+    id: str | None = None
+    retry: int | None = None
+
+
+@dataclass
+class _Decoder:
+    """Incremental SSE decoder following the WHATWG event-stream parsing rules."""
+
+    _data: list[str] = field(default_factory=list[str])
+    _event: str | None = None
+    _id: str | None = None
+    _retry: int | None = None
+    _size: int = 0
+
+    def feed_line(self, line: str) -> ServerSentEvent | None:
+        if line == "":
+            return self._dispatch()
+        if line.startswith(":"):
+            return None
+        name, _, value = line.partition(":")
+        value = value.removeprefix(" ")
+        if name == "data":
+            self._size += len(value)
+            if self._size > MAX_EVENT_BYTES:
+                raise ValueError(f"Server-sent event exceeds {MAX_EVENT_BYTES} bytes")
+            self._data.append(value)
+        elif name == "event":
+            self._event = value
+        elif name == "id":
+            if "\0" not in value:
+                self._id = value
+        elif name == "retry" and value.isdigit():
+            self._retry = int(value)
+        return None
+
+    def _dispatch(self) -> ServerSentEvent | None:
+        if not self._data:
+            self._event = None
+            return None
+        event = ServerSentEvent(data="\n".join(self._data), event=self._event, id=self._id, retry=self._retry)
+        self._data = []
+        self._event = None
+        self._retry = None
+        self._size = 0
+        return event
+
+
+_NEWLINE = re.compile(r"\r\n|\r|\n")
+
+
+class _LineSplitter:
+    """Splits decoded text into lines on CRLF, CR or LF, across chunk boundaries."""
+
+    def __init__(self) -> None:
+        self._buffer = ""
+
+    def feed(self, chunk: str) -> list[str]:
+        buffer = self._buffer + chunk
+        lines: list[str] = []
+        start = 0
+        while (match := _NEWLINE.search(buffer, start)) is not None:
+            if match.group() == "\r" and match.end() == len(buffer):
+                break  # may be the first half of a CRLF split across chunks
+            lines.append(buffer[start : match.start()])
+            start = match.end()
+        self._buffer = buffer[start:]
+        if len(self._buffer) > MAX_EVENT_BYTES:
+            raise ValueError(f"Server-sent event line exceeds {MAX_EVENT_BYTES} bytes")
+        return lines
+
+    def flush(self) -> list[str]:
+        """Returns the final partial line, then an empty line so a pending event is dispatched."""
+        rest, self._buffer = self._buffer.removesuffix("\r"), ""
+        return [rest, ""] if rest else [""]
+
+
+class _StreamBase(Generic[_T]):
+    def __init__(self, response: httpx.Response, adapter: pydantic.TypeAdapter[_T]) -> None:
+        self.response = response
+        self._adapter = adapter
+        self.on_activity: Callable[[], object] | None = None
+        """Called for every chunk the stream receives, including keepalive comments that carry no event."""
+
+    def _activity(self) -> None:
+        if self.on_activity is not None:
+            self.on_activity()
+
+    def _decode(self, event: ServerSentEvent) -> _T:
+        try:
+            payload: Any = json.loads(event.data)
+        except json.JSONDecodeError as exc:
+            raise APIResponseValidationError(self.response, event.data, message="Malformed server-sent event") from exc
+        try:
+            return self._adapter.validate_python(payload)
+        except pydantic.ValidationError as exc:
+            raise APIResponseValidationError(self.response, payload, message=validation_summary(exc)) from exc
+
+
+class Stream(_StreamBase[_T]):
+    """A synchronous stream of decoded events.
+
+    Iterate it to receive events. Close it, or use it as a context manager, to release the connection::
+
+        with client.event.subscribe() as events:
+            for event in events:
+                ...
+    """
+
+    def __init__(self, response: httpx.Response, adapter: pydantic.TypeAdapter[_T]) -> None:
+        super().__init__(response, adapter)
+        self._iterator: Generator[_T, None, None] = self._events()
+
+    def __iter__(self) -> Iterator[_T]:
+        return self._iterator
+
+    def __next__(self) -> _T:
+        return next(self._iterator)
+
+    def _events(self) -> Generator[_T, None, None]:
+        decoder = _Decoder()
+        try:
+            splitter = _LineSplitter()
+            for chunk in self.response.iter_text():
+                self._activity()
+                for line in splitter.feed(chunk):
+                    if (event := decoder.feed_line(line)) is not None:
+                        yield self._decode(event)
+            for line in splitter.flush():
+                if (event := decoder.feed_line(line)) is not None:
+                    yield self._decode(event)
+        except (httpx.TransportError, ValueError) as exc:
+            if isinstance(exc, ValueError):
+                raise APIResponseValidationError(self.response, None, message=str(exc)) from exc
+            raise APIConnectionError(request=self.response.request, message=f"Stream interrupted: {exc}") from exc
+        finally:
+            self.response.close()
+
+    def close(self) -> None:
+        """Closes the underlying connection."""
+        self._iterator.close()
+        self.response.close()
+
+    def interrupt(self) -> None:
+        """Unblocks a read in progress on another thread, which then ends with :class:`APIConnectionError`.
+
+        ``close`` must run on the iterating thread. Call this from any other thread first to wake it.
+        """
+        network_stream: Any = self.response.extensions.get("network_stream")
+        sock: Any = network_stream.get_extra_info("socket") if network_stream is not None else None
+        if isinstance(sock, socket.socket):
+            with contextlib.suppress(OSError):
+                sock.shutdown(socket.SHUT_RDWR)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class AsyncStream(_StreamBase[_T]):
+    """An asynchronous stream of decoded events.
+
+    Iterate it with ``async for``. Close it, or use it as an async context manager, to release the connection::
+
+        async with await client.event.subscribe() as events:
+            async for event in events:
+                ...
+    """
+
+    def __init__(self, response: httpx.Response, adapter: pydantic.TypeAdapter[_T]) -> None:
+        super().__init__(response, adapter)
+        self._iterator: AsyncGenerator[_T, None] = self._events()
+
+    def __aiter__(self) -> AsyncIterator[_T]:
+        return self._iterator
+
+    async def __anext__(self) -> _T:
+        return await self._iterator.__anext__()
+
+    async def _events(self) -> AsyncGenerator[_T, None]:
+        decoder = _Decoder()
+        try:
+            splitter = _LineSplitter()
+            async for chunk in self.response.aiter_text():
+                self._activity()
+                for line in splitter.feed(chunk):
+                    if (event := decoder.feed_line(line)) is not None:
+                        yield self._decode(event)
+            for line in splitter.flush():
+                if (event := decoder.feed_line(line)) is not None:
+                    yield self._decode(event)
+        except (httpx.TransportError, ValueError) as exc:
+            if isinstance(exc, ValueError):
+                raise APIResponseValidationError(self.response, None, message=str(exc)) from exc
+            raise APIConnectionError(request=self.response.request, message=f"Stream interrupted: {exc}") from exc
+        finally:
+            await self.response.aclose()
+
+    async def close(self) -> None:
+        """Closes the underlying connection."""
+        await self._iterator.aclose()
+        await self.response.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()

opencode/_types.py

@@ -0,0 +1,77 @@
+"""Shared typing helpers used by the client and the generated code."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Annotated, Any, Final, Literal, TypeAlias, TypeVar
+
+import httpx
+import pydantic
+from typing_extensions import override
+
+__all__ = [
+    "NOT_GIVEN",
+    "Body",
+    "Headers",
+    "NotGiven",
+    "OpenEnum",
+    "Query",
+    "Timeout",
+]
+
+_T = TypeVar("_T")
+
+
+class NotGiven:
+    """Marks an argument that was not passed, as opposed to one passed as ``None``.
+
+    The OpenCode API distinguishes a field that is absent from a field set to ``null``, so optional
+    arguments default to ``NOT_GIVEN`` and are left out of the request entirely.
+    """
+
+    _instance: NotGiven | None = None
+
+    def __new__(cls) -> NotGiven:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    @override
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+    @override
+    def __reduce__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN: Final = NotGiven()
+
+Headers: TypeAlias = Mapping[str, str | NotGiven]
+"""Extra request headers. A ``NOT_GIVEN`` value removes a header the client would otherwise send."""
+
+Query: TypeAlias = Mapping[str, object]
+"""Extra query parameters, encoded the same way as generated parameters."""
+
+Body: TypeAlias = Mapping[str, object]
+"""Extra JSON body fields, merged over the generated body."""
+
+Timeout: TypeAlias = float | httpx.Timeout | None
+"""A timeout in seconds, an ``httpx.Timeout``, or ``None`` to wait forever."""
+
+
+def _accept_unknown_value(value: Any, handler: pydantic.ValidatorFunctionWrapHandler) -> Any:
+    try:
+        return handler(value)
+    except pydantic.ValidationError:
+        # Newer servers may add enum members. Keep the raw value instead of failing the whole response.
+        if isinstance(value, (str, int, float, bool)):
+            return value
+        raise
+
+
+OpenEnum = Annotated[_T, pydantic.WrapValidator(_accept_unknown_value)]
+"""A ``Literal`` enum that type-checks strictly but accepts values added by newer servers at runtime."""