continuum-task-server-sdk 1.1.0__py3-none-any.whl

continuum_task_server_sdk-1.1.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.5
+Name: continuum-task-server-sdk
+Version: 1.1.0
+Summary: Python SDK for the Continuum Task Server
+Project-URL: Homepage, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python
+Project-URL: Issues, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python/issues
+Author: Continuum
+License: MIT
+Keywords: continuum,queue,sdk,task,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: websocket-client<2.0,>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Continuum Task Server SDK for Python
+
+Python client for the [Continuum](https://github.com/ContinuumWorkflow) task server. Designed so a 20-line script can stand up a worker that claims queue items, runs your code, and reports results.
+
+- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Defaults to HTTP polling; set ``transport="websocket"`` (or ``CONTINUUM_TRANSPORT=websocket`` in the example) to claim from STOMP ``work.available`` hints instead.
+- **`ContinuumClient`** — thin pythonic client over the management + queue REST APIs (task types, task items, versions, queue, content store).
+- **`ContinuumWebSocketClient`** — synchronous STOMP-over-WebSocket client for the worker hot path (enqueue, claim, heartbeat, status, ``subscribeWork``, durable ``subscribeWait`` / ``ackEvent``).
+
+Requires Python 3.10+.
+
+## Installation
+
+Tagged releases (`v*`) are published to [PyPI](https://pypi.org/project/continuum-task-server-sdk/):
+
+```bash
+pip install continuum-task-server-sdk
+```
+
+Dev and PR builds are still attached to private GitHub Releases. Install those with a token:
+
+```bash
+pip install \
+  "https://${GITHUB_TOKEN}@github.com/ContinuumWorkflow/continuum-task-server-sdk-python/releases/download/v0.1.0/continuum_task_server_sdk-0.1.0-py3-none-any.whl"
+```
+
+`GITHUB_TOKEN` must be a PAT with repo read access.
+
+## Quickstart: build a task server in 20 lines
+
+```python
+import os
+from continuum_task_server import TaskServer
+
+server = TaskServer(
+    base_url=os.environ["CONTINUUM_URL"],
+    api_key=os.environ["CONTINUUM_API_KEY"],
+)
+
+
+@server.task("echo")
+def echo(item):
+    return {"echoed": item.input_data_json}
+
+
+@server.task("greet")
+def greet(item):
+    name = (item.input_data_json or {}).get("name", "world")
+    return {"message": f"hello, {name}"}
+
+
+if __name__ == "__main__":
+    server.run()
+```
+
+Set `CONTINUUM_TRANSPORT=websocket` (and enable Queue API WebSockets) to replace polling with STOMP wake-ups. HTTP polling remains the default.
+
+Run it. The server polls `/api/queue/claim` for `echo` and `greet`, claims items as they become available, runs your handler in a thread, heartbeats while it runs, and:
+
+- **Handler returns** a value → queue item marked `ENDED`, return value JSON-encoded as `outputData` (default `auto_complete=True`).
+- **Handler raises** → queue item marked `KILLED`, error info written to `outputData`.
+
+Press `Ctrl+C` (or send `SIGTERM`) and the server stops polling and waits up to `shutdown_timeout` seconds for in-flight handlers to finish.
+
+### Deferred completion (`auto_complete=False`)
+
+The handler runs under the normal **in-handler** heartbeat (same as any task). When it returns, the server **does not** send `ENDED` and **does not** keep heartbeating: you own the claim until you finish or lose it to timeouts.
+
+Typical pattern: persist `item.id` (and anything else you need), then on each pass of **your** poller (cron, loop, worker restart), call **`server.client.queue.heartbeat(queue_item_id)`** so the Continuum claim stays alive, and when the real-world condition is met call **`server.complete_queue_item(...)`** or **`server.fail_queue_item(...)`**. Use the **same worker API key** as the process that claimed the item (often the same `TaskServer` / `ContinuumClient` config loaded from env).
+
+```python
+@server.task("wait-for-mail", auto_complete=False)
+def wait_for_mail(item):
+    db.insert_outstanding(queue_item_id=str(item.id), payload=item.input_data_json)
+    # Returns without ENDED — no background heartbeat from TaskServer
+
+
+# Elsewhere: each time you poll your DB for outstanding work (including after restart):
+for row in db.outstanding_rows():
+    server.client.queue.heartbeat(row.queue_item_id)
+    if mail_arrived(row):
+        server.complete_queue_item(row.queue_item_id, output_data={"received": True})
+```
+
+Standalone process (no `TaskServer`): build a `ContinuumClient` with the worker key and call `client.queue.heartbeat` / `client.queue.update_status` the same way.
+
+### TaskServer options
+
+```python
+TaskServer(
+    base_url="http://localhost:8080",
+    api_key="...",
+    max_workers=4,  # thread pool size across all tasks
+    poll_interval=1.0,  # initial poll delay (backs off when idle)
+    max_poll_interval=5.0,  # max idle poll delay
+    heartbeat_interval=15.0,  # how often to call /heartbeat per running task
+    shutdown_timeout=30.0,  # how long to wait for handlers during shutdown
+    transport="http",  # "websocket" uses STOMP; httpx transports still accepted
+)
+```
+
+Per-task concurrency limit:
+
+```python
+@server.task("docker-run", concurrency=2)
+def run_docker(item): ...
+```
+
+Handler signature: `def handler(item: QueueItem) -> dict | list | str | None`. Inside, you have:
+
+- `item.input_data` — raw JSON string from the queue item (or `None`).
+- `item.input_data_json` — parsed value (`dict` / `list` / `str` / `None`).
+- `server.client` — full `ContinuumClient` if you need to chain management calls, fetch content, enqueue child tasks, etc.
+
+## Using `ContinuumClient` directly
+
+```python
+from continuum_task_server import ContinuumClient, TaskStatus
+
+with ContinuumClient(base_url="http://localhost:8080", api_key="...") as client:
+    # Task types
+    types = client.task_types.list()
+    echo_type = client.task_types.get_by_name("echo")
+
+    # Task items + versions
+    item = client.task_items.get_by_name("my-task")
+    versions = client.task_items.versions.list(item.id)
+
+    # Enqueue work
+    queued = client.queue.add(task_name="echo", input_data={"hello": "world"})
+
+    # Worker-side primitives (normally handled by TaskServer)
+    claimed = client.queue.claim("echo")
+    if claimed is not None:
+        client.queue.heartbeat(claimed.id)
+        client.queue.update_status(claimed.id, TaskStatus.ENDED, output_data={"ok": True})
+
+    # Content store
+    content = client.content_store.get_by_url("db://...")
+    if content is not None:
+        print(content.as_text())
+```
+
+`input_data` / `output_data` accept `dict` / `list` / `str` / `None`; non-string values are JSON-encoded for you.
+
+## WebSocket / STOMP
+
+The Queue API worker socket is native STOMP at `/ws/queue` (API-key handshake, no SockJS/JWT). `http://` base URLs become `ws://`; `https://` becomes `wss://`.
+
+```python
+from continuum_task_server import ContinuumWebSocketClient, TaskStatus, WaitMode
+
+with ContinuumWebSocketClient(base_url, api_key) as queue:
+    queue.subscribe_work("echo")
+    hint = queue.next_event(timeout=30)  # work.available is a hint, not a reservation
+    item = queue.claim("echo")  # None if another worker won
+    queue.heartbeat(item.id)
+    wait = queue.subscribe_wait(
+        "run-42",
+        mode=WaitMode.EACH,
+        queue_item_ids=[item.id],
+    )
+    # Or create the child and wait in one transaction:
+    # created = queue.enqueue_and_subscribe_wait(
+    #     task_name="echo", subscriber_id="run-42", mode=WaitMode.EACH, input_data={"hello": "world"},
+    # )
+    queue.update_status(item.id, TaskStatus.ENDED, output_data={"ok": True})
+    completed = queue.next_event(timeout=30)  # queue.completed; dedupe by event_id
+    queue.ack_event("run-42", completed.event_id)
+    queue.unsubscribe_work("echo")
+```
+
+- **TaskServer WebSocket mode** uses this client for subscribe / claim / heartbeat / status. There is no HTTP fallback poll; recovery is reconnect + resubscribe. The API also checks PostgreSQL at subscribe time and periodically for connected sessions.
+- **Reconnect** restores `/user/queue/replies` and `/user/queue/events`, every `subscribeWork` task name, and every durable `subscriberId` via bind-only `subscribeWait` (replays unacked completions from PostgreSQL).
+- **Acks are explicit.** Do not assume the SDK acked a delivery. Completions are at-least-once; ignore duplicate `eventId`s.
+- **Claim and enqueue are not retried** if the socket drops after the frame is written. The reply may have been lost; check queue state instead of sending the same command again. Heartbeat and status wait for reconnect and retry.
+- **Durable waits** use a client-chosen `subscriberId` scoped to the API-key owner. `EACH` delivers per terminal item; `ALL` delivers one summary. Bind with only `subscriberId` after reconnect.
+
+See `examples/websocket_bindings.py` and `examples/wait_subscriber.py`.
+
+### Errors
+
+All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServerError`, plus WebSocket `TransportError`, `ProtocolError`, `CommandTimeoutError`, and `AmbiguousCommandError`. Each carries `status_code` and `body` when they come from the API.
+
+```python
+from continuum_task_server import ContinuumClient, NotFoundError
+
+with ContinuumClient(...) as client:
+    try:
+        client.task_types.get_by_name("does-not-exist")
+    except NotFoundError as e:
+        print(e.status_code, e.body)
+```
+
+## Endpoints covered
+
+| Group | Method | Path |
+| --- | --- | --- |
+| Task Types | `GET`/`POST` | `/api/management/task-types[/{id}\|/by-name]` |
+| Task Items | `GET`/`POST` | `/api/management/task-items[/{id}\|/by-name\|/{id}/publish]` |
+| Task Item Versions | `GET`/`POST`/`PATCH` | `/api/management/task-items/{id}/versions[...]` |
+| Queue (management) | `GET`/`POST` | `/api/management/queue-items[/{id}]` |
+| Queue (worker) | `POST` | `/api/queue/claim`, `/api/queue/queue-items/{id}/heartbeat`, `/api/queue/queue-items/{id}/status` |
+| Queue content | `GET` | `/api/queue/queue-items/{id}/content` |
+| Content store | `GET` | `/api/management/content-store[/{id}\|?url=db://...]` |
+
+All requests send `Api-Key: <your-key>`. `204 No Content` responses are normalized to `None` (e.g. `client.queue.claim()` returns `None` when nothing's available).
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check .
+ruff format --check .
+pytest
+```
+
+Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport and an in-memory WebSocket for STOMP tests — no live server required.
+
+## Versioning
+
+- **Tag `v1.2.3`** → release wheel `1.2.3` attached to a `v1.2.3` GitHub Release.
+- **Push to `main`** → prerelease wheel `0.1.0.dev{run}+{shortsha}` attached to a `dev-{shortsha}` Release.
+- **Pull request** → prerelease wheel `0.1.0b{pr}.{run}` attached to a `pr-{pr}` Release; install command posted as a PR comment.
+
+## License
+
+MIT.

continuum_task_server_sdk-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+continuum_task_server/__init__.py,sha256=QH6eYhZahD6MjzN7QcmA_okMBxnhRjwTJN5savEvUDE,1545
+continuum_task_server/_http.py,sha256=feeOeqCUAwDASEfH3RS6mtEysHPkmj_6mtNCyGo3J9o,4776
+continuum_task_server/_stomp.py,sha256=5CNVCsu-0NXIpjob3KE8u9zmx5EhM4daWM853SrwMkA,3780
+continuum_task_server/client.py,sha256=wHpY_R5w2uB9djS05j1KyZOAH1QZQPOPaizT_KrqaUA,11658
+continuum_task_server/exceptions.py,sha256=W9IHIoKn0ZEjFSzbBO5KQI9cSDrqw16Bil-6N25YmPU,2351
+continuum_task_server/models.py,sha256=mdlUtDzUg5XAYro3fRVn1gZmZnNrEggWEu_EahK-0Oo,6829
+continuum_task_server/server.py,sha256=0flv02prTcf3hihwfK3MboK0NLyYG8fs2pXkChrk0MQ,18859
+continuum_task_server/websocket.py,sha256=C238qOBvr30bLSmMqPlmaEfafmFcL3ubFzOEa9bX_MY,31748
+continuum_task_server_sdk-1.1.0.dist-info/METADATA,sha256=rXbb2k9OmaY_U8B003PXFT0qWkJtyF8UgrjNcUA2w7Y,11692
+continuum_task_server_sdk-1.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+continuum_task_server_sdk-1.1.0.dist-info/RECORD,,

continuum_task_server_sdk-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any