Skip to content

About

A Durable Task Python SDK compatible with the Durable Task Scheduler

Resources

Code of conduct

Contributing

Security policy

Stars

40 stars

Watchers

4 watching

Forks

 
 

Repository files navigation

Durable Task SDK for Python

License: MIT Build Validation PyPI version

This repository contains Python SDKs for building durable orchestrations with Azure Durable Task Scheduler and Azure Durable Functions:

Python Requirements

The core SDK and Azure Managed provider require Python 3.11 or later. The Azure Functions Durable provider requires Python 3.13 or later.

References

Optional Features

Async Orchestrators

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.

Task Hub Query Filters

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"])

Set Serialization

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.

Entity IDs

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.

Large Payload Externalization

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.

Failure Details Properties

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.

Trademarks

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.

About

A Durable Task Python SDK compatible with the Durable Task Scheduler

Resources

Code of conduct

Contributing

Security policy

Stars

40 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages