durable-workflow 0.2.0__tar.gz → 0.3.0__tar.gz

durable_workflow-0.3.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: durable-workflow
+Version: 0.3.0
+Summary: Python SDK for the Durable Workflow server (language-neutral HTTP protocol)
+Author: Durable Workflow Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/durable-workflow/sdk-python
+Project-URL: Documentation, https://durable-workflow.github.io/docs/2.0/polyglot/python
+Project-URL: Repository, https://github.com/durable-workflow/sdk-python
+Project-URL: Issues, https://github.com/zorporation/durable-workflow/issues
+Keywords: workflow,durable,orchestration,temporal,saga
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: avro<2,>=1.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20; extra == "prometheus"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Dynamic: license-file
+
+# Durable Workflow (Python SDK)
+
+A Python SDK for the [Durable Workflow server](https://github.com/durable-workflow/server). Speaks the server's language-neutral HTTP/JSON worker protocol — no PHP runtime required.
+
+Status: **Alpha**. Core features implemented: workflows, activities, schedules, signals, timers, child workflows, continue-as-new, side effects, version markers, and worker-applied accepted updates. Client calls for queries and updates exist; Python workflow-side query receiver metadata is available, while server-routed Python query execution and pre-accept update validator routing are still in progress. Full language-neutral protocol support for cross-PHP/Python orchestration is the release goal.
+
+## Install
+
+```bash
+pip install durable-workflow
+```
+
+Or for development:
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Quickstart
+
+```python
+from durable_workflow import Client, Worker, workflow, activity
+
+@activity.defn(name="greet")
+def greet(name: str) -> str:
+    return f"hello, {name}"
+
+@workflow.defn(name="greeter")
+class GreeterWorkflow:
+    def run(self, ctx, name):
+        result = yield ctx.schedule_activity("greet", [name])
+        return result
+
+async def main():
+    client = Client("http://server:8080", token="dev-token-123", namespace="default")
+    worker = Worker(
+        client,
+        task_queue="python-workers",
+        workflows=[GreeterWorkflow],
+        activities=[greet],
+    )
+    handle = await client.start_workflow(
+        workflow_type="greeter",
+        workflow_id="greet-1",
+        task_queue="python-workers",
+        input=["world"],
+    )
+    await worker.run_until(workflow_id="greet-1", timeout=30.0)
+    result = await client.get_result(handle)
+    print(result)  # "hello, world"
+```
+
+For a fuller deployable example, see
+[`examples/order_processing`](examples/order_processing), which runs a
+multi-activity order workflow against a local server with Docker Compose.
+
+## Activity retries and timeouts
+
+Configure per-call activity retries and deadlines from workflow code:
+
+```python
+from durable_workflow import ActivityRetryPolicy
+
+result = yield ctx.schedule_activity(
+    "charge-card",
+    [order],
+    retry_policy=ActivityRetryPolicy(
+        max_attempts=4,
+        initial_interval_seconds=1,
+        backoff_coefficient=2,
+        maximum_interval_seconds=30,
+        non_retryable_error_types=["ValidationError"],
+    ),
+    start_to_close_timeout=120,
+    schedule_to_close_timeout=300,
+    heartbeat_timeout=15,
+)
+```
+
+Child workflow starts use the same retry policy shape and workflow-level
+execution/run timeout names:
+
+```python
+from durable_workflow import ChildWorkflowRetryPolicy
+
+receipt = yield ctx.start_child_workflow(
+    "payment.child",
+    [order],
+    retry_policy=ChildWorkflowRetryPolicy(
+        max_attempts=3,
+        initial_interval_seconds=2,
+        backoff_coefficient=2,
+        non_retryable_error_types=["ValidationError"],
+    ),
+    execution_timeout_seconds=600,
+    run_timeout_seconds=120,
+)
+```
+
+## Workflow signals, queries, and updates
+
+Signals mutate workflow state during replay:
+
+```python
+@workflow.defn(name="approval")
+class ApprovalWorkflow:
+    def __init__(self) -> None:
+        self.approved = False
+
+    @workflow.signal("approve")
+    def approve(self, by: str) -> None:
+        self.approved = True
+
+    @workflow.query("status")
+    def status(self) -> dict:
+        return {"approved": self.approved}
+
+    @workflow.update("set_approval")
+    def set_approval(self, approved: bool) -> dict:
+        self.approved = approved
+        return {"approved": self.approved}
+
+    @set_approval.validator
+    def validate_set_approval(self, approved: bool) -> None:
+        if not isinstance(approved, bool):
+            raise ValueError("approved must be boolean")
+```
+
+The Python SDK records query and update receiver metadata on workflow classes,
+exposes a query-state replay helper, and applies accepted updates on Python
+workflow tasks by emitting `complete_update` or `fail_update` back to the
+server. Query routing and synchronous pre-accept update validator execution are
+still server-side follow-ups; use those paths only with deployments that
+advertise support for the target workflow type.
+
+## Features
+
+- **Async-first**: Built on `httpx` and `asyncio`
+- **Type-safe**: Full type hints, passes `mypy --strict`
+- **Polyglot**: Works alongside PHP workers on the same task queue
+- **HTTP/JSON protocol**: No gRPC, no protobuf dependencies
+- **Codec envelopes**: Avro payloads by default, with JSON decode compatibility for existing history
+- **Metrics hooks**: Pluggable counters and histograms, with an optional Prometheus adapter
+
+## Authentication
+
+For local servers that use one shared bearer token, pass `token=`:
+
+```python
+client = Client("http://server:8080", token="shared-token", namespace="default")
+```
+
+For production servers with role-scoped tokens, pass separate credentials for
+control-plane calls and worker-plane polling:
+
+```python
+client = Client(
+    "https://workflow.example.internal",
+    control_token="operator-token",
+    worker_token="worker-token",
+    namespace="orders",
+)
+```
+
+Create one client per namespace when your deployment issues namespace-scoped
+tokens. The SDK sends the configured token as `Authorization: Bearer ...` and
+the namespace as `X-Namespace` on every request.
+
+## Metrics
+
+Pass a recorder to `Client(metrics=...)` or `Worker(metrics=...)` to collect request, poll, and task metrics. The SDK ships a no-op default, an `InMemoryMetrics` recorder for tests or custom exporter loops, and `PrometheusMetrics` for deployments that install the optional extra:
+
+```bash
+pip install 'durable-workflow[prometheus]'
+```
+
+```python
+from durable_workflow import Client, PrometheusMetrics
+
+metrics = PrometheusMetrics()
+client = Client("http://server:8080", token="dev-token-123", metrics=metrics)
+```
+
+Custom recorders implement `increment(name, value=1.0, tags=None)` and `record(name, value, tags=None)`.
+
+## Documentation
+
+Full documentation is available at
+[durable-workflow.github.io/docs/2.0/polyglot/python](https://durable-workflow.github.io/docs/2.0/polyglot/python):
+
+- [Python SDK guide](https://durable-workflow.com/docs/2.0/polyglot/python)
+- [API reference](https://python.durable-workflow.com/)
+
+## Requirements
+
+- Python ≥ 3.10
+- A running [Durable Workflow server](https://github.com/durable-workflow/server)
+
+## Compatibility
+
+SDK version 0.2.x is compatible with servers that advertise these protocol
+manifests from `GET /api/cluster/info`:
+
+- `control_plane.version: "2"`
+- `control_plane.request_contract.schema: durable-workflow.v2.control-plane-request.contract` version `1`
+- `worker_protocol.version: "1.0"`
+
+The top-level server `version` is build identity only. The worker checks these
+protocol manifests at startup and fails closed when compatibility is missing,
+unknown, or undiscoverable.
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e '.[dev]'
+
+# Run tests
+pytest
+
+# Run integration tests (requires Docker)
+pytest -m integration
+
+# Type check
+mypy src/durable_workflow/
+
+# Lint
+ruff check src/ tests/
+
+# Preview the API reference site locally
+pip install -e '.[docs]'
+mkdocs serve
+```
+
+The API reference is published to [python.durable-workflow.com](https://python.durable-workflow.com/) and rebuilt automatically on push to `main`.
+
+## License
+
+MIT

durable_workflow-0.3.0/README.md

@@ -0,0 +1,239 @@
+# Durable Workflow (Python SDK)
+
+A Python SDK for the [Durable Workflow server](https://github.com/durable-workflow/server). Speaks the server's language-neutral HTTP/JSON worker protocol — no PHP runtime required.
+
+Status: **Alpha**. Core features implemented: workflows, activities, schedules, signals, timers, child workflows, continue-as-new, side effects, version markers, and worker-applied accepted updates. Client calls for queries and updates exist; Python workflow-side query receiver metadata is available, while server-routed Python query execution and pre-accept update validator routing are still in progress. Full language-neutral protocol support for cross-PHP/Python orchestration is the release goal.
+
+## Install
+
+```bash
+pip install durable-workflow
+```
+
+Or for development:
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Quickstart
+
+```python
+from durable_workflow import Client, Worker, workflow, activity
+
+@activity.defn(name="greet")
+def greet(name: str) -> str:
+    return f"hello, {name}"
+
+@workflow.defn(name="greeter")
+class GreeterWorkflow:
+    def run(self, ctx, name):
+        result = yield ctx.schedule_activity("greet", [name])
+        return result
+
+async def main():
+    client = Client("http://server:8080", token="dev-token-123", namespace="default")
+    worker = Worker(
+        client,
+        task_queue="python-workers",
+        workflows=[GreeterWorkflow],
+        activities=[greet],
+    )
+    handle = await client.start_workflow(
+        workflow_type="greeter",
+        workflow_id="greet-1",
+        task_queue="python-workers",
+        input=["world"],
+    )
+    await worker.run_until(workflow_id="greet-1", timeout=30.0)
+    result = await client.get_result(handle)
+    print(result)  # "hello, world"
+```
+
+For a fuller deployable example, see
+[`examples/order_processing`](examples/order_processing), which runs a
+multi-activity order workflow against a local server with Docker Compose.
+
+## Activity retries and timeouts
+
+Configure per-call activity retries and deadlines from workflow code:
+
+```python
+from durable_workflow import ActivityRetryPolicy
+
+result = yield ctx.schedule_activity(
+    "charge-card",
+    [order],
+    retry_policy=ActivityRetryPolicy(
+        max_attempts=4,
+        initial_interval_seconds=1,
+        backoff_coefficient=2,
+        maximum_interval_seconds=30,
+        non_retryable_error_types=["ValidationError"],
+    ),
+    start_to_close_timeout=120,
+    schedule_to_close_timeout=300,
+    heartbeat_timeout=15,
+)
+```
+
+Child workflow starts use the same retry policy shape and workflow-level
+execution/run timeout names:
+
+```python
+from durable_workflow import ChildWorkflowRetryPolicy
+
+receipt = yield ctx.start_child_workflow(
+    "payment.child",
+    [order],
+    retry_policy=ChildWorkflowRetryPolicy(
+        max_attempts=3,
+        initial_interval_seconds=2,
+        backoff_coefficient=2,
+        non_retryable_error_types=["ValidationError"],
+    ),
+    execution_timeout_seconds=600,
+    run_timeout_seconds=120,
+)
+```
+
+## Workflow signals, queries, and updates
+
+Signals mutate workflow state during replay:
+
+```python
+@workflow.defn(name="approval")
+class ApprovalWorkflow:
+    def __init__(self) -> None:
+        self.approved = False
+
+    @workflow.signal("approve")
+    def approve(self, by: str) -> None:
+        self.approved = True
+
+    @workflow.query("status")
+    def status(self) -> dict:
+        return {"approved": self.approved}
+
+    @workflow.update("set_approval")
+    def set_approval(self, approved: bool) -> dict:
+        self.approved = approved
+        return {"approved": self.approved}
+
+    @set_approval.validator
+    def validate_set_approval(self, approved: bool) -> None:
+        if not isinstance(approved, bool):
+            raise ValueError("approved must be boolean")
+```
+
+The Python SDK records query and update receiver metadata on workflow classes,
+exposes a query-state replay helper, and applies accepted updates on Python
+workflow tasks by emitting `complete_update` or `fail_update` back to the
+server. Query routing and synchronous pre-accept update validator execution are
+still server-side follow-ups; use those paths only with deployments that
+advertise support for the target workflow type.
+
+## Features
+
+- **Async-first**: Built on `httpx` and `asyncio`
+- **Type-safe**: Full type hints, passes `mypy --strict`
+- **Polyglot**: Works alongside PHP workers on the same task queue
+- **HTTP/JSON protocol**: No gRPC, no protobuf dependencies
+- **Codec envelopes**: Avro payloads by default, with JSON decode compatibility for existing history
+- **Metrics hooks**: Pluggable counters and histograms, with an optional Prometheus adapter
+
+## Authentication
+
+For local servers that use one shared bearer token, pass `token=`:
+
+```python
+client = Client("http://server:8080", token="shared-token", namespace="default")
+```
+
+For production servers with role-scoped tokens, pass separate credentials for
+control-plane calls and worker-plane polling:
+
+```python
+client = Client(
+    "https://workflow.example.internal",
+    control_token="operator-token",
+    worker_token="worker-token",
+    namespace="orders",
+)
+```
+
+Create one client per namespace when your deployment issues namespace-scoped
+tokens. The SDK sends the configured token as `Authorization: Bearer ...` and
+the namespace as `X-Namespace` on every request.
+
+## Metrics
+
+Pass a recorder to `Client(metrics=...)` or `Worker(metrics=...)` to collect request, poll, and task metrics. The SDK ships a no-op default, an `InMemoryMetrics` recorder for tests or custom exporter loops, and `PrometheusMetrics` for deployments that install the optional extra:
+
+```bash
+pip install 'durable-workflow[prometheus]'
+```
+
+```python
+from durable_workflow import Client, PrometheusMetrics
+
+metrics = PrometheusMetrics()
+client = Client("http://server:8080", token="dev-token-123", metrics=metrics)
+```
+
+Custom recorders implement `increment(name, value=1.0, tags=None)` and `record(name, value, tags=None)`.
+
+## Documentation
+
+Full documentation is available at
+[durable-workflow.github.io/docs/2.0/polyglot/python](https://durable-workflow.github.io/docs/2.0/polyglot/python):
+
+- [Python SDK guide](https://durable-workflow.com/docs/2.0/polyglot/python)
+- [API reference](https://python.durable-workflow.com/)
+
+## Requirements
+
+- Python ≥ 3.10
+- A running [Durable Workflow server](https://github.com/durable-workflow/server)
+
+## Compatibility
+
+SDK version 0.2.x is compatible with servers that advertise these protocol
+manifests from `GET /api/cluster/info`:
+
+- `control_plane.version: "2"`
+- `control_plane.request_contract.schema: durable-workflow.v2.control-plane-request.contract` version `1`
+- `worker_protocol.version: "1.0"`
+
+The top-level server `version` is build identity only. The worker checks these
+protocol manifests at startup and fails closed when compatibility is missing,
+unknown, or undiscoverable.
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e '.[dev]'
+
+# Run tests
+pytest
+
+# Run integration tests (requires Docker)
+pytest -m integration
+
+# Type check
+mypy src/durable_workflow/
+
+# Lint
+ruff check src/ tests/
+
+# Preview the API reference site locally
+pip install -e '.[docs]'
+mkdocs serve
+```
+
+The API reference is published to [python.durable-workflow.com](https://python.durable-workflow.com/) and rebuilt automatically on push to `main`.
+
+## License
+
+MIT

{durable_workflow-0.2.0 → durable_workflow-0.3.0}/pyproject.toml

@@ -1,14 +1,15 @@
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for the Durable Workflow server (language-neutral HTTP protocol)"
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     { name = "Durable Workflow Contributors" },
 ]
@@ -22,7 +23,6 @@ keywords = [
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -42,10 +42,17 @@ dev = [
     "mypy>=1.10",
     "ruff>=0.4",
 ]
+prometheus = [
+    "prometheus-client>=0.20",
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+]
 
 [project.urls]
 Homepage = "https://github.com/durable-workflow/sdk-python"
-Documentation = "https://durable-workflow.github.io/docs/2.0/sdks/python/"
+Documentation = "https://durable-workflow.github.io/docs/2.0/polyglot/python"
 Repository = "https://github.com/durable-workflow/sdk-python"
 Issues = "https://github.com/zorporation/durable-workflow/issues"
 

{durable_workflow-0.2.0 → durable_workflow-0.3.0}/src/durable_workflow/__init__.py

@@ -6,7 +6,7 @@ try:
 except PackageNotFoundError:  # source checkout without installed metadata
     __version__ = "0.0.0+unknown"
 
-from . import activity, sync, workflow
+from . import activity, sync, testing, workflow
 from .activity import ActivityContext, ActivityInfo
 from .client import (
     Client,
@@ -40,14 +40,23 @@ from .errors import (
     WorkflowNotFound,
     WorkflowTerminated,
 )
+from .metrics import (
+    InMemoryMetrics,
+    MetricsRecorder,
+    NoopMetrics,
+    PrometheusMetrics,
+)
+from .retry_policy import RetryPolicy, TransportRetryPolicy
 from .worker import Worker
-from .workflow import ContinueAsNew, StartChildWorkflow
+from .workflow import ActivityRetryPolicy, ChildWorkflowRetryPolicy, ContinueAsNew, StartChildWorkflow
 
 __all__ = [
     "__version__",
     "ActivityCancelled",
     "ActivityContext",
     "ActivityInfo",
+    "ActivityRetryPolicy",
+    "ChildWorkflowRetryPolicy",
     "ChildWorkflowFailed",
     "Client",
     "ContinueAsNew",
@@ -68,12 +77,19 @@ __all__ = [
     "WorkflowList",
     "activity",
     "sync",
+    "testing",
     "workflow",
     "DurableWorkflowError",
     "InvalidArgument",
+    "InMemoryMetrics",
+    "MetricsRecorder",
     "NamespaceNotFound",
+    "NoopMetrics",
     "QueryFailed",
+    "PrometheusMetrics",
+    "RetryPolicy",
     "ServerError",
+    "TransportRetryPolicy",
     "Unauthorized",
     "UpdateRejected",
     "WorkflowAlreadyStarted",

{durable_workflow-0.2.0 → durable_workflow-0.3.0}/src/durable_workflow/activity.py

@@ -20,6 +20,8 @@ _current_context: contextvars.ContextVar[ActivityContext | None] = contextvars.C
 
 @dataclass(frozen=True)
 class ActivityInfo:
+    """Metadata attached to the currently running activity attempt."""
+
     task_id: str
     activity_type: str
     activity_attempt_id: str
@@ -29,6 +31,8 @@ class ActivityInfo:
 
 
 class ActivityContext:
+    """Per-attempt activity context exposed by :func:`durable_workflow.activity.context`."""
+
     def __init__(
         self,
         *,
@@ -41,13 +45,26 @@ class ActivityContext:
 
     @property
     def info(self) -> ActivityInfo:
+        """Metadata for the currently running activity attempt."""
         return self._info
 
     @property
     def is_cancelled(self) -> bool:
+        """``True`` once the server has signalled that the owning workflow cancelled this activity."""
         return self._cancel_requested
 
     async def heartbeat(self, details: dict[str, Any] | None = None) -> None:
+        """Report liveness to the server and check for a cancellation request.
+
+        Long-running activities should call ``heartbeat()`` periodically so the
+        server can distinguish a slow-but-alive attempt from a dead worker.
+        Optional ``details`` are attached to the heartbeat and surface as the
+        activity's last-known progress on failure.
+
+        Raises :class:`~durable_workflow.errors.ActivityCancelled` when the
+        owning workflow has requested cancellation, so the activity can exit
+        cleanly at its next natural break point.
+        """
         resp = await self._client.heartbeat_activity_task(
             task_id=self._info.task_id,
             activity_attempt_id=self._info.activity_attempt_id,
@@ -60,6 +77,7 @@ class ActivityContext:
 
 
 def context() -> ActivityContext:
+    """Return the current activity attempt context."""
     ctx = _current_context.get()
     if ctx is None:
         raise RuntimeError("activity.context() called outside of an activity execution")
@@ -71,6 +89,8 @@ def _set_context(ctx: ActivityContext | None) -> contextvars.Token[ActivityConte
 
 
 def defn(*, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Register a callable as an activity type under a language-neutral name."""
+
     def wrap(fn: Callable[..., Any]) -> Callable[..., Any]:
         fn.__activity_name__ = name  # type: ignore[attr-defined]
         _REGISTRY[name] = fn
@@ -80,4 +100,5 @@ def defn(*, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
 
 
 def registry() -> dict[str, Callable[..., Any]]:
+    """Return a copy of activity callables registered in this process."""
     return dict(_REGISTRY)