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

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

@@ -32,7 +32,7 @@ pip install -e ".[dev]"
 
 ## Code Generation
 - Use `uv run python scripts/generate_proto.py` for protobuf generation
-- Use `uv run python scripts/dev.py` for development tasks
+- Use `make` targets for development tasks
 
 ## Code Quality
 - **ALWAYS run linter and type checker after making code changes**

{cadence_python_client-0.2.2 → cadence_python_client-0.3.0}/.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
@@ -92,6 +97,6 @@ jobs:
       - name: Install dependencies
         run: |
           uv sync --extra dev
-      - name: Run unit tests
+      - name: Run integration tests
         run: |
-          uv run pytest -v --integration-tests
+          uv run pytest -v tests/integration_tests --integration-tests

{cadence_python_client-0.2.2 → cadence_python_client-0.3.0}/Makefile

@@ -33,7 +33,11 @@ test:
 # Run integration tests
 integration-test:
 	@echo "Running integration tests..."
-	uv run pytest -v --integration-tests
+	uv run pytest -v tests/integration_tests --integration-tests
+
+integration-test-keep:
+	@echo "Running integration tests with cadence alive..."
+	uv run pytest -v tests/integration_tests --integration-tests --keep-cadence-alive
 
 # Clean generated files and caches
 clean:
@@ -41,15 +45,17 @@ clean:
 	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.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cadence-python-client
-Version: 0.2.2
-Summary: Python framework for authoring Cadence workflows and activities
+Version: 0.3.0
+Summary: Python SDK for authoring Cadence workflows and activities
 Author: Cadence
 License: Apache-2.0
 Project-URL: Homepage, https://cadenceworkflow.io/
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://cadenceworkflow.io/docs/get-started
 Project-URL: Repository, https://github.com/cadence-workflow/cadence-python-client
 Project-URL: Bug Tracker, https://github.com/cadence-workflow/cadence-python-client/issues
 Keywords: workflow,orchestration,distributed,async,cadence
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
@@ -31,14 +31,11 @@ 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"
-Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: isort>=5.12.0; extra == "dev"
-Requires-Dist: flake8>=6.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
-Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 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"
@@ -56,22 +53,33 @@ Requires-Dist: openai>=0.27.10; extra == "openai"
 Requires-Dist: openai-agents>=0.12.5; extra == "openai"
 Dynamic: license-file
 
-# Python framework for Cadence
+# Cadence Python SDK
 
 [Cadence](https://github.com/uber/cadence) is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way.
 
 If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion.
 
-`cadence-python-client` is the Python framework for authoring workflows and activities.
+The Cadence Python SDK is the framework for authoring workflows and activities using the Python programming language.
 
-## Disclaimer
-**This SDK is currently an early work-in-progress (WIP) and is NOT ready for production use.**
+## Installation
 
-- 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
+Install from [PyPI](https://pypi.org/project/cadence-python-client/):
 
-## Installation
+```bash
+pip install cadence-python-client
+```
+
+Or with `uv`:
+
+```bash
+uv add cadence-python-client
+```
+
+The core package supports Python `>=3.11,<3.14`.
+
+The SDK is ready for production use using PYPI. To build from source, clone the repository and install the development dependencies.
+
+Clone the repository if you want to develop locally:
 
 ```bash
 git clone https://github.com/cadence-workflow/cadence-python-client.git
@@ -103,8 +111,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 +123,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.3.0}/README.md

@@ -1,19 +1,30 @@
-# Python framework for Cadence
+# Cadence Python SDK
 
 [Cadence](https://github.com/uber/cadence) is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way.
 
 If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion.
 
-`cadence-python-client` is the Python framework for authoring workflows and activities.
+The Cadence Python SDK is the framework for authoring workflows and activities using the Python programming language.
 
-## Disclaimer
-**This SDK is currently an early work-in-progress (WIP) and is NOT ready for production use.**
+## Installation
 
-- 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
+Install from [PyPI](https://pypi.org/project/cadence-python-client/):
 
-## Installation
+```bash
+pip install cadence-python-client
+```
+
+Or with `uv`:
+
+```bash
+uv add cadence-python-client
+```
+
+The core package supports Python `>=3.11,<3.14`.
+
+The SDK is ready for production use using PYPI. To build from source, clone the repository and install the development dependencies.
+
+Clone the repository if you want to develop locally:
 
 ```bash
 git clone https://github.com/cadence-workflow/cadence-python-client.git
@@ -45,8 +56,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 +68,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.3.0}/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.3.0}/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.3.0}/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,
         )