cadence-python-client 0.1.0__py3-none-any.whl

cadence/sample/simple_usage_example.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Simple usage example for cadence protobuf modules.
+This demonstrates basic usage patterns for the generated protobuf classes.
+"""
+
+import sys
+import os
+
+# Add the project root to the path so we can import cadence modules
+project_root = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
+sys.path.insert(0, project_root)
+
+
+def example_workflow_execution():
+    """Example of creating and using WorkflowExecution objects."""
+    print("=== Workflow Execution Example ===")
+
+    from cadence.api.v1 import common, workflow
+
+    # Create a workflow execution
+    wf_exec = common.WorkflowExecution()
+    wf_exec.workflow_id = "my-workflow-123"
+    wf_exec.run_id = "run-456"
+
+    print("Created workflow execution:")
+    print(f"  - Workflow ID: {wf_exec.workflow_id}")
+    print(f"  - Run ID: {wf_exec.run_id}")
+
+    # Create workflow execution info
+    wf_info = workflow.WorkflowExecutionInfo()
+    wf_info.workflow_execution.CopyFrom(wf_exec)
+    wf_info.type.name = "MyWorkflowType"
+    wf_info.start_time.seconds = 1234567890
+    wf_info.close_time.seconds = 1234567990
+
+    print("Created workflow execution info:")
+    print(f"  - Type: {wf_info.type.name}")
+    print(f"  - Start Time: {wf_info.start_time.seconds}")
+    print(f"  - Close Time: {wf_info.close_time.seconds}")
+
+    return wf_exec, wf_info
+
+
+def example_domain_operations():
+    """Example of creating and using Domain objects."""
+    print("\n=== Domain Operations Example ===")
+
+    from cadence.api.v1 import domain
+
+    # Create a domain
+    domain_obj = domain.Domain()
+    domain_obj.name = "my-domain"
+    domain_obj.status = domain.DOMAIN_STATUS_REGISTERED
+    domain_obj.description = "My test domain"
+
+    print("Created domain:")
+    print(f"  - Name: {domain_obj.name}")
+    print(f"  - Status: {domain_obj.status}")
+    print(f"  - Description: {domain_obj.description}")
+
+    return domain_obj
+
+
+def example_enum_usage():
+    """Example of using enum values."""
+    print("\n=== Enum Usage Example ===")
+
+    from cadence.api.v1 import workflow
+
+    # Workflow execution close status
+    print("Workflow Execution Close Status:")
+    print(f"  - COMPLETED: {workflow.WORKFLOW_EXECUTION_CLOSE_STATUS_COMPLETED}")
+    print(f"  - FAILED: {workflow.WORKFLOW_EXECUTION_CLOSE_STATUS_FAILED}")
+    print(f"  - CANCELED: {workflow.WORKFLOW_EXECUTION_CLOSE_STATUS_CANCELED}")
+    print(f"  - TERMINATED: {workflow.WORKFLOW_EXECUTION_CLOSE_STATUS_TERMINATED}")
+    print(f"  - TIMED_OUT: {workflow.WORKFLOW_EXECUTION_CLOSE_STATUS_TIMED_OUT}")
+
+    # Timeout types
+    print("\nTimeout Types:")
+    print(f"  - START_TO_CLOSE: {workflow.TIMEOUT_TYPE_START_TO_CLOSE}")
+    print(f"  - SCHEDULE_TO_CLOSE: {workflow.TIMEOUT_TYPE_SCHEDULE_TO_CLOSE}")
+    print(f"  - SCHEDULE_TO_START: {workflow.TIMEOUT_TYPE_SCHEDULE_TO_START}")
+    print(f"  - HEARTBEAT: {workflow.TIMEOUT_TYPE_HEARTBEAT}")
+
+    # Parent close policies
+    print("\nParent Close Policies:")
+    print(f"  - TERMINATE: {workflow.PARENT_CLOSE_POLICY_TERMINATE}")
+    print(f"  - ABANDON: {workflow.PARENT_CLOSE_POLICY_ABANDON}")
+    print(f"  - REQUEST_CANCEL: {workflow.PARENT_CLOSE_POLICY_REQUEST_CANCEL}")
+
+
+def example_serialization():
+    """Example of serializing and deserializing protobuf objects."""
+    print("\n=== Serialization Example ===")
+
+    from cadence.api.v1 import common
+
+    # Create a workflow execution
+    wf_exec = common.WorkflowExecution()
+    wf_exec.workflow_id = "serialization-test"
+    wf_exec.run_id = "run-789"
+
+    # Serialize to bytes
+    serialized = wf_exec.SerializeToString()
+    print(f"Serialized size: {len(serialized)} bytes")
+
+    # Deserialize from bytes
+    new_wf_exec = common.WorkflowExecution()
+    new_wf_exec.ParseFromString(serialized)
+
+    print("Deserialized workflow execution:")
+    print(f"  - Workflow ID: {new_wf_exec.workflow_id}")
+    print(f"  - Run ID: {new_wf_exec.run_id}")
+
+    # Verify they're equal
+    if (
+        wf_exec.workflow_id == new_wf_exec.workflow_id
+        and wf_exec.run_id == new_wf_exec.run_id
+    ):
+        print("✓ Serialization/deserialization successful!")
+    else:
+        print("✗ Serialization/deserialization failed!")
+
+
+def main():
+    """Main example function."""
+    print("🚀 Cadence Protobuf Usage Examples")
+    print("=" * 50)
+
+    try:
+        # Run all examples
+        example_workflow_execution()
+        example_domain_operations()
+        example_enum_usage()
+        example_serialization()
+
+        print("\n" + "=" * 50)
+        print("✅ All examples completed successfully!")
+        print("The protobuf modules are working correctly and ready for use.")
+
+    except Exception as e:
+        print(f"\n❌ Example failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    exit(main())

cadence/signal.py

@@ -0,0 +1,174 @@
+"""
+Signal definition for Cadence workflows.
+
+This module provides the SignalDefinition class used internally by WorkflowDefinition
+to track signal handler metadata.
+"""
+
+import inspect
+from dataclasses import dataclass
+from functools import update_wrapper
+from inspect import Parameter, signature
+from typing import (
+    Callable,
+    Generic,
+    ParamSpec,
+    Type,
+    TypeVar,
+    TypedDict,
+    get_type_hints,
+    Any,
+)
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class SignalParameter:
+    """Parameter metadata for a signal handler."""
+
+    name: str
+    type_hint: Type | None
+    has_default: bool
+    default_value: Any
+
+
+class SignalDefinitionOptions(TypedDict, total=False):
+    """Options for defining a signal."""
+
+    name: str
+
+
+class SignalDefinition(Generic[P, T]):
+    """
+    Definition of a signal handler with metadata.
+
+    Similar to ActivityDefinition but for signal handlers.
+    Provides type safety and metadata for signal handlers.
+    """
+
+    def __init__(
+        self,
+        wrapped: Callable[P, T],
+        name: str,
+        params: list[SignalParameter],
+        is_async: bool,
+    ):
+        self._wrapped = wrapped
+        self._name = name
+        self._params = params
+        self._is_async = is_async
+        update_wrapper(self, wrapped)
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+        """Call the wrapped signal handler function."""
+        return self._wrapped(*args, **kwargs)
+
+    @property
+    def name(self) -> str:
+        """Get the signal name."""
+        return self._name
+
+    @property
+    def params(self) -> list[SignalParameter]:
+        """Get the signal parameters."""
+        return self._params
+
+    @property
+    def is_async(self) -> bool:
+        """Check if the signal handler is async."""
+        return self._is_async
+
+    @property
+    def wrapped(self) -> Callable[P, T]:
+        """Get the wrapped signal handler function."""
+        return self._wrapped
+
+    @staticmethod
+    def wrap(
+        fn: Callable[P, T], opts: SignalDefinitionOptions
+    ) -> "SignalDefinition[P, T]":
+        """
+        Wrap a function as a SignalDefinition.
+
+        This is an internal method used by WorkflowDefinition to create signal definitions
+        from methods decorated with @workflow.signal.
+
+        Args:
+            fn: The signal handler function to wrap
+            opts: Options for the signal definition
+
+        Returns:
+            A SignalDefinition instance
+
+        Raises:
+            ValueError: If return type is not None
+        """
+        name = opts.get("name") or fn.__qualname__
+        is_async = inspect.iscoroutinefunction(fn)
+        params = _get_signal_signature(fn)
+        _validate_signal_return_type(fn)
+
+        return SignalDefinition[P, T](fn, name, params, is_async)
+
+
+def _validate_signal_return_type(fn: Callable) -> None:
+    """
+    Validate that signal handler returns None.
+
+    Args:
+        fn: The signal handler function
+
+    Raises:
+        ValueError: If return type is not None
+    """
+    try:
+        hints = get_type_hints(fn)
+        ret_type = hints.get("return", inspect.Signature.empty)
+
+        if ret_type is not None and ret_type is not inspect.Signature.empty:
+            raise ValueError(
+                f"Signal handler '{fn.__qualname__}' must return None "
+                f"(signals cannot return values), got {ret_type}"
+            )
+    except NameError:
+        pass
+
+
+def _get_signal_signature(fn: Callable[P, T]) -> list[SignalParameter]:
+    """
+    Extract parameter information from a signal handler function.
+
+    Args:
+        fn: The signal handler function
+
+    Returns:
+        List of SignalParameter objects
+
+    Raises:
+        ValueError: If parameters are not positional
+    """
+    sig = signature(fn)
+    args = sig.parameters
+    hints = get_type_hints(fn)
+    params = []
+
+    for name, param in args.items():
+        # Filter out the self parameter for instance methods
+        if param.name == "self":
+            continue
+
+        has_default = param.default != Parameter.empty
+        default = param.default if has_default else None
+
+        if param.kind in (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD):
+            type_hint = hints.get(name, None)
+            params.append(SignalParameter(name, type_hint, has_default, default))
+        else:
+            raise ValueError(
+                f"Signal handler '{fn.__qualname__}' parameter '{name}' must be positional, "
+                f"got {param.kind.name}"
+            )
+
+    return params

cadence/worker/__init__.py

@@ -0,0 +1,13 @@
+from ._worker import Worker, WorkerOptions
+
+from ._registry import (
+    Registry,
+    RegisterWorkflowOptions,
+)
+
+__all__ = [
+    "Worker",
+    "WorkerOptions",
+    "Registry",
+    "RegisterWorkflowOptions",
+]

cadence/worker/_activity.py

@@ -0,0 +1,60 @@
+import asyncio
+from typing import Optional
+
+from cadence._internal.activity import ActivityExecutor
+from cadence.api.v1.service_worker_pb2 import (
+    PollForActivityTaskResponse,
+    PollForActivityTaskRequest,
+)
+from cadence.api.v1.tasklist_pb2 import TaskList, TaskListKind
+from cadence.client import Client
+from cadence.worker._registry import Registry
+from cadence.worker._types import WorkerOptions, _LONG_POLL_TIMEOUT
+from cadence.worker._poller import Poller
+
+
+class ActivityWorker:
+    def __init__(
+        self, client: Client, task_list: str, registry: Registry, options: WorkerOptions
+    ) -> None:
+        self._client = client
+        self._task_list = task_list
+        self._identity = options["identity"]
+        max_concurrent = options["max_concurrent_activity_execution_size"]
+        permits = asyncio.Semaphore(max_concurrent)
+        self._executor = ActivityExecutor(
+            self._client,
+            self._task_list,
+            options["identity"],
+            max_concurrent,
+            registry.get_activity,
+        )
+        self._poller = Poller[PollForActivityTaskResponse](
+            options["activity_task_pollers"], permits, self._poll, self._execute
+        )
+        # TODO: Local dispatch, local activities, actually running activities, etc
+
+    async def run(self) -> None:
+        await self._poller.run()
+
+    async def _poll(self) -> Optional[PollForActivityTaskResponse]:
+        task: PollForActivityTaskResponse = (
+            await self._client.worker_stub.PollForActivityTask(
+                PollForActivityTaskRequest(
+                    domain=self._client.domain,
+                    task_list=TaskList(
+                        name=self._task_list, kind=TaskListKind.TASK_LIST_KIND_NORMAL
+                    ),
+                    identity=self._identity,
+                ),
+                timeout=_LONG_POLL_TIMEOUT,
+            )
+        )
+
+        if task.task_token:
+            return task
+        else:
+            return None
+
+    async def _execute(self, task: PollForActivityTaskResponse) -> None:
+        await self._executor.execute(task)

cadence/worker/_base_task_handler.py

@@ -0,0 +1,71 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class BaseTaskHandler(ABC, Generic[T]):
+    """
+    Base task handler that provides common functionality for processing tasks.
+
+    This abstract class defines the interface and common behavior for task handlers
+    that process different types of tasks (workflow decisions, activities, etc.).
+    """
+
+    def __init__(self, client, task_list: str, identity: str, **options):
+        """
+        Initialize the base task handler.
+
+        Args:
+            client: The Cadence client instance
+            task_list: The task list name
+            identity: Worker identity
+            **options: Additional options for the handler
+        """
+        self._client = client
+        self.task_list = task_list
+        self._identity = identity
+        self._options = options
+
+    async def handle_task(self, task: T) -> None:
+        """
+        Handle a single task.
+
+        This method provides the base implementation for task handling that includes:
+        - Error handling
+        - Cleanup
+
+        Args:
+            task: The task to handle
+        """
+        try:
+            # Handle the task implementation
+            await self._handle_task_implementation(task)
+
+        except Exception as e:
+            logger.exception(f"Error handling task: {e}")
+            await self.handle_task_failure(task, e)
+
+    @abstractmethod
+    async def _handle_task_implementation(self, task: T) -> None:
+        """
+        Handle the actual task implementation.
+
+        Args:
+            task: The task to handle
+        """
+        pass
+
+    @abstractmethod
+    async def handle_task_failure(self, task: T, error: Exception) -> None:
+        """
+        Handle task processing failure.
+
+        Args:
+            task: The task that failed
+            error: The exception that occurred
+        """
+        pass

cadence/worker/_decision.py

@@ -0,0 +1,62 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional
+
+from cadence.api.v1.service_worker_pb2 import (
+    PollForDecisionTaskRequest,
+    PollForDecisionTaskResponse,
+)
+from cadence.api.v1.tasklist_pb2 import TaskList, TaskListKind
+from cadence.client import Client
+from cadence.worker._decision_task_handler import DecisionTaskHandler
+from cadence.worker._poller import Poller
+from cadence.worker._registry import Registry
+from cadence.worker._types import _LONG_POLL_TIMEOUT, WorkerOptions
+
+
+class DecisionWorker:
+    def __init__(
+        self, client: Client, task_list: str, registry: Registry, options: WorkerOptions
+    ) -> None:
+        self._client = client
+        self._task_list = task_list
+        self._registry = registry
+        self._identity = options["identity"]
+        permits = asyncio.Semaphore(
+            options["max_concurrent_decision_task_execution_size"]
+        )
+        executor = ThreadPoolExecutor(
+            max_workers=options["max_concurrent_decision_task_execution_size"]
+        )
+        self._decision_handler = DecisionTaskHandler(
+            client, task_list, registry, executor=executor, **options
+        )
+        self._poller = Poller[PollForDecisionTaskResponse](
+            options["decision_task_pollers"], permits, self._poll, self._execute
+        )
+        # TODO: Sticky poller, actually running workflows, etc.
+
+    async def run(self) -> None:
+        await self._poller.run()
+
+    async def _poll(self) -> Optional[PollForDecisionTaskResponse]:
+        task: PollForDecisionTaskResponse = (
+            await self._client.worker_stub.PollForDecisionTask(
+                PollForDecisionTaskRequest(
+                    domain=self._client.domain,
+                    task_list=TaskList(
+                        name=self._task_list, kind=TaskListKind.TASK_LIST_KIND_NORMAL
+                    ),
+                    identity=self._identity,
+                ),
+                timeout=_LONG_POLL_TIMEOUT,
+            )
+        )
+
+        if task and task.task_token:
+            return task
+        else:
+            return None
+
+    async def _execute(self, task: PollForDecisionTaskResponse) -> None:
+        await self._decision_handler.handle_task(task)