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

opencode/_exceptions.py

@@ -147,47 +147,69 @@ class APIStatusError(APIError):
 
 
 class BadRequestError(APIStatusError):
+    """The server rejected the request as malformed (400)."""
+
     status = 400
 
 
 class AuthenticationError(APIStatusError):
+    """The password was missing or wrong (401)."""
+
     status = 401
 
 
 class PermissionDeniedError(APIStatusError):
+    """The request is not allowed (403)."""
+
     status = 403
 
 
 class NotFoundError(APIStatusError):
+    """The requested resource does not exist (404)."""
+
     status = 404
 
 
 class ConflictError(APIStatusError):
+    """The request conflicts with the current state, for example a busy session (409)."""
+
     status = 409
     tag = "ConflictError"
 
 
 class ContentTooLargeError(APIStatusError):
+    """The request body is too large (413)."""
+
     status = 413
 
 
 class UnprocessableEntityError(APIStatusError):
+    """The request was well formed but could not be processed (422)."""
+
     status = 422
 
 
 class RateLimitError(APIStatusError):
+    """Too many requests (429). Retried automatically, honoring ``Retry-After``."""
+
     status = 429
 
 
 class InternalServerError(APIStatusError):
+    """The server failed (500, and the base class for every 5xx)."""
+
     status = 500
 
 
 class NotImplementedServerError(InternalServerError):
+    """The server does not implement this endpoint (501)."""
+
     status = 501
 
 
 class ServiceUnavailableError(InternalServerError):
+    """The server is temporarily unavailable (503). Retried automatically."""
+
     status = 503
     tag = "ServiceUnavailableError"
 

opencode/_server.py

@@ -109,10 +109,12 @@ class OpencodeServer:
 
     @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:
