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

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/.github/workflows/ci_checks.yml

@@ -54,7 +54,7 @@ jobs:
           uv sync --extra dev --extra openai
       - name: Run mypy type checker
         run: |
-          uv run mypy cadence/
+          uv run mypy cadence/ tests/
 
   test:
     name: Unit Tests
@@ -74,7 +74,12 @@ jobs:
           uv sync --extra dev
       - name: Run unit tests
         run: |
-          uv run pytest -v
+          uv run pytest --integration-tests --cov --cov-branch --cov-report=xml
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: cadence-workflow/cadence-python-client
 
   integration_test:
     name: Integration Tests

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/Makefile

@@ -35,21 +35,27 @@ integration-test:
 	@echo "Running integration tests..."
 	uv run pytest -v --integration-tests
 
+integration-test-keep:
+	@echo "Running integration tests with cadence alive..."
+	uv run pytest -v --integration-tests --keep-cadence-alive
+
 # Clean generated files and caches
 clean:
 	@echo "Cleaning up..."
 	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
 	find . -type f -name "*.pyc" -delete 2>/dev/null || true
 	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	rm -rf .mypy_cache
 
 # Show help
 help:
 	@echo "Available targets:"
-	@echo "  make pr              - Run all PR checks (recommended before submitting PR)"
-	@echo "  make install         - Install dependencies"
-	@echo "  make lint            - Run Ruff linter"
-	@echo "  make type-check      - Run mypy type checker"
-	@echo "  make test            - Run unit tests"
-	@echo "  make integration-test - Run integration tests"
-	@echo "  make clean           - Remove generated files and caches"
-	@echo "  make help            - Show this help message"
+	@echo "  make pr                    - Run all PR checks (recommended before submitting PR)"
+	@echo "  make install         		- Install dependencies"
+	@echo "  make lint            		- Run Ruff linter"
+	@echo "  make type-check      		- Run mypy type checker"
+	@echo "  make test            		- Run unit tests"
+	@echo "  make integration-test 		- Run integration tests"
+	@echo "  make integration-test-keep - Run integration tests with cadence alive"
+	@echo "  make clean           		- Remove generated files and caches"
+	@echo "  make help            		- Show this help message"

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadence-python-client
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python framework for authoring Cadence workflows and activities
 Author: Cadence
 License: Apache-2.0
@@ -31,6 +31,7 @@ Requires-Dist: typing-extensions>=4.0.0
 Requires-Dist: prometheus-client>=0.21.0
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.73.1; extra == "dev"
+Requires-Dist: grpc-stubs>=1.53.0.6; extra == "dev"
 Requires-Dist: pytest>=8.4.1; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -68,11 +69,26 @@ If you'd like to propose a new feature, first join the [CNCF Slack workspace](ht
 **This SDK is currently an early work-in-progress (WIP) and is NOT ready for production use.**
 
 - This project is still in active development
-- It has not been published to any package repository (PyPI, etc.)
 - APIs and interfaces are subject to change without notice
 
 ## Installation
 
