cloacina-client 0.8.0__tar.gz

cloacina_client-0.8.0/.gitignore

@@ -0,0 +1,79 @@
+wip/
+/target/
+# Ignore all target directories (including in examples and subdirectories)
+**/target/
+
+# Cargo.lock is committed: this workspace ships binaries (cloacina-server,
+# cloacinactl, cloacina-compiler). Library consumers ignore our lockfile
+# anyway, so committing it just gives our own builds + Docker --locked the
+# reproducibility they need.
+# https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+
+# Each example/fixture/tutorial crate declares its own [workspace] and
+# therefore gets its own Cargo.lock when built. These are transient
+# build artifacts — committing them clutters PRs with churn whenever an
+# example is rebuilt locally. The root Cargo.lock (above) still applies
+# to the actual shipping workspace.
+examples/**/Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Mac OS files
+.DS_Store
+
+# Exclude working-docs directory
+/working-docs/
+
+# Hugo documentation
+/docs/public/
+/docs/.hugo_build.lock
+/docs/static/api/
+
+# Python files
+*.pyc
+__pycache__/
+
+# Python egg-info directories (generated during development installs)
+*.egg-info/
+# Python build directories
+build/
+dist/
+.cursorignore
+
+# SQLite database files created by tests and tutorials
+*.db
+*.db-shm
+*.db-wal
+*.db\?*
+
+# Packaged workflow files
+*.cloacina
+test-quick/
+.claude/*
+.claude_handovers/
+diataxis/
+run_demos.sh
+docs/content/api-reference/_nav.yml
+
+# Transient test output (don't commit)
+integration-test.log
+.metis/*.log
+# Auto-generated Metis code index — regenerated on every edit by the indexer,
+# so it churns constantly and shouldn't be tracked.
+.metis/code-index.md
+.metis/code-index-hashes.json
+.metis/code-index-symbols.json
+.metis/.index-dirty
+node_modules/
+clients/python/.venv/
+clients/python/dist/

cloacina_client-0.8.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: cloacina-client
+Version: 0.8.0
+Summary: Python SDK for cloacina-server — typed REST client and WebSocket execution-event streams. Version-locked to the cloacina server release. (Service client; the embedded runtime is the separate `cloaca` package.)
+Project-URL: Repository, https://github.com/colliery-io/cloacina
+Project-URL: Documentation, https://colliery-io.github.io/cloacina/
+Author-email: Dylan Storey <dylan.storey@gmail.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: websockets<16,>=13
+Description-Content-Type: text/markdown
+
+# cloacina-client
+
+Python SDK for [cloacina-server](https://github.com/colliery-io/cloacina) — a typed REST client plus WebSocket execution-event streaming, for Python 3.10+.
+
+> **This is the service client.** It talks to a running cloacina-server over HTTP/WebSocket. The embedded workflow runtime is the separate [`cloaca`](https://pypi.org/project/cloaca/) package — the two are deliberately distinct.
+
+**Version lockstep:** `cloacina-client X.Y.Z` is generated from, tested against, and only supported on `cloacina-server X.Y.Z`.
+
+## Install
+
+```bash
+pip install cloacina-client
+```
+
+## Quickstart
+
+```python
+from cloacina_client import Client
+
+client = Client("http://localhost:8080", api_key="clk_...", tenant="public")
+
+accepted = client.execute_workflow("my_workflow", {"input": 42})
+print(accepted.execution_id)
+
+for execution in client.iterate_executions(status="Failed"):
+    print(execution.id, execution.workflow_name)
+```
+
+Every helper raises `CloacinaApiError` (with `.status` and the server's machine-readable `.code`) on non-2xx responses. The generated [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) client is available as `client.generated` for anything the shim doesn't cover.
+
+## Async + live execution events
+
+```python
+import asyncio
+from cloacina_client import AsyncClient
+
+async def main():
+    client = AsyncClient("http://localhost:8080", api_key="clk_...")
+    accepted = await client.execute_workflow("my_workflow", {"input": 42})
+    # Reconnect, dedup, and acks are handled for you.
+    async for event in client.follow_execution_events(accepted.execution_id):
+        print(event)
+
+asyncio.run(main())
+```
+
+WebSocket connections never carry the long-lived key: the SDK mints a single-use, 60-second ticket (`POST /v1/auth/ws-ticket`) per connection. A `4426` close (protocol version mismatch) raises `ProtocolVersionError` — upgrade the SDK.
+
+## Regenerating
+
+`src/cloacina_client/_generated/` is produced by a pinned generator from the committed server contract:
+
+```bash
+uvx openapi-python-client@0.29.0 generate \
+  --path ../../docs/static/openapi.json \
+  --config generator-config.yaml --meta none \
+  --output-path src/cloacina_client/_generated --overwrite
+```
+
+## Contract tests
+
+`tests/test_contract.py` exercises every documented endpoint plus the WebSocket lifecycle against a live server:
+
+```bash
+CLOACINA_SERVER_URL=http://localhost:8080 \
+CLOACINA_API_KEY=<bootstrap-key> \
+uv run pytest
+```
+
+The full execute→event-stream flow (which needs a compiled `.cloacina` package) runs in the repo's `angreal test sdk-contract` harness.

cloacina_client-0.8.0/README.md

@@ -0,0 +1,70 @@
+# cloacina-client
+
+Python SDK for [cloacina-server](https://github.com/colliery-io/cloacina) — a typed REST client plus WebSocket execution-event streaming, for Python 3.10+.
+
+> **This is the service client.** It talks to a running cloacina-server over HTTP/WebSocket. The embedded workflow runtime is the separate [`cloaca`](https://pypi.org/project/cloaca/) package — the two are deliberately distinct.
+
+**Version lockstep:** `cloacina-client X.Y.Z` is generated from, tested against, and only supported on `cloacina-server X.Y.Z`.
+
+## Install
+
+```bash
+pip install cloacina-client
+```
+
+## Quickstart
+
+```python
+from cloacina_client import Client
+
+client = Client("http://localhost:8080", api_key="clk_...", tenant="public")
+
+accepted = client.execute_workflow("my_workflow", {"input": 42})
+print(accepted.execution_id)
+
+for execution in client.iterate_executions(status="Failed"):
+    print(execution.id, execution.workflow_name)
+```
+
+Every helper raises `CloacinaApiError` (with `.status` and the server's machine-readable `.code`) on non-2xx responses. The generated [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) client is available as `client.generated` for anything the shim doesn't cover.
+
+## Async + live execution events
+
+```python
+import asyncio
+from cloacina_client import AsyncClient
+
+async def main():
+    client = AsyncClient("http://localhost:8080", api_key="clk_...")
+    accepted = await client.execute_workflow("my_workflow", {"input": 42})
+    # Reconnect, dedup, and acks are handled for you.
+    async for event in client.follow_execution_events(accepted.execution_id):
+        print(event)
+
+asyncio.run(main())
+```
+
+WebSocket connections never carry the long-lived key: the SDK mints a single-use, 60-second ticket (`POST /v1/auth/ws-ticket`) per connection. A `4426` close (protocol version mismatch) raises `ProtocolVersionError` — upgrade the SDK.
+
+## Regenerating
+
+`src/cloacina_client/_generated/` is produced by a pinned generator from the committed server contract:
+
+```bash
+uvx openapi-python-client@0.29.0 generate \
+  --path ../../docs/static/openapi.json \
+  --config generator-config.yaml --meta none \
+  --output-path src/cloacina_client/_generated --overwrite
+```
+
+## Contract tests
+
+`tests/test_contract.py` exercises every documented endpoint plus the WebSocket lifecycle against a live server:
+
+```bash
+CLOACINA_SERVER_URL=http://localhost:8080 \
+CLOACINA_API_KEY=<bootstrap-key> \
+uv run pytest
+```
+
+The full execute→event-stream flow (which needs a compiled `.cloacina` package) runs in the repo's `angreal test sdk-contract` harness.

cloacina_client-0.8.0/generator-config.yaml

@@ -0,0 +1,3 @@
+---
+package_name_override: "_generated"
+project_name_override: "cloacina-client-generated"

cloacina_client-0.8.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloacina-client"
+version = "0.8.0"
+description = "Python SDK for cloacina-server — typed REST client and WebSocket execution-event streams. Version-locked to the cloacina server release. (Service client; the embedded runtime is the separate `cloaca` package.)"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Dylan Storey", email = "dylan.storey@gmail.com" }]
+dependencies = [
+    "httpx>=0.27,<1",
+    "attrs>=22.2.0",
+    "python-dateutil>=2.8.0",
+    "websockets>=13,<16",
+]
+
+[project.urls]
+Repository = "https://github.com/colliery-io/cloacina"
+Documentation = "https://colliery-io.github.io/cloacina/"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloacina_client"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+# Regenerating the vendored client (pinned generator — CI diffs this):
+#   uvx openapi-python-client@0.29.0 generate \
+#     --path ../../docs/static/openapi.json \
+#     --config generator-config.yaml --meta none \
+#     --output-path src/cloacina_client/_generated --overwrite

cloacina_client-0.8.0/src/cloacina_client/__init__.py

@@ -0,0 +1,52 @@
+# Copyright 2025-2026 Colliery Software
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Python SDK for cloacina-server (CLOACI-I-0113 / T-0647).
+
+This is the *service client* — it talks to a running cloacina-server over
+HTTP/WebSocket. The embedded workflow runtime is the separate ``cloaca``
+package; the two are deliberately distinct.
+
+Quickstart::
+
+    from cloacina_client import Client
+
+    client = Client("http://localhost:8080", api_key="clk_...", tenant="public")
+    accepted = client.execute_workflow("my_workflow", {"input": 42})
+
+    import asyncio
+    from cloacina_client import AsyncClient
+
+    async def follow():
+        aclient = AsyncClient("http://localhost:8080", api_key="clk_...")
+        async for event in aclient.follow_execution_events(accepted.execution_id):
+            print(event)
+
+    asyncio.run(follow())
+"""
+
+from ._client import AsyncClient, Client, CloacinaApiError
+from ._generated import models
+from ._ws import DELIVERY_PROTOCOL_VERSION, DeliveryPush
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "CloacinaApiError",
+    "DeliveryPush",
+    "DELIVERY_PROTOCOL_VERSION",
+    "models",
+]
+
+__version__ = "0.8.0"