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

{opencode_python_sdk-0.1.1.dist-info → opencode_python_sdk-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencode-python-sdk
-Version: 0.1.1
+Version: 0.1.3
 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/
@@ -31,6 +31,8 @@ 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
@@ -204,6 +206,103 @@ 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.
 
+### Shared event stream
+
+`client.events` shares one connection among every subscriber, like `client.event` in the TypeScript client. The
+connection opens with the first subscriber and closes when the last one leaves. Each subscriber has its own queue of
+up to 4096 events; one that falls further behind fails with `EventOverflowError` without affecting the others. The
+latest `server.connected` event is replayed to subscribers that join later.
+
+```python
+from opencode.types import SessionIdleEvent
+
+with client.events.of_type(SessionIdleEvent).for_session(session.id) as idle:
+    client.session.prompt(session.id, text="Hello")
+    event = idle.get(timeout=300)  # typed as SessionIdleEvent
+```
+
+- Filters chain: `of_type(*classes)` narrows the yielded type, `for_session(id)` keeps one session's events, and
+  `where(predicate)` takes any test. Entering the `with` block joins the stream, so nothing published after that is
+  missed.
+- `subscribe(on_activity=callback)` calls `callback` for every chunk received, keepalive comments included, as a
+  liveness signal.
+- `close()` (or leaving the `with` block) ends the subscription, also from another thread. In async code, cancel a wait
+  with `anyio.fail_after`, `asyncio.timeout` or a trio cancel scope; the subscription stays usable.
+- Reconnection is opt-in: `EventHub(client, reconnect=True)` (or `AsyncEventHub`, or a `Reconnect(...)` policy) reopens
+  the connection with exponential backoff after connection errors, 5xx and 429. Subscribers see `server.connected`
+  once. **The stream is volatile**: events published while disconnected are lost, so re-read state through the API
+  after a reconnect when it matters.
+
+The async hub works the same way under asyncio and trio:
+
+```python
+async with client.events.for_session(session.id) as events:
+    async for event in events:
+        print(event.type)
+```
+
+`client.event.subscribe()` still opens a dedicated connection.
+
+### Plugin RPC
+
+Declare a plugin RPC once as a class, then call it with typed inputs and outputs:
+
+```python
+from pydantic import BaseModel
+from opencode import RpcCallError, RpcDefinition, rpc_event, rpc_method
+
+
+class AddInput(BaseModel):
+    amount: int
+
+
+class Total(BaseModel):
+    total: int
+
+
+class Counter(RpcDefinition, id="counter"):
+    add = rpc_method(AddInput, Total)
+    reset = rpc_method(None, Total)
+    changed = rpc_event(Total)
+
+
+counter = client.rpc(Counter)
+try:
+    print(counter.call(Counter.add, AddInput(amount=2)).total)
+except RpcCallError as error:
+    print(error.type, error.message, error.data)
+
+with counter.subscribe(Counter.changed) as changes:  # only rpc.counter.changed, with validated data
+    for change in changes:
+        print(change.data.total)
+```
+
+Any type pydantic validates works for inputs, outputs and event data. `rpc_method(..., errors={"not_found": Model})`
+validates the `data` of declared errors. Failures raise `RpcCallError`; crashes and outputs that do not match the
+declared type raise `RpcCallInternalError`. `counter.events()` yields every raw event of the RPC. The untyped
+`client.rpc.call(rpc_id, method, input=...)` is still available.
+
+## 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.1.dist-info → opencode_python_sdk-0.1.3.dist-info}/RECORD

@@ -1,16 +1,19 @@
 opencode/.generated.json,sha256=QNCFazAYhcwsGf0l4A2EeSpm2HOM7TRBE648Zyoeq_s,1383
-opencode/__init__.py,sha256=UGraxBEfh90WBSAQ7ccwxJsXE5AxYDDTyKlcXhqzykc,4106
+opencode/__init__.py,sha256=-jyJAzJw0GVbe4ZgtdAIiblDo2Xl5EZWk_22hOqmD2Y,5243
 opencode/_base_client.py,sha256=3BwhIXL-cFGoRUuwDzTeFH21O7pihUR5CryOlS1Wylo,20108
-opencode/_client.py,sha256=ip-UhWyHTViMnqgX3jhUmCkscahFtXnIWM2Jd2zn61I,6723
+opencode/_client.py,sha256=3zY2lGLi_9FBpbG1UIWmklgSn86sJJZv0Wf7Z7sWNDk,7687
 opencode/_constants.py,sha256=-B_D8RHElL4mYN__WVf4bag4D12dJHbL69_EMfi7bXo,1132
 opencode/_errors.py,sha256=dWjsyGV0aDBKsvJrGNKGJn41Yue66yBBwGTT2pTV7E8,16431
+opencode/_events.py,sha256=KwVvFMyPEBy-wopfbTcu7nDWwgo0zqSdWpuTmTl3dFc,30099
 opencode/_exceptions.py,sha256=kqQiaSM6zbfyiXXddwapIymW7J61ZlAa767Yko5Y9EI,8720
 opencode/_models.py,sha256=2esvD2CmslOHCbuLNkN0sGDcgMAqeoMmB7hZMPzo1uA,1988
 opencode/_pagination.py,sha256=uvB-0IwfkGqbYIYiUW_ax_oAE-ldZJSWHtjluVcZlNk,7052
+opencode/_pty.py,sha256=wdqBF7K40ikzas8i203pem2iov8nbgYDC-RqH6ZX41E,23429
 opencode/_qs.py,sha256=8EWbLzd-iLComngGRyO95f_z76j4tUeBihYJdHI5NP8,3643
 opencode/_resource.py,sha256=ovuG85mWcuXNTu5m6H9FKPN2rrD5o52oRFAGBHimPyg,1263
+opencode/_rpc.py,sha256=s3E_6Abfbt4nRysaK-J0RFt5xx8ZCdolRJCJad2UayI,17578
 opencode/_server.py,sha256=O-yVWU-v7HDJuVav1xXTil96BtvvbYMsHm1zLhneWKk,12849
-opencode/_streaming.py,sha256=OJJNoFdvx6degaVnnQNhv9augigImoYjGzEdnI3FVkk,7905
+opencode/_streaming.py,sha256=TfnfZaNucjLrpfOB9m1i_sRtjYoACztTflavrhwvnDE,8861
 opencode/_types.py,sha256=Z8bYxzpZhPRtisvPUv9R5g4oBlC23iXR70fFzReTOc0,2194
 opencode/_unions.py,sha256=dW0dTmP2QK2lL6RhyK2YsjD2yNbO8Ah6pk-i5ySW3lo,1518
 opencode/_version.py,sha256=zNErHu8z_g6ScOeYcO8QAiktg036FVPaUiIIZefeoLU,259
@@ -22,7 +25,7 @@ opencode/resources/config.py,sha256=pnRi7pG8mJqO0Xp6dnh0a8V767Dy5Zvbr8wvsaBqaIc,
 opencode/resources/credential.py,sha256=6X-IGP8uN4WVVhCFoLPWnMjfQ6dW25wms1R3YIFNggA,12018
 opencode/resources/debug.py,sha256=gdKIJ1jSsD6mPaI_Qd3pmE5J5URIyTWZAppfulejf-c,5483
 opencode/resources/event.py,sha256=UntmSEmFRWjSIjWvP-OkXfc-S1cpflwHyp0E2ZYGCBk,2694
-opencode/resources/experimental.py,sha256=JdRajS5r4k7AjEX9Xp_Y2iGKndSKdDsJZK1nq-PM0kU,27961
+opencode/resources/experimental.py,sha256=qjaMkBfI7aOwLWeQWlXmVtYwM1VIilry27kyCVcC1B0,28058
 opencode/resources/file.py,sha256=leXPuTdE44BUrpIqDZ3MAAjSgv8_aKtyDROKsDZuVSE,12943
 opencode/resources/form.py,sha256=ToPVrHbTlyUZyNrMaH3bkcfqEjvIF1UlL7CQHT2VjyE,2967
 opencode/resources/generate.py,sha256=koElRVSJtRrP6yok3hsYOJon8MMinku8IB8zCS0MImM,3755
@@ -36,7 +39,7 @@ opencode/resources/permission.py,sha256=4J-eysN90zWIAdrXbzXfR4FvPlsyIgwvXPmRMI46
 opencode/resources/plugin.py,sha256=CaZCUCdU4iAxgkZhYr6QntPmdAcJuBlip55q3q5rplw,8159
 opencode/resources/project.py,sha256=BJkgHswUoE2UZkWYQzTg1KyT8L5l5WNlJhlBdVZUMso,6114
 opencode/resources/provider.py,sha256=H7hdaJZ1ToyEGoSr13qUcAV-Rd1bd-pUSi6GJlY8B7A,6134
-opencode/resources/pty.py,sha256=gjXxuppy8R70PaN0x-ixv7X7s-U2XPER6Us4t4Getco,17480
+opencode/resources/pty.py,sha256=ttlB4iwI-QyppsEClPrsdkvEtLFsrxOF5-B1iH-4QY0,17537
 opencode/resources/reference.py,sha256=7Y9pPZYVoIaN8k3qwYY8-h54vBUdxI6lSBgJYmowq3I,3089
 opencode/resources/rpc.py,sha256=AExEcrxgJrreOqav4k_edNcrg3Uqa9p7lilnvxVMqfo,3630
 opencode/resources/server.py,sha256=tNuofw5_BMSCGTalkUvOc5--hn43mSVBU0HANK-L8zo,6932
@@ -49,7 +52,7 @@ opencode/resources/websearch.py,sha256=xr1vaS6dwPsSZJUtVSkRtqtzZuoP9xg_cr1bBpeKo
 opencode/resources/worktree.py,sha256=mohf9rIm4PPJTMbJmieygQkaC8rc7LgF0GO4u-2D9OU,10950
 opencode/types/__init__.py,sha256=5JEAe89RPSwJw1yz0kufBxtEJgRsMpZXj7KTbzGX45A,60935
 opencode/types/_generated.py,sha256=c3zBAfVpZGJ9TX4FqrMZASmoxRntel_QzVuP85BOJwU,235015
-opencode_python_sdk-0.1.1.dist-info/METADATA,sha256=i_ELBqCkCafo6tyKdVzcETFFjRDhmDhZi_X8jPJDsQ0,11502
-opencode_python_sdk-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-opencode_python_sdk-0.1.1.dist-info/licenses/LICENSE,sha256=SbiOG1an_-gZ0gwGLS0tsbUnMHA7tYX22FgP1EqzrH4,1093
-opencode_python_sdk-0.1.1.dist-info/RECORD,,
+opencode_python_sdk-0.1.3.dist-info/METADATA,sha256=8bH3l7_tYHkst05cMXdAxJCvpbYHZWxSLKKXR1ItkHE,15746
+opencode_python_sdk-0.1.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+opencode_python_sdk-0.1.3.dist-info/licenses/LICENSE,sha256=SbiOG1an_-gZ0gwGLS0tsbUnMHA7tYX22FgP1EqzrH4,1093
+opencode_python_sdk-0.1.3.dist-info/RECORD,,