This repository contains Python SDKs for building durable orchestrations with Azure Durable Task Scheduler and Azure Durable Functions:
durabletaskis the core orchestration SDK.durabletask.azuremanagedis the Azure Durable Task Scheduler provider.azure-functions-durableis a preview Azure Durable Functions provider built ondurabletask.
The core SDK and Azure Managed provider require Python 3.11 or later. The Azure Functions Durable provider requires Python 3.13 or later.
- Supported Patterns
- Available Features
- Getting Started
- Development Guide
- Azure Functions Durable 2.x
- Contributing Guide
All three packages support async def orchestrators and nested async helpers.
Existing generator orchestrators continue to work.
import asyncio
from durabletask import task
async def sequence(ctx: task.AsyncOrchestrationContext, value: int) -> list[int]:
first = await ctx.call_activity("plus_one", input=value, return_type=int)
async with asyncio.TaskGroup() as group:
left = group.create_task(ctx.call_activity("plus_one", input=first, return_type=int))
right = group.create_task(ctx.call_activity("plus_one", input=value, return_type=int))
return [left.result(), right.result()]Register the function with TaskHubGrpcWorker, DurableTaskSchedulerWorker,
or the Azure Functions orchestration_trigger decorator as usual. All three
packages use this two-argument shape for async orchestrators. Async
orchestrators automatically receive cold coroutine operations accepted by
create_task and task groups.
Generator orchestrators keep their eager, reusable durable handles. For
interoperability, ctx.as_task_context() exposes the eager context and
handle.wait() creates an independently cancellable borrower.
Warning
This is replay-driven await syntax, not general-purpose asyncio execution.
Compose durable work with asyncio.gather, local tasks/task groups, and
durable asyncio.sleep / timeouts within the
supported contract.
Perform network, storage, and other nondeterministic I/O in activities.
Completed foreign awaitables and synchronous side effects cannot reliably be
detected by the replay engine.
Python finally blocks and async context-manager exits can run at ordinary
dispatch suspension; they are not workflow-lifetime compensation scopes.
An async helper is not a durable sub-orchestration: use
await ctx.call_sub_orchestrator(...) for a separate orchestration instance.
An async def function containing yield is an async generator, not a supported
orchestrator. Converting an existing orchestrator must preserve durable action
order and payloads for replay compatibility.
See the contract for cancellation, per-dispatch async cleanup, unsupported
ordering-sensitive APIs and framework adapters.
Set OrchestrationQuery.task_hub_names to filter orchestration queries by one or
more task hubs. The filter is available through synchronous and asynchronous
core and Azure Managed clients; filtering support depends on the backend.
from durabletask.client import OrchestrationQuery
query = OrchestrationQuery(task_hub_names=["orders", "billing"])The default JsonDataConverter serializes sets and frozensets as JSON arrays
ordered by their canonical JSON representation, not numeric order. For example,
{2, 10} serializes as [10, 2]. To reconstruct annotated sets and frozensets
instead of receiving lists, configure the same converter on clients and workers:
from durabletask.serialization import JsonDataConverter
converter = JsonDataConverter(enable_generic_sets=True)Pass it using the data_converter parameter on core or Azure Managed clients
and workers. enable_set_coercion=True is an alias for the same option.
Azure Functions uses its own shared codec rather than this converter.
Warning
Set reconstruction is disabled by default to preserve the order and duplicates of recorded JSON arrays. Enabling it for existing orchestrations can change replay behavior. Iteration over reconstructed sets is not replay-safe; sort values explicitly before using their order to schedule durable work.
EntityInstanceId values are immutable, hashable, and usable as dictionary keys
or set elements. Construct a new ID to change an entity name or key; attribute
assignment and deletion raise AttributeError.
Install the azure-blob-payloads extra to automatically offload oversized orchestration payloads to
Azure Blob Storage:
pip install durabletask[azure-blob-payloads]See the feature documentation and the example for usage details.
Configure an ExceptionPropertiesProvider to attach portable diagnostic
properties to activity, entity, and orchestration failures:
from durabletask import ExceptionPropertiesProvider
from durabletask.worker import TaskHubGrpcWorker
class FailureProperties(ExceptionPropertiesProvider):
def get_exception_properties(self, exception: Exception):
return {"error_code": getattr(exception, "error_code", None)}
worker = TaskHubGrpcWorker(exception_properties_provider=FailureProperties())Properties support None, booleans, numbers, strings, nested mappings, and
lists. They are available from TaskFailedError.details, orchestration state,
and history as FailureDetails.properties.
Note
Python intentionally treats .NET's dt: and dto: property strings as
ordinary strings, matching the Java SDK. Consequently, datetime values do
not retain their type across Python/.NET failure-details property round trips;
this is a .NET SDK parity gap.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.