opencode-python-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/.gitignore

@@ -14,3 +14,7 @@ htmlcov/
 codegen/extract/node_modules/
 codegen/extract/.cache/
 .DS_Store
+
+# MkDocs output
+site/
+.cache/

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/PKG-INFO

@@ -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

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/README.md

@@ -2,10 +2,13 @@
 
 [![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.
@@ -166,6 +169,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

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/pyproject.toml

@@ -34,11 +34,16 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/shrijayan/opencode-python-sdk"
-Documentation = "https://github.com/shrijayan/opencode-python-sdk#readme"
+Documentation = "https://shrijayan.github.io/opencode-python-sdk/"
 Repository = "https://github.com/shrijayan/opencode-python-sdk"
 Issues = "https://github.com/shrijayan/opencode-python-sdk/issues"
 Changelog = "https://github.com/shrijayan/opencode-python-sdk/blob/main/CHANGELOG.md"
 
+[project.optional-dependencies]
+pty = [
+    "websockets>=14,<17",
+]
+
 [dependency-groups]
 dev = [
   "mypy>=1.18",
@@ -48,6 +53,11 @@ dev = [
   "respx>=0.22",
   "ruff>=0.14",
   "trio>=0.31",
+  "websockets>=14",
+]
+docs = [
+    "mkdocs-material[imaging]>=9.6",
+    "mkdocstrings[python]>=0.30",
 ]
 
 [build-system]
@@ -93,6 +103,7 @@ src = ["src", "tests", "codegen"]
 select = [
   "B",   # bugbear
   "C4",  # comprehensions
+  "D1",  # missing docstrings (public modules only; tests/test_docs_coverage.py covers the private runtime modules)
   "E",   # pycodestyle errors
   "F",   # pyflakes
   "FA",  # future annotations
@@ -107,6 +118,8 @@ select = [
   "W",   # pycodestyle warnings
 ]
 ignore = [
+  "D105",   # magic methods
+  "D107",   # __init__: arguments are documented on the class
   "E501",   # line length is handled by the formatter
   "RUF022", # __all__ keeps a readable, grouped order
 ]
@@ -116,10 +129,12 @@ ignore = [
 "src/opencode/types/**" = ["E741", "TC"]
 "src/opencode/resources/**" = ["TC"]
 "src/opencode/_errors.py" = ["TC"]
-"codegen/**" = ["T20"]
-"scripts/**" = ["T20"]
-"examples/**" = ["T20"]
-"tests/**" = ["E501", "TC"]
+# D1 applies to the published package only.
+"codegen/**" = ["T20", "D1"]
+"scripts/**" = ["T20", "D1"]
+"examples/**" = ["T20", "D1"]
+"tests/**" = ["E501", "TC", "D1"]
+"docs/**" = ["D1"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["opencode", "codegen"]

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/src/opencode/__init__.py

@@ -75,6 +75,7 @@ from ._exceptions import (
 )
 from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
+from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
 from ._server import AsyncOpencodeServer, OpencodeServer, ServerStartError
 from ._streaming import AsyncStream, Stream
 from ._types import NOT_GIVEN, NotGiven
@@ -97,6 +98,7 @@ __all__ = [
     "AsyncOpencode",
     "AsyncOpencodeServer",
     "AsyncPaginator",
+    "AsyncPtyConnection",
     "AsyncStream",
     "AuthenticationError",
     "BadRequestError",
@@ -111,6 +113,8 @@ __all__ = [
     "OpencodeError",
     "OpencodeServer",
     "PermissionDeniedError",
+    "PtyConnection",
+    "PtyConnectionError",
     "RateLimitError",
     "ServerStartError",
     "ServiceUnavailableError",

{opencode_python_sdk-0.1.0 → opencode_python_sdk-0.1.2}/src/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"