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

cadence_python_client-0.2.2/.cursorrules

@@ -0,0 +1,49 @@
+# Cursor Rules for Cadence Python Client
+
+## Package Management
+- **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, 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
+```bash
+# ✅ Correct
+uv run python scripts/generate_proto.py
+uv run python -m pytest tests/
+uv run mypy cadence/
+uv tool run ruff check
+
+# ❌ Avoid
+python scripts/generate_proto.py
+pip install -e ".[dev]"
+```
+
+## Virtual Environment
+- The project uses `uv` for virtual environment management
+- Always activate the virtual environment using `uv` commands
+- Dependencies are managed through `pyproject.toml` and `uv.lock`
+
+## Testing
+- Run tests with `uv run python -m pytest`
+- Use `uv run` for any Python script execution
+- Development tools should be run with `uv tool run`
+
+## Code Generation
+- Use `uv run python scripts/generate_proto.py` for protobuf generation
+- Use `uv run python scripts/dev.py` for development tasks
+
+## 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 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 run mypy cadence/` (checks type safety)
+4. Run `uv run python -m pytest` (run tests)
+5. Commit changes

cadence_python_client-0.2.2/.github/dco.yml

@@ -0,0 +1,2 @@
+require:
+  members: false

cadence_python_client-0.2.2/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+<!-- Describe what has changed in this PR -->
+**What changed?**
+
+
+<!-- Tell your future self why have you made these changes -->
+**Why?**
+
+
+<!-- How have you verified this change? Tested locally? Added a unit test? Checked in staging env? -->
+**How did you test it?**
+
+
+<!-- Assuming the worst case, what can be broken when deploying this change to production? -->
+**Potential risks**
+
+<!-- Is it notable for release? e.g. schema updates, configuration or data migration required? If so, please mention it, and also update CHANGELOG.md -->
+**Release notes**
+
+<!-- Is there any documentation updates should be made for config, https://cadenceworkflow.io/docs/operation-guide/setup/ ? If so, please open an PR in https://github.com/cadence-workflow/cadence-docs -->
+**Documentation Changes**

cadence_python_client-0.2.2/.github/workflows/ci_checks.yml

@@ -0,0 +1,97 @@
+name: CI Checks
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+      - name: Ensure Proto Files changes are committed
+        run: |
+          uv run python scripts/generate_proto.py
+          if [ -n "$(git status --porcelain  2>&1)" ]; then
+            echo "There are file changes after generating proto files."
+            echo "Please run this command and commit the changes:"
+            echo "\tuv run python scripts/generate_proto.py"
+            git status --porcelain
+            git --no-pager diff
+            exit 1
+          fi
+      - name: Run Ruff linter
+        run: |
+          uv tool run ruff check
+          uv tool run ruff format --check
+
+  type-check:
+    name: Type Safety Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev --extra openai
+      - name: Run mypy type checker
+        run: |
+          uv run mypy cadence/
+
+  test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+      - name: Run unit tests
+        run: |
+          uv run pytest -v
+
+  integration_test:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+      - name: Run unit tests
+        run: |
+          uv run pytest -v --integration-tests

cadence_python_client-0.2.2/.github/workflows/python-publish.yml

@@ -0,0 +1,62 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: 
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cadence-python-client
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cadence_python_client-0.2.2/.github/workflows/semantic-pr.yml

@@ -0,0 +1,72 @@
+name: Semantic Pull Request
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  semantic-pr:
+    name: Validate PR title follows conventional commit format
+    runs-on: ubuntu-latest
+    # TODO: Remove this once we commit to conventional commits
+    continue-on-error: true
+
+    steps:
+      - name: Validate PR title
+        id: lint_pr_title
+        uses: amannn/action-semantic-pull-request@v5.4.0
+        with:
+          # Allow standard conventional commit types
+          types: |
+            fix
+            feat
+            docs
+            style
+            refactor
+            perf
+            test
+            chore
+            ci
+            build
+          # TODO: Remove this once we've decided on scopes
+          requireScope: false
+          # Skip validation for certain labels if needed
+          ignoreLabels: |
+            skip-commit-format
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Comment on PR if validation fails
+        if: steps.lint_pr_title.outputs.error_message != null
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `⚠️ **Semantic PR Check Failed**
+
+              **Error Details:**
+              \`\`\`
+              ${{ steps.lint_pr_title.outputs.error_message }}
+              \`\`\`
+
+              **Required Format:**
+              \`\`\`
+              <type>: <description>
+              \`\`\`
+
+              **Allowed types:** fix, feat, docs, style, refactor, perf, test, chore, ci, build
+
+              **Examples:**
+              - \`feat: add user authentication system\`
+              - \`fix: resolve memory leak in worker pool\`
+              - \`docs: update API documentation\`
+              - \`test: add integration tests for auth flow\`
+
+              This is currently a **warning only** and won't block your PR from being merged.`
+            })