@@ -291,18 +293,22 @@ class AsyncOpencodeServer:
 
     @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(
@@ -312,10 +318,12 @@ class AsyncOpencodeServer:
         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:

opencode/resources/agent.py

@@ -38,9 +38,9 @@ class AgentResource(SyncAPIResource):
         Retrieve currently registered agents.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/agent``
         """
@@ -75,10 +75,10 @@ class AgentResource(SyncAPIResource):
         Retrieve a single currently registered agent.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          AgentNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          AgentNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/agent/:agentID``
         """
@@ -116,9 +116,9 @@ class AsyncAgentResource(AsyncAPIResource):
         Retrieve currently registered agents.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/agent``
         """
@@ -153,10 +153,10 @@ class AsyncAgentResource(AsyncAPIResource):
         Retrieve a single currently registered agent.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          AgentNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          AgentNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/agent/:agentID``
         """

opencode/resources/command.py

@@ -35,9 +35,9 @@ class CommandResource(SyncAPIResource):
         Retrieve currently registered commands.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/command``
         """
@@ -75,9 +75,9 @@ class AsyncCommandResource(AsyncAPIResource):
         Retrieve currently registered commands.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/command``
         """

opencode/resources/config.py

@@ -37,9 +37,9 @@ class ConfigResource(SyncAPIResource):
         Return configuration documents and discovery sources for the requested location, from lowest to highest priority.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/config``
         """
@@ -72,9 +72,9 @@ class ConfigResource(SyncAPIResource):
         Return shells available to terminal and agent execution.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/config/shell``
         """
@@ -109,9 +109,9 @@ class ConfigResource(SyncAPIResource):
         This endpoint is experimental in OpenCode and may change without notice.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``PATCH /api/experimental/config``
         """
@@ -146,9 +146,9 @@ class AsyncConfigResource(AsyncAPIResource):
         Return configuration documents and discovery sources for the requested location, from lowest to highest priority.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/config``
         """
@@ -181,9 +181,9 @@ class AsyncConfigResource(AsyncAPIResource):
         Return shells available to terminal and agent execution.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/config/shell``
         """
@@ -218,9 +218,9 @@ class AsyncConfigResource(AsyncAPIResource):
         This endpoint is experimental in OpenCode and may change without notice.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``PATCH /api/experimental/config``
         """

opencode/resources/credential.py

@@ -38,8 +38,8 @@ class CredentialResource(SyncAPIResource):
         List every stored integration credential, including its secret value.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/credential``
         """
@@ -77,9 +77,9 @@ class CredentialResource(SyncAPIResource):
         Store an integration credential. It becomes the integration's active credential unless activate is false and the integration already has one. Fails with a conflict when the requested ID already exists.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ConflictError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ConflictError: The server answered 409.
 
         ``POST /api/credential``
         """
@@ -121,8 +121,8 @@ class CredentialResource(SyncAPIResource):
         Update a stored credential label.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``PATCH /api/credential/:credentialID``
         """
@@ -153,8 +153,8 @@ class CredentialResource(SyncAPIResource):
         Activate a stored integration credential.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``POST /api/credential/:credentialID/activate``
         """
@@ -184,8 +184,8 @@ class CredentialResource(SyncAPIResource):
         Remove a stored integration credential.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``DELETE /api/credential/:credentialID``
         """
@@ -218,8 +218,8 @@ class AsyncCredentialResource(AsyncAPIResource):
         List every stored integration credential, including its secret value.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/credential``
         """
@@ -257,9 +257,9 @@ class AsyncCredentialResource(AsyncAPIResource):
         Store an integration credential. It becomes the integration's active credential unless activate is false and the integration already has one. Fails with a conflict when the requested ID already exists.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ConflictError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ConflictError: The server answered 409.
 
         ``POST /api/credential``
         """
@@ -301,8 +301,8 @@ class AsyncCredentialResource(AsyncAPIResource):
         Update a stored credential label.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``PATCH /api/credential/:credentialID``
         """
@@ -333,8 +333,8 @@ class AsyncCredentialResource(AsyncAPIResource):
         Activate a stored integration credential.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``POST /api/credential/:credentialID/activate``
         """
@@ -364,8 +364,8 @@ class AsyncCredentialResource(AsyncAPIResource):
         Remove a stored integration credential.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``DELETE /api/credential/:credentialID``
         """

opencode/resources/debug.py

@@ -36,8 +36,8 @@ class DebugLocationResource(SyncAPIResource):
         List locations currently loaded by the server.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/debug/location``
         """
@@ -70,8 +70,8 @@ class DebugLocationResource(SyncAPIResource):
         Dispose the requested location's cached services so its next use boots them fresh.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``DELETE /api/debug/location``
         """
@@ -94,6 +94,7 @@ class DebugResource(SyncAPIResource):
 
     @cached_property
     def location(self) -> DebugLocationResource:
+        """Operations under ``client.debug.location``."""
         return DebugLocationResource(self._client)
 
 
@@ -113,8 +114,8 @@ class AsyncDebugLocationResource(AsyncAPIResource):
         List locations currently loaded by the server.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/debug/location``
         """
@@ -147,8 +148,8 @@ class AsyncDebugLocationResource(AsyncAPIResource):
         Dispose the requested location's cached services so its next use boots them fresh.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``DELETE /api/debug/location``
         """
@@ -171,4 +172,5 @@ class AsyncDebugResource(AsyncAPIResource):
 
     @cached_property
     def location(self) -> AsyncDebugLocationResource:
+        """Operations under ``client.debug.location``."""
         return AsyncDebugLocationResource(self._client)

opencode/resources/event.py

@@ -32,8 +32,8 @@ class EventResource(SyncAPIResource):
         Subscribe to native events and plugin RPC events across all server locations. Volatile by contract: a slow consumer overflows and fails the stream, and events during disconnection are missed.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/event``
         """
@@ -66,8 +66,8 @@ class AsyncEventResource(AsyncAPIResource):
         Subscribe to native events and plugin RPC events across all server locations. Volatile by contract: a slow consumer overflows and fails the stream, and events during disconnection are missed.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
 
         ``GET /api/event``
         """