Master Temporal Python Workflows

This skill covers production-grade Temporal workflow development with the Python SDK: worker configuration and registration, workflow definition (@workflow.defn, @workflow.run), activity definition (@activity.defn), and the three execution models for activities - async (asyncio, for non-blocking I/O), sync multithreaded (ThreadPoolExecutor, for blocking I/O like sync DB clients), and sync multiprocess (ProcessPoolExecutor, for CPU-intensive work like ML inference) - flagging the critical anti-pattern of blocking the async event loop, which serializes what should be concurrent execution.

It covers error handling and retries in depth: ApplicationError with non_retryable=True, RetryPolicy configuration (backoff coefficient, max interval, max attempts), the four timeout types (schedule_to_close_timeout, start_to_close_timeout, heartbeat_timeout, schedule_to_start_timeout), and catching ActivityError for compensation logic. Signal (@workflow.signal) and query (@workflow.query) handlers are covered for external events and read-only state inspection, alongside the hard determinism requirements workflows must follow - workflow.now() instead of datetime.now(), workflow.random() instead of random.random(), no threading/locks/global state, no direct external calls - plus workflow versioning via workflow.get_version() for safe code evolution. Testing spans WorkflowEnvironment (time-skipping, so month-long workflows test instantly), ActivityEnvironment for activity unit tests, Docker-based integration testing, and replay testing against production event histories to validate determinism after code changes. Production sections cover containerized worker deployment, worker versioning/blue-green rollout, observability (execution metrics, queue depth, distributed tracing), and performance tuning (concurrency, connection pooling, activity batching).

Use Temporal Python for distributed transactions across microservices, long-running business processes (hours to years), the Saga pattern with compensation, entity workflow management (carts, accounts, inventory), human-in-the-loop approval workflows, and multi-step data pipelines - anywhere automatic state persistence, retries, and time-travel replay debugging matter more than raw throughput.

It is not suited to workflows that can't tolerate the strict determinism constraints (no direct I/O, no wall-clock time, no randomness in workflow code - those all belong in activities), and it explicitly calls out common pitfalls: determinism violations, non-idempotent activities (unsafe under Temporal's automatic retries), skipping the payload size limit (2MB per argument), and deploying workers with unregistered workflows/activities or mismatched task queues.

Input is a business process to model as a durable workflow (order fulfillment, payment with compensation, multi-party approval) plus its external side effects (API calls, DB writes) to isolate into activities. Output is workflow/activity Python code with correct decorators, a RetryPolicy and timeout configuration, signal/query handlers for interaction, and a test suite using time-skipping and replay validation.

Targets the official Temporal Python SDK (python.temporal.io), with Docker/Kubernetes for worker deployment, and references Temporal's own documentation (docs.temporal.io) and architecture docs for deeper detail. Supports JSON (default), Protobuf, and custom data converters for serialization, plus Pydantic models for typed inputs/outputs.

Backend and platform engineers building durable, long-running distributed workflows in Python who need production discipline around determinism, retries, testing, and deployment - not a quick single-function orchestration script.