+Install from [PyPI](https://pypi.org/project/cadence-python-client/):
+
+```bash
+pip install cadence-python-client
+```
+
+Or with `uv`:
+
+```bash
+uv add cadence-python-client
+```
+
+The core package supports Python `>=3.11,<3.14`.
+
+Clone the repository if you want to develop locally:
+
 ```bash
 git clone https://github.com/cadence-workflow/cadence-python-client.git
 cd cadence-python-client
@@ -103,8 +119,7 @@ cd cadence-python-client
 
 3. **Create virtual environment and install dependencies:**
    ```bash
-   uv venv
-   uv pip install -e ".[dev]"
+   uv sync --all-extras
    ```
 
    Or if you prefer traditional pip:
@@ -116,70 +131,56 @@ cd cadence-python-client
 
 ### Generate Protobuf and gRPC Files
 
-Run the generation script:
+Run the generation script only if you change files under `idls/proto/`:
+
 ```bash
-# Using uv (recommended)
-uv sync --extra dev
-uv run python scripts/generate_proto.py
+# Recommended
+make generate
 
-# Or using traditional Python
-python scripts/generate_proto.py
+# Or run the script directly
+uv run python scripts/generate_proto.py
 ```
 
 This will:
-- Download protoc 29.1 binary
-- Install grpcio-tools if needed
 - Generate Python protobuf files in `cadence/api/v1/`
 - Generate gRPC service files in `cadence/api/v1/`
-- Create proper package structure with both protobuf and gRPC imports
+- Refresh the package imports for the generated modules
 
 ### Test
 
-Verify the generated files work:
-```bash
-# Using uv (recommended)
-uv run python cadence/sample/simple_usage_example.py
-uv run python cadence/sample/grpc_usage_example.py
+Run the main checks:
 
-# Or using traditional Python
-python cadence/sample/simple_usage_example.py
-python test_grpc_with_examples.py
+```bash
+make lint
+make type-check
+make test
 ```
 
-### Development Script
-
-The project includes a development script that provides convenient commands for common tasks:
+Run integration tests with Docker:
 
 ```bash
-# Generate protobuf files
-uv run python scripts/dev.py protobuf
-
-# Run tests
-uv run python scripts/dev.py test
-
-# Run tests with coverage
-uv run python scripts/dev.py test-cov
-
-# Run linting
-uv run python scripts/dev.py lint
-
-# Format code
-uv run python scripts/dev.py format
+make integration-test
+```
 
-# Install in development mode
-uv run python scripts/dev.py install
+You can also verify the generated files manually:
 
-# Install with dev dependencies
-uv run python scripts/dev.py install-dev
+```bash
+uv run python cadence/sample/simple_usage_example.py
+uv run python cadence/sample/grpc_usage_example.py
+```
 
-# Build package
-uv run python scripts/dev.py build
+### Development Commands
 
-# Clean build artifacts
-uv run python scripts/dev.py clean
+The current repository workflow is centered on `make` targets:
 
-# Run all checks (lint + test)
-uv run python scripts/dev.py check
+```bash
+make install
+make generate
+make lint
+make type-check
+make test
+make integration-test
+make pr
 ```
 
 ## License

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/README.md

@@ -10,11 +10,26 @@ If you'd like to propose a new feature, first join the [CNCF Slack workspace](ht
 **This SDK is currently an early work-in-progress (WIP) and is NOT ready for production use.**
 
 - This project is still in active development
-- It has not been published to any package repository (PyPI, etc.)
 - APIs and interfaces are subject to change without notice
 
 ## Installation
 
+Install from [PyPI](https://pypi.org/project/cadence-python-client/):
+
+```bash
+pip install cadence-python-client
+```
+
+Or with `uv`:
+
+```bash
+uv add cadence-python-client
+```
+
+The core package supports Python `>=3.11,<3.14`.
+
+Clone the repository if you want to develop locally:
+
 ```bash
 git clone https://github.com/cadence-workflow/cadence-python-client.git
 cd cadence-python-client
@@ -45,8 +60,7 @@ cd cadence-python-client
 
 3. **Create virtual environment and install dependencies:**
    ```bash
-   uv venv
-   uv pip install -e ".[dev]"
+   uv sync --all-extras
    ```
 
    Or if you prefer traditional pip:
@@ -58,70 +72,56 @@ cd cadence-python-client
 
 ### Generate Protobuf and gRPC Files
 
-Run the generation script:
+Run the generation script only if you change files under `idls/proto/`:
+
 ```bash
-# Using uv (recommended)
-uv sync --extra dev
-uv run python scripts/generate_proto.py
+# Recommended
+make generate
 
-# Or using traditional Python
-python scripts/generate_proto.py
+# Or run the script directly
+uv run python scripts/generate_proto.py
 ```
 
 This will:
-- Download protoc 29.1 binary
-- Install grpcio-tools if needed
 - Generate Python protobuf files in `cadence/api/v1/`
 - Generate gRPC service files in `cadence/api/v1/`
-- Create proper package structure with both protobuf and gRPC imports
+- Refresh the package imports for the generated modules
 
 ### Test
 
-Verify the generated files work:
-```bash
-# Using uv (recommended)
-uv run python cadence/sample/simple_usage_example.py
-uv run python cadence/sample/grpc_usage_example.py
+Run the main checks:
 
-# Or using traditional Python
-python cadence/sample/simple_usage_example.py
-python test_grpc_with_examples.py
+```bash
+make lint
+make type-check
+make test
 ```
 
-### Development Script
-
-The project includes a development script that provides convenient commands for common tasks:
+Run integration tests with Docker:
 
 ```bash
-# Generate protobuf files
-uv run python scripts/dev.py protobuf
-
-# Run tests
-uv run python scripts/dev.py test
-
-# Run tests with coverage
-uv run python scripts/dev.py test-cov
-
-# Run linting
-uv run python scripts/dev.py lint
-
-# Format code
-uv run python scripts/dev.py format
+make integration-test
+```
 
-# Install in development mode
-uv run python scripts/dev.py install
+You can also verify the generated files manually:
 
-# Install with dev dependencies
-uv run python scripts/dev.py install-dev
+```bash
+uv run python cadence/sample/simple_usage_example.py
+uv run python cadence/sample/grpc_usage_example.py
+```
 
-# Build package
-uv run python scripts/dev.py build
+### Development Commands
 
-# Clean build artifacts
-uv run python scripts/dev.py clean
+The current repository workflow is centered on `make` targets:
 
-# Run all checks (lint + test)
-uv run python scripts/dev.py check
+```bash
+make install
+make generate
+make lint
+make type-check
+make test
+make integration-test
+make pr
 ```
 
 ## License

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/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_python_client-0.2.2 → cadence_python_client-0.2.3}/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_python_client-0.2.2 → cadence_python_client-0.2.3}/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_python_client-0.2.2 → cadence_python_client-0.2.3}/cadence/_internal/workflow/workflow_engine.py

