cadence-python-client 0.2.1__tar.gz → 0.2.2__tar.gz

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/.cursorrules

@@ -4,7 +4,7 @@
 - **Always use `uv` for Python package management**
 - Use `uv run` for running Python commands instead of `python` directly
 - Use `uv sync` for installing dependencies instead of `pip install`
-- Use `uv tool run` for running development tools (pytest, mypy, ruff, etc.)
+- Use `uv tool run` for running development tools (pytest, ruff, etc.); use `uv run mypy` so mypy uses the project environment (e.g. `types-grpcio`).
 - Only use `pip` or `python` directly when specifically required by the tool or documentation
 
 ## Examples
@@ -12,7 +12,7 @@
 # ✅ Correct
 uv run python scripts/generate_proto.py
 uv run python -m pytest tests/
-uv tool run mypy cadence/
+uv run mypy cadence/
 uv tool run ruff check
 
 # ❌ Avoid
@@ -37,13 +37,13 @@ pip install -e ".[dev]"
 ## Code Quality
 - **ALWAYS run linter and type checker after making code changes**
 - Run linter with auto-fix: `uv tool run ruff check --fix`
-- Run type checking: `uv tool run mypy cadence/`
-- Use `uv tool run ruff check --fix && uv tool run mypy cadence/` to run both together
+- Run type checking: `uv run mypy cadence/`
+- Use `uv tool run ruff check --fix && uv run mypy cadence/` to run both together
 - **Standard workflow**: Make changes → Run linter → Run type checker → Commit
 
 ## Development Workflow
 1. Make code changes
 2. Run `uv tool run ruff check --fix` (fixes formatting and linting issues)
-3. Run `uv tool run mypy cadence/` (checks type safety)
+3. Run `uv run mypy cadence/` (checks type safety)
 4. Run `uv run python -m pytest` (run tests)
 5. Commit changes

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/Makefile

@@ -7,7 +7,7 @@ pr: install generate lint type-check test integration-test
 # Install dependencies
 install:
 	@echo "Installing dependencies..."
-	uv sync --extra dev
+	uv sync --all-extras
 
 # Generate idl files
 generate:

{cadence_python_client-0.2.1/cadence_python_client.egg-info → cadence_python_client-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadence-python-client
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python framework for authoring Cadence workflows and activities
 Author: Cadence
 License: Apache-2.0
@@ -43,6 +43,7 @@ Requires-Dist: pytest-docker>=3.2.3; extra == "dev"
 Requires-Dist: opentelemetry-instrumentation-grpc==0.60b1; extra == "dev"
 Requires-Dist: opentelemetry-sdk>=1.39.1; extra == "dev"
 Requires-Dist: setuptools-scm[simple]>=9.2; extra == "dev"
+Requires-Dist: types-grpcio>=1.0.0.20260408; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=6.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/fn_signature.py

@@ -53,8 +53,20 @@ class FnSignature:
     def params_from_payload(
         self, data_converter: DataConverter, payload: Payload
     ) -> list[Any]:
+        if not self.params:
+            return []
         type_hints = [param.type_hint for param in self.params]
-        return data_converter.from_data(payload, type_hints)
+        decoded = _decode_provided_values(data_converter, payload, type_hints)
+        for i, param in enumerate(self.params):
+            if i < len(decoded):
+                continue
+            if param.has_default:
+                decoded.append(param.default_value)
+            else:
+                raise ValueError(
+                    f"required parameter '{param.name}' (position {i}) not provided in payload"
+                )
+        return decoded
 
     @staticmethod
     def of(fn: Callable) -> "FnSignature":
@@ -88,3 +100,21 @@ class FnSignature:
         return_type = hints.get("return", Any)
 
         return FnSignature(params, return_type)
+
+
+def _decode_provided_values(
+    data_converter: DataConverter,
+    payload: Payload,
+    type_hints: Sequence[Type | None],
+) -> list[Any]:
+    decoder = getattr(data_converter, "_decode_provided_values", None)
+    if callable(decoder):
+        return list(decoder(payload, type_hints))
+
+    counter = getattr(data_converter, "_payload_value_count", None)
+    if callable(counter):
+        provided_count = int(counter(payload, len(type_hints)))
+        return data_converter.from_data(payload, list(type_hints[:provided_count]))
+
+    # Backward compatibility
+    return data_converter.from_data(payload, list(type_hints))

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/rpc/retry.py

@@ -60,6 +60,8 @@ class RetryInterceptor(UnaryUnaryClientInterceptor):
     ) -> Any:
         loop = asyncio.get_running_loop()
         expiration_interval = client_call_details.timeout
