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

opencode/resources/shell.py

@@ -41,9 +41,9 @@ class ShellResource(SyncAPIResource):
         List currently running shell commands for a location. Exited commands are not included.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell``
         """
@@ -81,9 +81,9 @@ class ShellResource(SyncAPIResource):
         Spawn one non-interactive shell command for a location. Combined stdout/stderr is captured to a file pageable via output.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``POST /api/shell``
         """
@@ -119,10 +119,10 @@ class ShellResource(SyncAPIResource):
         Get one shell command, including its status and exit code once exited.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ShellNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ShellNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell/:id``
         """
@@ -159,10 +159,10 @@ class ShellResource(SyncAPIResource):
         Page through captured combined output by absolute byte cursor.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ShellNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ShellNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell/:id/output``
         """
@@ -197,9 +197,9 @@ class ShellResource(SyncAPIResource):
         Terminate and remove one shell command and its retained output.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``DELETE /api/shell/:id``
         """
@@ -234,9 +234,9 @@ class AsyncShellResource(AsyncAPIResource):
         List currently running shell commands for a location. Exited commands are not included.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell``
         """
@@ -274,9 +274,9 @@ class AsyncShellResource(AsyncAPIResource):
         Spawn one non-interactive shell command for a location. Combined stdout/stderr is captured to a file pageable via output.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``POST /api/shell``
         """
@@ -312,10 +312,10 @@ class AsyncShellResource(AsyncAPIResource):
         Get one shell command, including its status and exit code once exited.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ShellNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ShellNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell/:id``
         """
@@ -352,10 +352,10 @@ class AsyncShellResource(AsyncAPIResource):
         Page through captured combined output by absolute byte cursor.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ShellNotFoundError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ShellNotFoundError: The server answered 404.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/shell/:id/output``
         """
@@ -390,9 +390,9 @@ class AsyncShellResource(AsyncAPIResource):
         Terminate and remove one shell command and its retained output.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``DELETE /api/shell/:id``
         """

opencode/resources/skill.py

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

opencode/resources/vcs.py

@@ -43,9 +43,9 @@ class VcsBranchResource(SyncAPIResource):
         List local and remote branches available at the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs/branch``
         """
@@ -71,6 +71,7 @@ class VcsResource(SyncAPIResource):
 
     @cached_property
     def branch(self) -> VcsBranchResource:
+        """Operations under ``client.vcs.branch``."""
         return VcsBranchResource(self._client)
 
     def init(
@@ -88,12 +89,12 @@ class VcsResource(SyncAPIResource):
         Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ConflictError
-          VcsInitNotSupportedError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ConflictError: The server answered 409.
+          VcsInitNotSupportedError: The server answered 501.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/vcs/init``
         """
@@ -124,9 +125,9 @@ class VcsResource(SyncAPIResource):
         Get current and default branch information for the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs``
         """
@@ -160,10 +161,10 @@ class VcsResource(SyncAPIResource):
         Infer a local review base from named branch creation history, or the repository default only when currently on that branch. Returns null before the first commit or when the provider lacks base metadata; ambiguous Git history requires an explicit base on diff requests.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/vcs/base``
         """
@@ -197,9 +198,9 @@ class VcsResource(SyncAPIResource):
         List uncommitted working-copy changes relative to the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs/status``
         """
@@ -236,10 +237,10 @@ class VcsResource(SyncAPIResource):
         Diff HEAD to the working copy (working), the base merge-base to the working copy (branch), or the base merge-base to HEAD (committed). Omitting base preserves repository-default comparison; supplying it overrides the comparison without saving it.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/vcs/diff``
         """
@@ -279,9 +280,9 @@ class AsyncVcsBranchResource(AsyncAPIResource):
         List local and remote branches available at the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs/branch``
         """
@@ -307,6 +308,7 @@ class AsyncVcsResource(AsyncAPIResource):
 
     @cached_property
     def branch(self) -> AsyncVcsBranchResource:
+        """Operations under ``client.vcs.branch``."""
         return AsyncVcsBranchResource(self._client)
 
     async def init(
@@ -324,12 +326,12 @@ class AsyncVcsResource(AsyncAPIResource):
         Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ConflictError
-          VcsInitNotSupportedError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ConflictError: The server answered 409.
+          VcsInitNotSupportedError: The server answered 501.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/vcs/init``
         """
@@ -360,9 +362,9 @@ class AsyncVcsResource(AsyncAPIResource):
         Get current and default branch information for the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs``
         """
@@ -396,10 +398,10 @@ class AsyncVcsResource(AsyncAPIResource):
         Infer a local review base from named branch creation history, or the repository default only when currently on that branch. Returns null before the first commit or when the provider lacks base metadata; ambiguous Git history requires an explicit base on diff requests.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/vcs/base``
         """
@@ -433,9 +435,9 @@ class AsyncVcsResource(AsyncAPIResource):
         List uncommitted working-copy changes relative to the requested location.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
 
         ``GET /api/vcs/status``
         """
@@ -472,10 +474,10 @@ class AsyncVcsResource(AsyncAPIResource):
         Diff HEAD to the working copy (working), the base merge-base to the working copy (branch), or the base merge-base to HEAD (committed). Omitting base preserves repository-default comparison; supplying it overrides the comparison without saving it.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/vcs/diff``
         """

opencode/resources/voice.py

@@ -40,10 +40,10 @@ class VoiceResource(SyncAPIResource):
         This endpoint is experimental in OpenCode and may change without notice.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/experimental/voice/session``
         """
@@ -86,10 +86,10 @@ class AsyncVoiceResource(AsyncAPIResource):
         This endpoint is experimental in OpenCode and may change without notice.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/experimental/voice/session``
         """

opencode/resources/websearch.py

@@ -37,10 +37,10 @@ class WebsearchResource(SyncAPIResource):
         Return the registered web search providers.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/websearch/provider``
         """
@@ -76,10 +76,10 @@ class WebsearchResource(SyncAPIResource):
         Run one web search through the selected provider. Specify a provider to override the configured default.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/websearch``
         """
@@ -118,10 +118,10 @@ class AsyncWebsearchResource(AsyncAPIResource):
         Return the registered web search providers.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``GET /api/websearch/provider``
         """
@@ -157,10 +157,10 @@ class AsyncWebsearchResource(AsyncAPIResource):
         Run one web search through the selected provider. Specify a provider to override the configured default.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          LocationNotFoundError
-          ServiceUnavailableError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          LocationNotFoundError: The server answered 404.
+          ServiceUnavailableError: The server answered 503.
 
         ``POST /api/websearch``
         """

opencode/resources/worktree.py

@@ -37,9 +37,9 @@ class WorktreeResource(SyncAPIResource):
         Return the project's saved worktree inventory without loading configuration or running discovery.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``GET /api/worktree``
         """
@@ -77,10 +77,10 @@ class WorktreeResource(SyncAPIResource):
         Load the project's canonical configuration, create a local worktree using its selected strategy, then run the project's setup script.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``POST /api/worktree``
         """
@@ -122,10 +122,10 @@ class WorktreeResource(SyncAPIResource):
         Load the project's canonical configuration and remove a saved worktree using its recorded strategy.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``DELETE /api/worktree``
         """
@@ -156,10 +156,10 @@ class WorktreeResource(SyncAPIResource):
         Load the project's canonical configuration, discover worktrees across known checkout roots using all available strategies, and reconcile saved state.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``POST /api/worktree/refresh``
         """
@@ -194,9 +194,9 @@ class AsyncWorktreeResource(AsyncAPIResource):
         Return the project's saved worktree inventory without loading configuration or running discovery.
 
         Raises:
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``GET /api/worktree``
         """
@@ -234,10 +234,10 @@ class AsyncWorktreeResource(AsyncAPIResource):
         Load the project's canonical configuration, create a local worktree using its selected strategy, then run the project's setup script.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``POST /api/worktree``
         """
@@ -279,10 +279,10 @@ class AsyncWorktreeResource(AsyncAPIResource):
         Load the project's canonical configuration and remove a saved worktree using its recorded strategy.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``DELETE /api/worktree``
         """
@@ -313,10 +313,10 @@ class AsyncWorktreeResource(AsyncAPIResource):
         Load the project's canonical configuration, discover worktrees across known checkout roots using all available strategies, and reconcile saved state.
 
         Raises:
-          WorktreeError
-          InvalidRequestError
-          UnauthorizedError
-          ProjectNotFoundError
+          WorktreeError: The server answered 400.
+          InvalidRequestError: The server answered 400.
+          UnauthorizedError: The server answered 401.
+          ProjectNotFoundError: The server answered 404.
 
         ``POST /api/worktree/refresh``
         """

{opencode_python_sdk-0.1.0.dist-info → opencode_python_sdk-0.1.2.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.0
+Version: 0.1.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://github.com/shrijayan/opencode-python-sdk#readme
+Project-URL: Documentation, https://shrijayan.github.io/opencode-python-sdk/
 Project-URL: Repository, https://github.com/shrijayan/opencode-python-sdk
 Project-URL: Issues, https://github.com/shrijayan/opencode-python-sdk/issues
 Project-URL: Changelog, https://github.com/shrijayan/opencode-python-sdk/blob/main/CHANGELOG.md
@@ -31,16 +31,21 @@ 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: pty
+Requires-Dist: websockets<17,>=14; extra == 'pty'
 Description-Content-Type: text/markdown
 
 # opencode-python-sdk
 
 [![CI](https://github.com/shrijayan/opencode-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/shrijayan/opencode-python-sdk/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/opencode-python-sdk.svg)](https://pypi.org/project/opencode-python-sdk/)
+[![Docs](https://img.shields.io/badge/docs-shrijayan.github.io-d9730d)](https://shrijayan.github.io/opencode-python-sdk/)
 [![Python](https://img.shields.io/pypi/pyversions/opencode-python-sdk.svg)](https://pypi.org/project/opencode-python-sdk/)
 
 Typed Python client for the [OpenCode](https://github.com/anomalyco/opencode) 2.x server API.
 
+**Documentation: <https://shrijayan.github.io/opencode-python-sdk/>**
+
 > **Unofficial, community-maintained.** This package is not affiliated with or endorsed by the OpenCode team.
 > If the OpenCode maintainers want to take it over, we are happy to transfer this repository and the `opencode-python-sdk`
 > name on PyPI. Open an issue and we will hand it over.
@@ -201,6 +206,27 @@ Events are typed (`SessionCreatedEvent`, `SessionTextDeltaEvent`, and so on). Ev
 not know arrive as `UnknownEvent` with all their fields kept. Streams apply only the connect timeout by default, since
 they stay open between events.
 
+## Terminals
+
+`client.pty.attach()` opens an interactive connection to a PTY over a WebSocket. It needs the `pty` extra:
+`pip install "opencode-python-sdk[pty]"`.
+
+```python
+pty = client.pty.create(command="/bin/sh").data
+with client.pty.attach(pty.id) as term:
+    term.resize(120, 40)
+    term.send("echo hi\n")
+    for chunk in term:  # output bytes, until the shell exits
+        print(chunk.decode(errors="replace"), end="")
+```
+
+`recv(timeout=...)` reads one chunk and returns `None` once the terminal has ended. `term.cursor` holds the output
+position to pass as `cursor=` when reattaching; `cursor=-1` skips the replay of earlier output. Persistent terminals
+work the same way through `client.experimental.persistent_pty.attach(pty_id, role=..., takeover=...)`. The async
+client returns `AsyncPtyConnection` (asyncio only): `async with await client.pty.attach(...) as term`. A connection
+the server refuses or closes abnormally raises `PtyConnectionError`. See
+[`examples/terminal.py`](examples/terminal.py) for a full TTY bridge.
+
 ## Errors
 
 Every error derives from `opencode.OpencodeError`. Errors the server declares are raised as their own class, with a