cadence-python-client 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

cadence/_internal/rpc/error.py

@@ -1,7 +1,7 @@
-from typing import Callable, Any, Optional, Generator, TypeVar
+from typing import Callable, Any, Optional, Generator, TypeVar, cast
 
 import grpc
-from google.rpc.status_pb2 import Status  # type: ignore
+from google.rpc.status_pb2 import Status
 from grpc.aio import (
     UnaryUnaryClientInterceptor,
     ClientCallDetails,
@@ -9,7 +9,7 @@ from grpc.aio import (
     UnaryUnaryCall,
     Metadata,
 )
-from grpc_status.rpc_status import from_call  # type: ignore
+from grpc_status.rpc_status import from_call
 
 from cadence.api.v1 import error_pb2
 from cadence import error
@@ -46,22 +46,22 @@ class CadenceErrorUnaryUnaryCall(UnaryUnaryCall[RequestType, ResponseType]):
         return await self._wrapped.code()
 
     async def details(self) -> str:
-        return await self._wrapped.details()  # type: ignore
+        return await self._wrapped.details()
 
     async def wait_for_connection(self) -> None:
         await self._wrapped.wait_for_connection()
 
     def cancelled(self) -> bool:
-        return self._wrapped.cancelled()  # type: ignore
+        return self._wrapped.cancelled()
 
     def done(self) -> bool:
-        return self._wrapped.done()  # type: ignore
+        return self._wrapped.done()
 
     def time_remaining(self) -> Optional[float]:
-        return self._wrapped.time_remaining()  # type: ignore
+        return self._wrapped.time_remaining()
 
     def cancel(self) -> bool:
-        return self._wrapped.cancel()  # type: ignore
+        return self._wrapped.cancel()
 
     def add_done_callback(self, callback: DoneCallbackType) -> None:
         self._wrapped.add_done_callback(callback)
@@ -79,16 +79,18 @@ class CadenceErrorInterceptor(UnaryUnaryClientInterceptor):
 
 
 def map_error(e: AioRpcError) -> error.CadenceRpcError:
-    status: Status | None = from_call(e)
+    # AioRpcError implements the grpc.Call interface but doesn't inherit from it in the type stubs
+    status: Status | None = from_call(cast(grpc.Call, e))
+    message = e.details() or ""
     if not status or not status.details:
-        return error.CadenceRpcError(e.details(), e.code())
+        return error.CadenceRpcError(message, e.code())
 
     details = status.details[0]
     if details.Is(error_pb2.WorkflowExecutionAlreadyStartedError.DESCRIPTOR):
         already_started = error_pb2.WorkflowExecutionAlreadyStartedError()
         details.Unpack(already_started)
         return error.WorkflowExecutionAlreadyStartedError(
-            e.details(),
+            message,
             e.code(),
             already_started.start_request_id,
             already_started.run_id,
@@ -97,19 +99,19 @@ def map_error(e: AioRpcError) -> error.CadenceRpcError:
         not_exists = error_pb2.EntityNotExistsError()
         details.Unpack(not_exists)
         return error.EntityNotExistsError(
-            e.details(),
+            message,
             e.code(),
             not_exists.current_cluster,
             not_exists.active_cluster,
             list(not_exists.active_clusters),
         )
     elif details.Is(error_pb2.WorkflowExecutionAlreadyCompletedError.DESCRIPTOR):
-        return error.WorkflowExecutionAlreadyCompletedError(e.details(), e.code())
+        return error.WorkflowExecutionAlreadyCompletedError(message, e.code())
     elif details.Is(error_pb2.DomainNotActiveError.DESCRIPTOR):
         not_active = error_pb2.DomainNotActiveError()
         details.Unpack(not_active)
         return error.DomainNotActiveError(
-            e.details(),
+            message,
             e.code(),
             not_active.domain,
             not_active.current_cluster,
@@ -120,7 +122,7 @@ def map_error(e: AioRpcError) -> error.CadenceRpcError:
         not_supported = error_pb2.ClientVersionNotSupportedError()
         details.Unpack(not_supported)
         return error.ClientVersionNotSupportedError(
-            e.details(),
+            message,
             e.code(),
             not_supported.feature_version,
             not_supported.client_impl,
@@ -129,20 +131,18 @@ def map_error(e: AioRpcError) -> error.CadenceRpcError:
     elif details.Is(error_pb2.FeatureNotEnabledError.DESCRIPTOR):
         not_enabled = error_pb2.FeatureNotEnabledError()
         details.Unpack(not_enabled)
-        return error.FeatureNotEnabledError(
-            e.details(), e.code(), not_enabled.feature_flag
-        )
+        return error.FeatureNotEnabledError(message, e.code(), not_enabled.feature_flag)
     elif details.Is(error_pb2.CancellationAlreadyRequestedError.DESCRIPTOR):
-        return error.CancellationAlreadyRequestedError(e.details(), e.code())
+        return error.CancellationAlreadyRequestedError(message, e.code())
     elif details.Is(error_pb2.DomainAlreadyExistsError.DESCRIPTOR):
-        return error.DomainAlreadyExistsError(e.details(), e.code())
+        return error.DomainAlreadyExistsError(message, e.code())
     elif details.Is(error_pb2.LimitExceededError.DESCRIPTOR):
-        return error.LimitExceededError(e.details(), e.code())
+        return error.LimitExceededError(message, e.code())
     elif details.Is(error_pb2.QueryFailedError.DESCRIPTOR):
-        return error.QueryFailedError(e.details(), e.code())
+        return error.QueryFailedError(message, e.code())
     elif details.Is(error_pb2.ServiceBusyError.DESCRIPTOR):
         service_busy = error_pb2.ServiceBusyError()
         details.Unpack(service_busy)
-        return error.ServiceBusyError(e.details(), e.code(), service_busy.reason)
+        return error.ServiceBusyError(message, e.code(), service_busy.reason)
     else:
-        return error.CadenceRpcError(e.details(), e.code())
+        return error.CadenceRpcError(message, e.code())

cadence/_internal/rpc/retry.py

@@ -1,6 +1,6 @@
 import asyncio
 from dataclasses import dataclass
-from typing import Callable, Any
+from typing import Callable, Any, cast
 
 from grpc import StatusCode
 from grpc.aio import UnaryUnaryClientInterceptor, ClientCallDetails
@@ -59,19 +59,23 @@ class RetryInterceptor(UnaryUnaryClientInterceptor):
         request: Any,
     ) -> Any:
         loop = asyncio.get_running_loop()
-        expiration_interval = client_call_details.timeout
-        if expiration_interval is None:
-            expiration_interval = float("inf")
+        expiration_interval = (
+            client_call_details.timeout
+            if client_call_details.timeout is not None
+            else float("inf")
+        )
         start_time = loop.time()
         deadline = start_time + expiration_interval
 
         attempts = 0
         while True:
             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(  # type: ignore[attr-defined]
-                timeout=remaining
+            call_details = ClientCallDetails(
+                method=client_call_details.method,
+                timeout=remaining,
+                metadata=client_call_details.metadata,
+                credentials=client_call_details.credentials,
+                wait_for_ready=client_call_details.wait_for_ready,
             )
             rpc_call = await continuation(call_details, request)
             try:
@@ -98,11 +102,11 @@ 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  # type: ignore[comparison-overlap]
-        and isinstance(err, EntityNotExistsError)
-    ):
+    # Handle requests to the passive side, matching the Go and Java Clients.
+    # grpc-stubs types method as str, but grpcio corrected it to bytes in v1.75.0
+    # (grpc/grpc#39405). Cast to bytes to match the actual runtime type.
+    method = cast(bytes, call_details.method)
+    if method == GET_WORKFLOW_HISTORY and isinstance(err, EntityNotExistsError):
         return (
             err.active_cluster is not None
             and err.current_cluster is not None

cadence/_internal/rpc/yarpc.py

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

cadence/_internal/workflow/context.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from contextlib import contextmanager
 from asyncio import get_running_loop
 from datetime import timedelta
@@ -5,17 +7,23 @@ from math import ceil
 from typing import Iterator, Optional, Any, Unpack, Type, cast, Callable
 
 from cadence._internal.workflow.deterministic_event_loop import DeterministicEventLoop
+from cadence._internal.workflow.memo import memo_to_proto
 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 import workflow_pb2
+from cadence.api.v1.common_pb2 import ActivityType, WorkflowType, WorkflowExecution
 from cadence.api.v1.decision_pb2 import (
     ScheduleActivityTaskDecisionAttributes,
+    SignalExternalWorkflowExecutionDecisionAttributes,
+    StartChildWorkflowExecutionDecisionAttributes,
     StartTimerDecisionAttributes,
 )
 from cadence.api.v1.tasklist_pb2 import TaskList, TaskListKind
 from cadence.data_converter import DataConverter
 from cadence.workflow import (
     ActivityOptions,
+    ChildWorkflowFuture,
+    ChildWorkflowOptions,
     ResultType,
     WorkflowContext,
     WorkflowInfo,
@@ -105,6 +113,131 @@ class Context(WorkflowContext):
 
         return cast(ResultType, result)
 
+    async def execute_child_workflow(
+        self,
+        workflow_type: str,
+        result_type: Type[ResultType],
+        *args: Any,
+        **kwargs: Unpack[ChildWorkflowOptions],
+    ) -> ResultType:
+        future = await self.start_child_workflow(
+            workflow_type, result_type, *args, **kwargs
+        )
+        return await future
+
+    async def start_child_workflow(
+        self,
+        workflow_type: str,
+        result_type: Type[ResultType],
+        *args: Any,
+        **kwargs: Unpack[ChildWorkflowOptions],
+    ) -> ChildWorkflowFuture[ResultType]:
+        schedule_attributes = self._build_child_workflow_attrs(
+            workflow_type, *args, **kwargs
+        )
+        execution_future, result_future = (
+            self._decision_manager.schedule_child_workflow(
+                schedule_attributes,
+                parent_workflow_run_id=self._info.workflow_run_id,
+            )
+        )
+        workflow_execution = await execution_future
+        return ChildWorkflowFuture(
+            workflow_id=workflow_execution.workflow_id,
+            run_id=workflow_execution.run_id,
+            result_future=result_future,
+            result_type=result_type,
+            data_converter=self.data_converter(),
+        )
+
+    def _build_child_workflow_attrs(
+        self,
+        workflow_type: str,
+        *args: Any,
+        **kwargs: Unpack[ChildWorkflowOptions],
+    ) -> StartChildWorkflowExecutionDecisionAttributes:
+        execution_timeout = kwargs.get("execution_start_to_close_timeout")
+        if execution_timeout is None:
+            raise ValueError(
+                "execution_start_to_close_timeout is required for child workflow execution"
+            )
+        if execution_timeout <= timedelta(0):
+            raise ValueError("execution_start_to_close_timeout must be greater than 0")
+
+        task_timeout = kwargs.get("task_start_to_close_timeout", timedelta(seconds=10))
+        if task_timeout <= timedelta(0):
+            raise ValueError("task_start_to_close_timeout must be greater than 0")
+
+        domain = kwargs.get("domain") or self._info.workflow_domain
+        task_list = kwargs.get("task_list") or self._info.workflow_task_list
+
+        workflow_id = kwargs.get("workflow_id") or ""
+
+        parent_close_policy = kwargs.get(
+            "parent_close_policy",
+            workflow_pb2.PARENT_CLOSE_POLICY_TERMINATE,
+        )
+        workflow_id_reuse_policy = kwargs.get(
+            "workflow_id_reuse_policy",
+            workflow_pb2.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY,
+        )
+        if workflow_id_reuse_policy == workflow_pb2.WORKFLOW_ID_REUSE_POLICY_INVALID:
+            raise ValueError(
+                "workflow_id_reuse_policy cannot be WORKFLOW_ID_REUSE_POLICY_INVALID"
+            )
+
+        child_input = self.data_converter().to_data(list(args))
+        schedule_attributes = StartChildWorkflowExecutionDecisionAttributes(
+            domain=domain,
+            workflow_id=workflow_id,
+            workflow_type=WorkflowType(name=workflow_type),
+            task_list=TaskList(kind=TaskListKind.TASK_LIST_KIND_NORMAL, name=task_list),
+            input=child_input,
+            execution_start_to_close_timeout=_round_to_nearest_second(
+                execution_timeout
+            ),
+            task_start_to_close_timeout=_round_to_nearest_second(task_timeout),
+            parent_close_policy=parent_close_policy,
+            workflow_id_reuse_policy=workflow_id_reuse_policy,
+            retry_policy=retry_policy_to_proto(kwargs.get("retry_policy")),
+        )
+
+        cron_schedule = kwargs.get("cron_schedule")
+        if cron_schedule:
+            schedule_attributes.cron_schedule = cron_schedule
+
+        memo_proto = memo_to_proto(self.data_converter(), kwargs.get("memo"))
+        if memo_proto is not None:
+            schedule_attributes.memo.CopyFrom(memo_proto)
+
+        return schedule_attributes
+
+    async def signal_child_workflow(
+        self,
+        child_workflow_id: str,
+        signal_name: str,
+        *args: Any,
+    ) -> None:
+        if not child_workflow_id:
+            raise ValueError("child_workflow_id must not be empty")
+        await self._signal_workflow(
+            child_workflow_id, signal_name, args, child_workflow_only=True
+        )
+
+    async def signal_external_workflow(
+        self,
+        workflow_id: str,
+        signal_name: str,
+        *args: Any,
+        run_id: str = "",
+        domain: str = "",
+    ) -> None:
+        if not workflow_id:
+            raise ValueError("workflow_id must not be empty")
+        await self._signal_workflow(
+            workflow_id, signal_name, args, run_id=run_id, domain=domain
+        )
+
     async def start_timer(self, duration: timedelta):
         if duration.total_seconds() <= 0:  # shortcut
             return
@@ -143,6 +276,30 @@ class Context(WorkflowContext):
         finally:
             WorkflowContext._var.reset(token)
 
+    async def _signal_workflow(
+        self,
+        workflow_id: str,
+        signal_name: str,
+        args: tuple,
+        *,
+        run_id: str = "",
+        domain: str = "",
+        child_workflow_only: bool = False,
+    ) -> None:
+        if not signal_name:
+            raise ValueError("signal_name must not be empty")
+        attrs = SignalExternalWorkflowExecutionDecisionAttributes(
+            domain=domain or self._info.workflow_domain,
+            workflow_execution=WorkflowExecution(
+                workflow_id=workflow_id,
+                run_id=run_id,
+            ),
+            signal_name=signal_name,
+            input=self.data_converter().to_data(list(args)),
+            child_workflow_only=child_workflow_only,
+        )
+        await self._decision_manager.signal_external_workflow(attrs)
+
 
 def _round_to_nearest_second(delta: timedelta) -> timedelta:
     return timedelta(seconds=ceil(delta.total_seconds()))

cadence/_internal/workflow/memo.py

@@ -0,0 +1,40 @@
+"""Convert user memo maps to/from protobuf :class:`cadence.api.v1.common_pb2.Memo`."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from cadence.api.v1 import common_pb2
+from cadence.data_converter import DataConverter
+
+
+def memo_to_proto(
+    data_converter: DataConverter,
+    memo: Mapping[str, Any] | None,
+) -> common_pb2.Memo | None:
+    """Serialize ``memo`` to protobuf, or ``None`` if no memo was provided.
+
+    Each value is encoded as a single-element list via the data converter,
+    matching Go/Java SDK behavior (one :class:`Payload` per key).
+    """
+    if not memo:
+        return None
+    out = common_pb2.Memo()
+    for key, value in memo.items():
+        out.fields[key].CopyFrom(data_converter.to_data([value]))
+    return out
+
+
+def memo_from_proto(
+    data_converter: DataConverter,
+    memo: common_pb2.Memo,
+) -> dict[str, Any]:
+    """Deserialize a protobuf ``Memo`` back to a plain dict.
+
+    Each field payload was encoded as a single-element list; we unwrap that
+    first element to recover the original value.
+    """
+    return {
+        key: data_converter.from_data(payload, [None])[0]
+        for key, payload in memo.fields.items()
+    }

cadence/_internal/workflow/statemachine/child_workflow_execution_state_machine.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from cadence._internal.workflow.statemachine.decision_state_machine import (
+    BaseDecisionStateMachine,
+    DecisionFuture,
+    DecisionId,
+    DecisionState,
+    DecisionType,
+)
+from cadence._internal.workflow.statemachine.event_dispatcher import EventDispatcher
+from cadence._internal.workflow.statemachine.nondeterminism import (
+    record_immediate_cancel,
+)
+from cadence.api.v1 import decision, history
+from cadence.api.v1.common_pb2 import Payload, WorkflowExecution
+from cadence.error import (
+    ChildWorkflowExecutionCanceled,
+    ChildWorkflowExecutionFailed,
+    ChildWorkflowExecutionTerminated,
+    ChildWorkflowExecutionTimedOut,
+    StartChildWorkflowExecutionFailed,
+)
+
+child_workflow_events = EventDispatcher("initiated_event_id")
+
+
+class ChildWorkflowExecutionStateMachine(BaseDecisionStateMachine):
+    """State machine for StartChildWorkflowExecution and child close events."""
+
+    request: decision.StartChildWorkflowExecutionDecisionAttributes
+    execution: DecisionFuture[WorkflowExecution]
+    result: DecisionFuture[Payload]
+    _run_id: str | None
+
+    def __init__(
+        self,
+        request: decision.StartChildWorkflowExecutionDecisionAttributes,
+        execution: DecisionFuture[WorkflowExecution],
+        result: DecisionFuture[Payload],
+    ) -> None:
+        super().__init__()
+        self.request = request
+        self.execution = execution
+        self.result = result
+        self._run_id = None
+
+    def get_id(self) -> DecisionId:
+        return DecisionId(DecisionType.CHILD_WORKFLOW, self.request.workflow_id)
+
+    def get_decision(self) -> decision.Decision | None:
+        match self.state:
+            case DecisionState.REQUESTED:
+                return decision.Decision(
+                    start_child_workflow_execution_decision_attributes=self.request
+                )
+            case DecisionState.CANCELED_AFTER_REQUESTED:
+                return record_immediate_cancel(self.request)
+            case (
+                DecisionState.CANCELED_AFTER_RECORDED
+                | DecisionState.CANCELED_AFTER_STARTED
+            ):
+                return decision.Decision(
+                    request_cancel_external_workflow_execution_decision_attributes=decision.RequestCancelExternalWorkflowExecutionDecisionAttributes(
+                        domain=self.request.domain,
+                        workflow_execution=WorkflowExecution(
+                            workflow_id=self.request.workflow_id,
+                            run_id=self._run_id or "",
+                        ),
+                        child_workflow_only=True,
+                    )
+                )
+            case _:
+                return None
+
+    def request_cancel(self) -> bool:
+        match self.state:
+            case DecisionState.REQUESTED:
+                self._transition(DecisionState.CANCELED_AFTER_REQUESTED)
+                self.execution.force_cancel()
+                self.result.force_cancel()
+                return True
+            case DecisionState.RECORDED:
+                self._transition(DecisionState.CANCELED_AFTER_RECORDED)
+                self.execution.force_cancel()
+                return True
+            case DecisionState.STARTED:
+                self._transition(DecisionState.CANCELED_AFTER_STARTED)
+                return True
+            case _:
+                return False
+
+    @child_workflow_events.event("workflow_id", event_id_is_alias=True)
+    def handle_initiated(
+        self, _: history.StartChildWorkflowExecutionInitiatedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.RECORDED)
+
+    @child_workflow_events.event()
+    def handle_initiation_failed(
+        self, event: history.StartChildWorkflowExecutionFailedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        exc = StartChildWorkflowExecutionFailed(
+            f"start child failed: {event.cause}",
+            cause=event.cause,
+            workflow_id=event.workflow_id,
+        )
+        self.execution.set_exception(exc)
+        self.result.set_exception(exc)
+
+    @child_workflow_events.event()
+    def handle_started(
+        self, event: history.ChildWorkflowExecutionStartedEventAttributes
+    ) -> None:
+        self._run_id = event.workflow_execution.run_id
+        if self.state is DecisionState.CANCELED_AFTER_RECORDED:
+            self._transition(DecisionState.CANCELED_AFTER_STARTED)
+        else:
+            self._transition(DecisionState.STARTED)
+        if not self.execution.done():
+            self.execution.set_result(event.workflow_execution)
+
+    @child_workflow_events.event()
+    def handle_completed(
+        self, event: history.ChildWorkflowExecutionCompletedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.result.set_result(event.result)
+
+    @child_workflow_events.event()
+    def handle_failed(
+        self, event: history.ChildWorkflowExecutionFailedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.result.set_exception(
+            ChildWorkflowExecutionFailed(
+                event.failure.reason,
+                failure=event.failure,
+            )
+        )
+
+    @child_workflow_events.event()
+    def handle_canceled(
+        self, event: history.ChildWorkflowExecutionCanceledEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.result.set_exception(
+            ChildWorkflowExecutionCanceled(
+                "child workflow canceled", details=event.details
+            )
+        )
+
+    @child_workflow_events.event()
+    def handle_timed_out(
+        self, event: history.ChildWorkflowExecutionTimedOutEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.result.set_exception(
+            ChildWorkflowExecutionTimedOut(
+                f"child workflow timed out: {event.timeout_type}",
+                timeout_type=int(event.timeout_type),
+            )
+        )
+
+    @child_workflow_events.event()
+    def handle_terminated(
+        self, event: history.ChildWorkflowExecutionTerminatedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.COMPLETED)
+        self.result.set_exception(ChildWorkflowExecutionTerminated())
+
+    @child_workflow_events.event(
+        "workflow_execution.workflow_id", event_id_is_alias=True
+    )
+    def handle_cancel_initiated(
+        self, _: history.RequestCancelExternalWorkflowExecutionInitiatedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.CANCELLATION_RECORDED)
+
+    @child_workflow_events.event()
+    def handle_cancel_failed(
+        self, _: history.RequestCancelExternalWorkflowExecutionFailedEventAttributes
+    ) -> None:
+        self._transition(DecisionState.STARTED)