+        if expiration_interval is None:
+            expiration_interval = float("inf")
         start_time = loop.time()
         deadline = start_time + expiration_interval
 
@@ -68,7 +70,9 @@ class RetryInterceptor(UnaryUnaryClientInterceptor):
             remaining = deadline - loop.time()
             # Namedtuple methods start with an underscore to avoid conflicts and aren't actually private
             # noinspection PyProtectedMember
-            call_details = client_call_details._replace(timeout=remaining)
+            call_details = client_call_details._replace(  # type: ignore[attr-defined]
+                timeout=remaining
+            )
             rpc_call = await continuation(call_details, request)
             try:
                 await rpc_call
@@ -95,8 +99,9 @@ class RetryInterceptor(UnaryUnaryClientInterceptor):
 
 def is_retryable(err: CadenceRpcError, call_details: ClientCallDetails) -> bool:
     # Handle requests to the passive side, matching the Go and Java Clients
-    if call_details.method == GET_WORKFLOW_HISTORY and isinstance(
-        err, EntityNotExistsError
+    if (
+        call_details.method == GET_WORKFLOW_HISTORY  # type: ignore[comparison-overlap]
+        and isinstance(err, EntityNotExistsError)
     ):
         return (
             err.active_cluster is not None

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/rpc/yarpc.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable
+from typing import Any, Callable, cast
 
 from grpc.aio import Metadata
 from grpc.aio import UnaryUnaryClientInterceptor, ClientCallDetails
@@ -40,6 +40,9 @@ class YarpcMetadataInterceptor(UnaryUnaryClientInterceptor):
 
         # Namedtuple methods start with an underscore to avoid conflicts and aren't actually private
         # noinspection PyProtectedMember
-        return client_call_details._replace(
-            metadata=metadata, timeout=client_call_details.timeout or 60.0
+        return cast(
+            ClientCallDetails,
+            client_call_details._replace(  # type: ignore[attr-defined]
+                metadata=metadata, timeout=client_call_details.timeout or 60.0
+            ),
         )

cadence_python_client-0.2.2/cadence/_internal/workflow/active_cluster_selection_policy.py

@@ -0,0 +1,32 @@
+"""Adapt :class:`cadence.workflow.ActiveClusterSelectionPolicy` (TypedDict) to its protobuf wire form."""
+
+from __future__ import annotations
+
+from typing import Mapping, cast
+
+from cadence.api.v1 import common_pb2
+from cadence.workflow import ActiveClusterSelectionPolicy
+
+
+def active_cluster_selection_policy_to_proto(
+    policy: ActiveClusterSelectionPolicy | Mapping[str, object] | None,
+) -> common_pb2.ActiveClusterSelectionPolicy | None:
+    """Convert a user active-cluster selection policy to protobuf, or ``None`` if empty.
+
+    ``None`` and an empty mapping both map to ``None``.
+    """
+    if policy is None or (isinstance(policy, Mapping) and len(policy) == 0):
+        return None
+
+    out = common_pb2.ActiveClusterSelectionPolicy()
+
+    if (ca := policy.get("cluster_attribute")) is not None:
+        ca_map = cast(Mapping[str, str], ca)
+        out.cluster_attribute.CopyFrom(
+            common_pb2.ClusterAttribute(
+                scope=ca_map.get("scope", ""),
+                name=ca_map.get("name", ""),
+            )
+        )
+
+    return out

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/workflow/context.py

@@ -1,8 +1,11 @@
 from contextlib import contextmanager
+from asyncio import get_running_loop
 from datetime import timedelta
 from math import ceil
-from typing import Iterator, Optional, Any, Unpack, Type, cast
+from typing import Iterator, Optional, Any, Unpack, Type, cast, Callable
 
+from cadence._internal.workflow.deterministic_event_loop import DeterministicEventLoop
+from cadence._internal.workflow.retry_policy import retry_policy_to_proto
 from cadence._internal.workflow.statemachine.decision_manager import DecisionManager
 from cadence.api.v1.common_pb2 import ActivityType
 from cadence.api.v1.decision_pb2 import (
@@ -11,15 +14,18 @@ from cadence.api.v1.decision_pb2 import (
 )
 from cadence.api.v1.tasklist_pb2 import TaskList, TaskListKind
 from cadence.data_converter import DataConverter
-from cadence.workflow import WorkflowContext, WorkflowInfo, ResultType, ActivityOptions
-
-default_activity_options = ActivityOptions(
-    schedule_to_close_timeout=timedelta(
-        hours=1
-    ),  # more than 1 hour is recommended to set up options explicitly like heartbeat for self recovery
-    schedule_to_start_timeout=timedelta(seconds=10),
+from cadence.workflow import (
+    ActivityOptions,
+    ResultType,
+    WorkflowContext,
+    WorkflowInfo,
 )
 
+_DEFAULT_ACTIVITY_OPTIONS: ActivityOptions = {
+    "schedule_to_close_timeout": timedelta(hours=1),
+    "schedule_to_start_timeout": timedelta(seconds=10),
+}
+
 
 class Context(WorkflowContext):
     def __init__(
@@ -45,7 +51,7 @@ class Context(WorkflowContext):
         *args: Any,
         **kwargs: Unpack[ActivityOptions],
     ) -> ResultType:
-        opts: ActivityOptions = {**default_activity_options, **kwargs}
+        opts: ActivityOptions = {**_DEFAULT_ACTIVITY_OPTIONS, **kwargs}
         if "schedule_to_close_timeout" not in opts and (
             "schedule_to_start_timeout" not in opts
             or "start_to_close_timeout" not in opts
@@ -87,14 +93,13 @@ class Context(WorkflowContext):
             schedule_to_start_timeout=_round_to_nearest_second(schedule_to_start),
             start_to_close_timeout=_round_to_nearest_second(start_to_close),
             heartbeat_timeout=_round_to_nearest_second(heartbeat),
-            retry_policy=None,
+            retry_policy=retry_policy_to_proto(opts.get("retry_policy")),
             header=None,
             request_local_dispatch=False,
         )
 
-        result_payload = await self._decision_manager.schedule_activity(
-            schedule_attributes
-        )
+        future = self._decision_manager.schedule_activity(schedule_attributes)
+        result_payload = await future
 
         result = self.data_converter().from_data(result_payload, [result_type])[0]
 
@@ -103,11 +108,12 @@ class Context(WorkflowContext):
     async def start_timer(self, duration: timedelta):
         if duration.total_seconds() <= 0:  # shortcut
             return
-        await self._decision_manager.start_timer(
+        future = self._decision_manager.start_timer(
             StartTimerDecisionAttributes(
                 start_to_fire_timeout=duration,
             )
         )
+        await future
 
     def set_replay_mode(self, replay: bool) -> None:
         """Set whether the workflow is currently in replay mode."""
@@ -125,11 +131,17 @@ class Context(WorkflowContext):
         """Get the current replay time in milliseconds."""
         return self._replay_current_time_milliseconds
 
+    async def wait_condition(self, predicate: Callable[[], bool]) -> None:
+        loop = cast(DeterministicEventLoop, get_running_loop())
+        await loop.create_waiter(predicate)
+
     @contextmanager
     def _activate(self) -> Iterator["Context"]:
         token = WorkflowContext._var.set(self)
-        yield self
-        WorkflowContext._var.reset(token)
+        try:
+            yield self
+        finally:
+            WorkflowContext._var.reset(token)
 
 
 def _round_to_nearest_second(delta: timedelta) -> timedelta:

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/workflow/deterministic_event_loop.py

@@ -8,6 +8,8 @@ import threading
 from typing import Callable, Any, TypeVar, Coroutine, Awaitable, Generator
 from typing_extensions import Unpack, TypeVarTuple
 
+from cadence._internal.workflow.waiter import Waiter
+
 logger = logging.getLogger(__name__)
 
 
@@ -32,6 +34,7 @@ class DeterministicEventLoop(AbstractEventLoop):
         self._thread_id: int | None = None  # indicate if the event loop is running
         self._debug: bool = False
         self._ready: collections.deque[events.Handle] = collections.deque()
+        self._waiters: list[Waiter] = []
         self._stopping: bool = False
         self._closed: bool = False
 
@@ -141,6 +144,13 @@ class DeterministicEventLoop(AbstractEventLoop):
     def create_future(self) -> Future[Any]:
         return futures.Future(loop=self)
 
+    def create_waiter(self, predicate: Callable[[], bool]) -> Waiter:
+        """Register a predicate-driven awaitable."""
+        waiter = Waiter(predicate, self)
+        if not waiter.poll():
+            self._waiters.append(waiter)
+        return waiter
+
     def _run_once(self) -> None:
         ntodo = len(self._ready)
         for i in range(ntodo):
@@ -149,6 +159,19 @@ class DeterministicEventLoop(AbstractEventLoop):
                 continue
             handle._run()
 
+        # Poll waiters; only stop early if settling one schedules new work,
+        # so remaining waiters are not skipped.
+        i = 0
+        while i < len(self._waiters):
+            w = self._waiters[i]
+            ready_before = len(self._ready)
+            if w.poll():
+                del self._waiters[i]
+                if len(self._ready) > ready_before:
+                    return
+            else:
+                i += 1
+
     def _run_forever_setup(self) -> None:
         self._check_closed()
         self._check_running()
@@ -190,6 +213,7 @@ class DeterministicEventLoop(AbstractEventLoop):
             logger.debug("Close %r", self)
         self._closed = True
         self._ready.clear()
+        self._waiters.clear()
 
     def is_closed(self) -> bool:
         """Returns True if the event loop was closed."""
@@ -462,13 +486,12 @@ class DeterministicEventLoop(AbstractEventLoop):
         )
 
     def call_exception_handler(self, context: dict[str, Any]) -> None:
-        # This is called if a task has an unhandled exception. Short term, it's helpful to log these for debugging.
-        # Long term, we need some combination of failing decision tasks or workflows based on these errors.
         message = context.get("message")
         if not message:
             message = "Unhandled exception in event loop"
 
         exception = context.get("exception")
+
         if isinstance(exception, BaseException):
             exc_info = exception
         else:

cadence_python_client-0.2.2/cadence/_internal/workflow/retry_policy.py

@@ -0,0 +1,62 @@
+"""Adapt :class:`cadence.workflow.RetryPolicy` (TypedDict) to its protobuf wire form."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from math import ceil
+from typing import Mapping, cast
+
+from google.protobuf.duration_pb2 import Duration
+
+from cadence.api.v1 import common_pb2
+from cadence.workflow import RetryPolicy
+
+
+def _round_to_whole_seconds(delta: timedelta) -> timedelta:
+    """Ceil-round a ``timedelta`` to whole seconds."""
+    return timedelta(seconds=ceil(delta.total_seconds()))
+
+
+def _set_duration_field(target: Duration, delta: timedelta) -> None:
+    """Write ``delta``, ceil-rounded to whole seconds, into a proto ``Duration`` field."""
+    d = Duration()
+    d.FromTimedelta(_round_to_whole_seconds(delta))
+    target.CopyFrom(d)
+
+
+def retry_policy_to_proto(
+    policy: RetryPolicy | Mapping[str, object] | None,
+) -> common_pb2.RetryPolicy | None:
+    """Convert a user retry policy to protobuf, or ``None`` if no policy was provided.
+
+    ``None`` and an empty mapping both map to ``None`` so that the server applies its
+    own defaults instead of receiving an explicit empty policy. Durations are ceiled
+    to whole seconds to match the server's resolution and the Go/Java SDKs.
+    """
+    if policy is None or (isinstance(policy, Mapping) and len(policy) == 0):
+        return None
+
+    out = common_pb2.RetryPolicy()
+
+    if (ii := policy.get("initial_interval")) is not None:
+        _set_duration_field(out.initial_interval, cast(timedelta, ii))
+
+    if (coef := policy.get("backoff_coefficient")) is not None:
+        coef_f = cast(float, coef)
+        if coef_f < 1.0:
+            raise ValueError("backoff_coefficient must be >= 1.0 when provided")
+        out.backoff_coefficient = coef_f
+
+    if (mi := policy.get("maximum_interval")) is not None:
+        _set_duration_field(out.maximum_interval, cast(timedelta, mi))
+
+    if (ma := policy.get("maximum_attempts")) is not None:
+        out.maximum_attempts = int(cast(int, ma))
+
+    if (reasons := policy.get("non_retryable_error_reasons")) is not None:
+        out.non_retryable_error_reasons.extend(cast(list[str], reasons))
+
+    if (ei := policy.get("expiration_interval")) is not None:
+        _set_duration_field(out.expiration_interval, cast(timedelta, ei))
+
+    return out

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/workflow/statemachine/event_dispatcher.py

@@ -21,7 +21,7 @@ class Action:
 class EventDispatcher:
     handlers: dict[Type, Action]
 
-    def __init__(self, default_id_attr: str) -> None:
+    def __init__(self, default_id_attr: str = "") -> None:
         self._default_id_attr = default_id_attr
         self.handlers = {}
 
@@ -32,7 +32,8 @@ class EventDispatcher:
             event_type = _find_event_type(func)
             event_id_attr = id_attr if id_attr else self._default_id_attr
 
-            _validate_field(func, event_type, event_id_attr)
+            if event_id_attr:
+                _validate_field(func, event_type, event_id_attr)
             if event_type in self.handlers:
                 raise ValueError(
                     f"Duplicate handler for {event_type}: {func.__qualname__} and {self.handlers[event_type].fn.__qualname__}"

cadence_python_client-0.2.2/cadence/_internal/workflow/waiter.py

@@ -0,0 +1,37 @@
+from asyncio import AbstractEventLoop, Future
+from typing import Callable, Any, Generator, Awaitable
+
+
+class Waiter(Awaitable[None]):
+    """Awaitable that resolves when ``predicate()`` becomes truthy."""
+
+    __slots__ = ("_predicate", "_future")
+
+    def __init__(self, predicate: Callable[[], bool], loop: AbstractEventLoop) -> None:
+        self._predicate = predicate
+        self._future: Future[None] = loop.create_future()
+
+    def __await__(self) -> Generator[Any, None, None]:
+        return self._future.__await__()
+
+    def done(self) -> bool:
+        return self._future.done()
+
+    def exception(self) -> BaseException | None:
+        return self._future.exception()
+
+    def result(self) -> None:
+        self._future.result()
+
+    def poll(self) -> bool:
+        """Re-evaluate the predicate. Returns True when settled (and evictable)."""
+        if self._future.done():
+            return True
+        try:
+            if self._predicate():
+                self._future.set_result(None)
+                return True
+            return False
+        except BaseException as exc:
+            self._future.set_exception(exc)
+            return True

{cadence_python_client-0.2.1 → cadence_python_client-0.2.2}/cadence/_internal/workflow/workflow_engine.py

@@ -2,6 +2,7 @@ import logging
 import traceback
 from asyncio import CancelledError, InvalidStateError
 from dataclasses import dataclass
+from functools import singledispatchmethod
 from typing import List, Optional
 
 from cadence._internal.workflow.context import Context
@@ -12,16 +13,16 @@ from cadence._internal.workflow.deterministic_event_loop import (
 )
 from cadence._internal.workflow.statemachine.decision_manager import DecisionManager
 from cadence._internal.workflow.workflow_instance import WorkflowInstance
-from cadence.api.v1 import history
-from cadence.api.v1.common_pb2 import Failure, WorkflowType
 from cadence.api.v1.decision_pb2 import (
     Decision,
     FailWorkflowExecutionDecisionAttributes,
     CompleteWorkflowExecutionDecisionAttributes,
     ContinueAsNewWorkflowExecutionDecisionAttributes,
 )
+from cadence.api.v1.common_pb2 import Failure, WorkflowType
 from cadence.api.v1.history_pb2 import (
     HistoryEvent,
+    WorkflowExecutionSignaledEventAttributes,
     WorkflowExecutionStartedEventAttributes,
 )
 from cadence.api.v1.tasklist_pb2 import TaskList
@@ -162,15 +163,19 @@ class WorkflowEngine:
                     # Process through state machines (DecisionsHelper now delegates to DecisionManager)
                     self._decision_manager.handle_history_event(marker_event)
 
-                # Phase 2: Process regular input events
+                # Phase 2: Apply input events in history order.
                 for event in decision_events.input:
                     self._apply_input_event(event)
 
                 # Phase 3: Execute workflow logic
                 self._workflow_instance.run_until_yield()
 
-                # If the workflow function returned (or threw an exception), we're done
-                # If it completed early (or late), the nondeterminism tracking will catch that
+                # Signal handler failures fail the decision task, not the workflow.
+                if (
+                    signal_failure := self._workflow_instance.get_signal_failure()
+                ) is not None:
+                    raise signal_failure
+
                 if decision := self._maybe_complete_workflow():
                     self._decision_manager.complete_workflow(decision)
 
@@ -228,29 +233,29 @@ class WorkflowEngine:
                 )
             )
 
-    def _apply_input_event(self, event: history.HistoryEvent) -> None:
-        logger.debug(
-            "Processing history event",
-            extra={
-                "workflow_id": self._context.info().workflow_id,
-                "event_type": getattr(event, "event_type", "unknown"),
-                "event_id": getattr(event, "event_id", None),
-                "replay_mode": self._context.is_replay_mode(),
-            },
-        )
-        # start workflow on workflow started event
-        if (
-            event.WhichOneof("attributes")
-            == "workflow_execution_started_event_attributes"
-        ):
-            started_attrs: WorkflowExecutionStartedEventAttributes = (
-                event.workflow_execution_started_event_attributes
-            )
-            if started_attrs and hasattr(started_attrs, "input"):
-                self._workflow_instance.start(started_attrs.input)
+    def _apply_input_event(self, event: HistoryEvent) -> None:
+        attr = event.WhichOneof("attributes")
+        if attr is None:
+            self._decision_manager.handle_history_event(event)
+            return
+        self._handle_input_event(getattr(event, attr), event)
 
+    @singledispatchmethod
+    def _handle_input_event(self, attrs: object, event: HistoryEvent) -> None:
         self._decision_manager.handle_history_event(event)
 
+    @_handle_input_event.register
+    def _handle_started_input_event(
+        self, attrs: WorkflowExecutionStartedEventAttributes, event: HistoryEvent
+    ) -> None:
+        self._workflow_instance.start(attrs.input)
+
+    @_handle_input_event.register
+    def _handle_signaled_input_event(
+        self, attrs: WorkflowExecutionSignaledEventAttributes, event: HistoryEvent
+    ) -> None:
+        self._workflow_instance.handle_signal(attrs.signal_name, attrs.input)
+
 
 def _failure_from_exception(e: Exception) -> Failure:
     stacktrace = "".join(traceback.format_exception(e))