@@ -25,6 +25,11 @@ from cadence.api.v1.history_pb2 import (
     WorkflowExecutionSignaledEventAttributes,
     WorkflowExecutionStartedEventAttributes,
 )
+from cadence.api.v1.query_pb2 import (
+    WorkflowQuery,
+    WorkflowQueryResult,
+    QUERY_RESULT_TYPE_ANSWERED,
+)
 from cadence.api.v1.tasklist_pb2 import TaskList
 from cadence.error import ContinueAsNewError
 from cadence.workflow import WorkflowDefinition, WorkflowInfo
@@ -35,6 +40,7 @@ logger = logging.getLogger(__name__)
 @dataclass
 class DecisionResult:
     decisions: list[Decision]
+    query_result: Optional[WorkflowQueryResult] = None
 
 
 class WorkflowEngine:
@@ -51,6 +57,7 @@ class WorkflowEngine:
     def process_decision(
         self,
         events: List[HistoryEvent],
+        query: Optional[WorkflowQuery] = None,
     ) -> DecisionResult:
         """
         Process a decision task and generate decisions using DecisionEventsIterator.
@@ -59,7 +66,7 @@ class WorkflowEngine:
         to drive the decision processing pipeline with proper replay handling.
 
         Args:
-            decision_task: The PollForDecisionTaskResponse from the service
+            events: The workflow history events.
 
         Returns:
             DecisionResult containing the list of decisions
@@ -74,6 +81,7 @@ class WorkflowEngine:
                         "workflow_type": ctx.info().workflow_type,
                         "workflow_id": ctx.info().workflow_id,
                         "run_id": ctx.info().workflow_run_id,
+                        "query": query.query_type if query else None,
                     },
                 )
 
@@ -83,11 +91,15 @@ class WorkflowEngine:
                 # Process decision events using iterator-driven approach
                 self._process_decision_events(ctx, events_iterator)
 
+                if query:
+                    return self._execute_query(query)
+
                 # Collect all pending decisions from state machines
                 decisions = self._decision_manager.collect_pending_decisions()
 
-                return DecisionResult(decisions=decisions)
+                return DecisionResult(decisions=decisions, query_result=None)
 
+        # TODO: reevaluate if this is needed to log error here or in the caller
         except Exception as e:
             # Log decision task failure with full context (matches Java ReplayDecisionTaskHandler)
             logger.error(
@@ -103,6 +115,18 @@ class WorkflowEngine:
             # Re-raise the exception so the handler can properly handle the failure
             raise
 
+    def _execute_query(self, query: WorkflowQuery) -> DecisionResult:
+        result_payload = self._workflow_instance.handle_query(
+            query.query_type, query.query_args
+        )
+        return DecisionResult(
+            decisions=[],
+            query_result=WorkflowQueryResult(
+                result_type=QUERY_RESULT_TYPE_ANSWERED,
+                answer=result_payload,
+            ),
+        )
+
     def is_done(self) -> bool:
         return self._workflow_instance.is_done()
 

{cadence_python_client-0.2.2 → cadence_python_client-0.2.3}/cadence/_internal/workflow/workflow_instance.py

@@ -96,6 +96,39 @@ class WorkflowInstance:
         if inspect.iscoroutine(result):
             await result
 
+    def handle_query(self, query_type: str, query_args: Payload) -> Payload:
+        """Execute a query handler and return the serialized result.
+
+        The query runs synchronously against the current workflow state
+        (after replay has caught up). It must not mutate state.
+
+        Args:
+            query_type: The registered query type name.
+            query_args: Serialized query arguments.
+
+        Returns:
+            Serialized query result as a Payload.
+
+        Raises:
+            ValueError: If the query type is not registered.
+            Exception: If the query handler raises.
+        """
+        query_def = self._definition.queries.get(query_type)
+        if query_def is None:
+            raise ValueError(
+                f"Unknown query type '{query_type}'. "
+                f"Known types: {list(self._definition.queries.keys())}"
+            )
+
+        args = query_def.params_from_payload(self._data_converter, query_args)
+        result = query_def(self._instance, *args)
+        if inspect.iscoroutine(result):
+            result.close()
+            raise TypeError(
+                f"Query handler '{query_type}' must be synchronous, got async function"
+            )
+        return self._data_converter.to_data([result])
+
     def _on_signal_task_done(self, task: Task[Any], signal_name: str) -> None:
         self._signal_tasks.discard(task)
         if task.cancelled():