cadence_python_client-0.2.2/.gitignore

@@ -0,0 +1,114 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Logs
+*.log
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+*.iml
+*.ipr
+*.iws
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Project specific
+.temp_gen/
+*.pb.py
+*.pb.pyi
+
+# bin
+.bin/
+
+# Claude Code files
+CLAUDE.md
+settings.local.json
+.python-version
+*.bak
+.mcp.json

cadence_python_client-0.2.2/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "idls"]
+	path = idls
+	url = https://github.com/cadence-workflow/cadence-idl.git

cadence_python_client-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to Cadence Python Client
+
+This doc is intended for contributors to the Cadence Python Client. Thanks for considering to contribute ❤️
+
+> 📚 **New to contributing to Cadence?** Check out our [Contributing Guide](https://cadenceworkflow.io/community/how-to-contribute/getting-started) for an overview of the contribution process across all Cadence repositories. This document contains Python client specific setup and development instructions.
+
+Once you go through the rest of this doc and get familiar with local development setup, take a look at the list of issues labeled with
+[good first issue](https://github.com/cadence-workflow/cadence-python-client/labels/good%20first%20issue).
+These issues are a great way to start contributing to Cadence Python Client.
+
+Join our community on the CNCF Slack workspace at [cloud-native.slack.com](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to reach out and discuss issues with the team.
+
+## Submitting Pull Requests
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Make your changes following the code quality guidelines above
+4. Write or update tests as needed
+5. Ensure all tests pass and there are no linting/type errors
+6. Submit a pull request with a clear description of your changes
+
+## Getting Help
+
+- **GitHub Issues**: [Report bugs or request features](https://github.com/cadence-workflow/cadence-python-client/issues/new)
+- **CNCF Slack**: Join the **#cadence-users** channel at [cloud-native.slack.com](https://communityinviter.com/apps/cloud-native/cncf)
+- **Stack Overflow**: Tag questions with `cadence-workflow`
+
+## License
+
+By contributing to Cadence Python Client, you agree that your contributions will be licensed under the Apache 2.0 License.
+

cadence_python_client-0.2.2/Makefile

@@ -0,0 +1,55 @@
+.PHONY: pr install lint type-check test integration-test clean generate help
+
+# Run all PR checks locally
+pr: install generate lint type-check test integration-test
+	@echo "All PR checks passed!"
+
+# Install dependencies
+install:
+	@echo "Installing dependencies..."
+	uv sync --all-extras
+
+# Generate idl files
+generate:
+	@echo "Generating type files based on IDL..."
+	uv run python scripts/generate_proto.py
+
+# Run linter
+lint:
+	@echo "Running Ruff linter and fixing lint issues..."
+	uv tool run ruff check --fix
+	uv tool run ruff format
+
+# Run type checker
+type-check:
+	@echo "Running mypy type checker..."
+	uv run mypy cadence/ tests/
+
+# Run unit tests
+test:
+	@echo "Running unit tests..."
+	uv run pytest -v
+
+# Run integration tests
+integration-test:
+	@echo "Running integration tests..."
+	uv run pytest -v --integration-tests
+
+# 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
+
+# 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"

{cadence_python_client-0.2.0/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.0
+Version: 0.2.2
 Summary: Python framework for authoring Cadence workflows and activities
 Author: Cadence
 License: Apache-2.0
@@ -40,6 +40,10 @@ 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"
+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"
@@ -47,6 +51,9 @@ Requires-Dist: myst-parser>=1.0.0; extra == "docs"
 Provides-Extra: examples
 Requires-Dist: requests>=2.28.0; extra == "examples"
 Requires-Dist: aiohttp>=3.8.0; extra == "examples"
+Provides-Extra: openai
+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_client-0.2.0 → cadence_python_client-0.2.2}/cadence/_internal/activity/_activity_executor.py

@@ -1,12 +1,13 @@
 from concurrent.futures import ThreadPoolExecutor
 from logging import getLogger
 from traceback import format_exception
-from typing import Any, Callable, cast
+from typing import Any, Callable, Union, cast
 from google.protobuf.duration import to_timedelta
 from google.protobuf.timestamp import to_datetime
 
 from cadence._internal.activity._context import _Context, _SyncContext
 from cadence._internal.activity._definition import BaseDefinition, ExecutionStrategy
+from cadence._internal.activity._heartbeat import _HeartbeatSender
 from cadence.activity import ActivityInfo, ActivityDefinition
 from cadence.api.v1.common_pb2 import Failure
 from cadence.api.v1.service_worker_pb2 import (
@@ -46,7 +47,9 @@ class ActivityExecutor:
             _logger.exception("Activity failed")
             await self._report_failure(task, e)
 
-    def _create_context(self, task: PollForActivityTaskResponse) -> _Context:
+    def _create_context(
+        self, task: PollForActivityTaskResponse
+    ) -> Union[_Context, _SyncContext]:
         activity_type = task.activity_type.name
         try:
             activity_def = cast(BaseDefinition, self._registry(activity_type))
@@ -54,11 +57,24 @@ class ActivityExecutor:
             raise KeyError(f"Activity type not found: {activity_type}") from None
 
         info = self._create_info(task)
+        heartbeat_sender = _HeartbeatSender(
+            self._client.worker_stub,
+            self._data_converter,
+            task.task_token,
+            self._identity,
+            task.heartbeat_details,
+        )
 
         if activity_def.strategy == ExecutionStrategy.ASYNC:
-            return _Context(self._client, info, activity_def)
+            return _Context(self._client, info, activity_def, heartbeat_sender)
         else:
-            return _SyncContext(self._client, info, activity_def, self._thread_pool)
+            return _SyncContext(
+                self._client,
+                info,
+                activity_def,
+                self._thread_pool,
+                heartbeat_sender,
+            )
 
     async def _report_failure(
         self, task: PollForActivityTaskResponse, error: Exception

cadence_python_client-0.2.2/cadence/_internal/activity/_context.py

@@ -0,0 +1,95 @@
+import asyncio
+from concurrent.futures.thread import ThreadPoolExecutor
+from typing import Any, Type
+
+from cadence import Client
+from cadence._internal.activity._definition import BaseDefinition
+from cadence._internal.activity._heartbeat import _HeartbeatSender
+from cadence.activity import ActivityInfo, ActivityContext
+from cadence.api.v1.common_pb2 import Payload
+
+
+class _Context(ActivityContext):
+    def __init__(
+        self,
+        client: Client,
+        info: ActivityInfo,
+        activity_def: BaseDefinition[[Any], Any],
+        heartbeat_sender: _HeartbeatSender,
+    ):
+        self._client = client
+        self._info = info
+        self._activity_def = activity_def
+        self._heartbeat_sender = heartbeat_sender
+        self._heartbeat_tasks: set[asyncio.Future[None]] = set()
+
+    async def execute(self, payload: Payload) -> Any:
+        params = self._to_params(payload)
+        try:
+            with self._activate():
+                return await self._activity_def.impl_fn(*params)
+        finally:
+            await self._wait_pending_heartbeats()
+
+    async def _wait_pending_heartbeats(self) -> None:
+        if not self._heartbeat_tasks:
+            return
+        tasks = list(self._heartbeat_tasks)
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    def _to_params(self, payload: Payload) -> list[Any]:
+        return self._activity_def.signature.params_from_payload(
+            self._client.data_converter, payload
+        )
+
+    def client(self) -> Client:
+        return self._client
+
+    def info(self) -> ActivityInfo:
+        return self._info
+
+    def heartbeat(self, *details: Any) -> None:
+        heartbeat_task = asyncio.create_task(
+            self._heartbeat_sender.send_heartbeat(*details)
+        )
+        self._heartbeat_tasks.add(heartbeat_task)
+        heartbeat_task.add_done_callback(self._heartbeat_tasks.discard)
+
+    def heartbeat_details(self, *types: Type) -> list[Any]:
+        return self._heartbeat_sender.get_details(*types)
+
+
+class _SyncContext(_Context):
+    def __init__(
+        self,
+        client: Client,
+        info: ActivityInfo,
+        activity_def: BaseDefinition[[Any], Any],
+        executor: ThreadPoolExecutor,
+        heartbeat_sender: _HeartbeatSender,
+    ):
+        super().__init__(client, info, activity_def, heartbeat_sender)
+        self._executor = executor
+
+    async def execute(self, payload: Payload) -> Any:
+        params = self._to_params(payload)
+        self._loop = asyncio.get_running_loop()
+        try:
+            return await self._loop.run_in_executor(self._executor, self._run, params)
+        finally:
+            await self._wait_pending_heartbeats()
+
+    def _run(self, args: list[Any]) -> Any:
+        with self._activate():
+            return self._activity_def.impl_fn(*args)
+
+    def client(self) -> Client:
+        raise RuntimeError("client is only supported in async activities")
+
+    def heartbeat(self, *details: Any) -> None:
+        future = asyncio.run_coroutine_threadsafe(
+            self._heartbeat_sender.send_heartbeat(*details), self._loop
+        )
+        wrapped = asyncio.wrap_future(future, loop=self._loop)
+        self._heartbeat_tasks.add(wrapped)
+        wrapped.add_done_callback(self._heartbeat_tasks.discard)