durabletask 1.3.0.dev25__tar.gz → 1.3.0.dev27__tar.gz

{durabletask-1.3.0.dev25 → durabletask-1.3.0.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durabletask
-Version: 1.3.0.dev25
+Version: 1.3.0.dev27
 Summary: A Durable Task Client SDK for Python
 License:     MIT License
         
@@ -40,6 +40,8 @@ Requires-Dist: packaging
 Provides-Extra: opentelemetry
 Requires-Dist: opentelemetry-api>=1.0.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-sdk>=1.0.0; extra == "opentelemetry"
+Provides-Extra: azure-blob-payloads
+Requires-Dist: azure-storage-blob[aio]>=12.0.0; extra == "azure-blob-payloads"
 Dynamic: license-file
 
 # Durable Task SDK for Python
@@ -59,6 +61,20 @@ This repo contains a Python SDK for use with the [Azure Durable Task Scheduler](
 - [Development Guide](./docs/development.md) 
 - [Contributing Guide](./CONTRIBUTING.md)
 
+## Optional Features
+
+### Large Payload Externalization
+
+Install the `azure-blob-payloads` extra to automatically offload
+oversized orchestration payloads to Azure Blob Storage:
+
+```bash
+pip install durabletask[azure-blob-payloads]
+```
+
+See the [feature documentation](./docs/features.md#large-payload-externalization)
+and the [example](./examples/large_payload/) for usage details.
+
 ## 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 

{durabletask-1.3.0.dev25 → durabletask-1.3.0.dev27}/README.md

@@ -15,6 +15,20 @@ This repo contains a Python SDK for use with the [Azure Durable Task Scheduler](
 - [Development Guide](./docs/development.md) 
 - [Contributing Guide](./CONTRIBUTING.md)
 
+## Optional Features
+
+### Large Payload Externalization
+
+Install the `azure-blob-payloads` extra to automatically offload
+oversized orchestration payloads to Azure Blob Storage:
+
+```bash
+pip install durabletask[azure-blob-payloads]
+```
+
+See the [feature documentation](./docs/features.md#large-payload-externalization)
+and the [example](./examples/large_payload/) for usage details.
+
 ## 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 

{durabletask-1.3.0.dev25 → durabletask-1.3.0.dev27}/durabletask/__init__.py

@@ -3,8 +3,14 @@
 
 """Durable Task SDK for Python"""
 
+from durabletask.payload.store import LargePayloadStorageOptions, PayloadStore
 from durabletask.worker import ConcurrencyOptions, VersioningOptions
 
-__all__ = ["ConcurrencyOptions", "VersioningOptions"]
+__all__ = [
+    "ConcurrencyOptions",
+    "LargePayloadStorageOptions",
+    "PayloadStore",
+    "VersioningOptions",
+]
 
 PACKAGE_NAME = "durabletask"

{durabletask-1.3.0.dev25 → durabletask-1.3.0.dev27}/durabletask/client.py

@@ -32,6 +32,8 @@ from durabletask.internal.client_helpers import (
     prepare_async_interceptors,
     prepare_sync_interceptors,
 )
+from durabletask.payload import helpers as payload_helpers
+from durabletask.payload.store import PayloadStore
 
 TInput = TypeVar('TInput')
 TOutput = TypeVar('TOutput')
@@ -152,7 +154,8 @@ class TaskHubGrpcClient:
                  log_formatter: Optional[logging.Formatter] = None,
                  secure_channel: bool = False,
                  interceptors: Optional[Sequence[shared.ClientInterceptor]] = None,
-                 default_version: Optional[str] = None):
+                 default_version: Optional[str] = None,
+                 payload_store: Optional[PayloadStore] = None):
 
         interceptors = prepare_sync_interceptors(metadata, interceptors)
 
@@ -165,6 +168,7 @@ class TaskHubGrpcClient:
         self._stub = stubs.TaskHubSidecarServiceStub(channel)
         self._logger = shared.get_logger("client", log_handler, log_formatter)
         self.default_version = default_version
+        self._payload_store = payload_store
 
     def close(self) -> None:
         """Closes the underlying gRPC channel."""
@@ -198,12 +202,20 @@ class TaskHubGrpcClient:
                 req.parentTraceContext.CopyFrom(parent_trace_ctx)
 
             self._logger.info(f"Starting new '{req.name}' instance with ID = '{req.instanceId}'.")
+            # Externalize any large payloads in the request
+            if self._payload_store is not None:
+                payload_helpers.externalize_payloads(
+                    req, self._payload_store, instance_id=req.instanceId,
+                )
             res: pb.CreateInstanceResponse = self._stub.StartInstance(req)
             return res.instanceId
 
     def get_orchestration_state(self, instance_id: str, *, fetch_payloads: bool = True) -> Optional[OrchestrationState]:
         req = pb.GetInstanceRequest(instanceId=instance_id, getInputsAndOutputs=fetch_payloads)
         res: pb.GetInstanceResponse = self._stub.GetInstance(req)
+        # De-externalize any large-payload tokens in the response
+        if self._payload_store is not None and res.exists:
+            payload_helpers.deexternalize_payloads(res, self._payload_store)
         return new_orchestration_state(req.instanceId, res)
 
     def get_all_orchestration_states(self,
@@ -220,6 +232,8 @@ class TaskHubGrpcClient:
         while True:
             req = build_query_instances_req(orchestration_query, _continuation_token)
             resp: pb.QueryInstancesResponse = self._stub.QueryInstances(req)
+            if self._payload_store is not None:
+                payload_helpers.deexternalize_payloads(resp, self._payload_store)
             states += [parse_orchestration_state(res) for res in resp.orchestrationState]
             if check_continuation_token(resp.continuationToken, _continuation_token, self._logger):
                 _continuation_token = resp.continuationToken
@@ -235,6 +249,8 @@ class TaskHubGrpcClient:
         try:
             self._logger.info(f"Waiting up to {timeout}s for instance '{instance_id}' to start.")
             res: pb.GetInstanceResponse = self._stub.WaitForInstanceStart(req, timeout=timeout)
+            if self._payload_store is not None and res.exists:
+                payload_helpers.deexternalize_payloads(res, self._payload_store)
             return new_orchestration_state(req.instanceId, res)
         except grpc.RpcError as rpc_error:
             if rpc_error.code() == grpc.StatusCode.DEADLINE_EXCEEDED:  # type: ignore
@@ -250,6 +266,8 @@ class TaskHubGrpcClient:
         try:
             self._logger.info(f"Waiting {timeout}s for instance '{instance_id}' to complete.")
             res: pb.GetInstanceResponse = self._stub.WaitForInstanceCompletion(req, timeout=timeout)
+            if self._payload_store is not None and res.exists:
+                payload_helpers.deexternalize_payloads(res, self._payload_store)
             state = new_orchestration_state(req.instanceId, res)
             log_completion_state(self._logger, instance_id, state)
             return state
@@ -264,6 +282,10 @@ class TaskHubGrpcClient:
         with tracing.start_raise_event_span(event_name, instance_id):
             req = build_raise_event_req(instance_id, event_name, data)
             self._logger.info(f"Raising event '{event_name}' for instance '{instance_id}'.")
+            if self._payload_store is not None:
+                payload_helpers.externalize_payloads(
+                    req, self._payload_store, instance_id=instance_id,
+                )
             self._stub.RaiseEvent(req)
 
     def terminate_orchestration(self, instance_id: str, *,
@@ -272,6 +294,10 @@ class TaskHubGrpcClient:
         req = build_terminate_req(instance_id, output, recursive)
 
         self._logger.info(f"Terminating instance '{instance_id}'.")
+        if self._payload_store is not None:
+            payload_helpers.externalize_payloads(
+                req, self._payload_store, instance_id=instance_id,
+            )
         self._stub.TerminateInstance(req)
 
     def suspend_orchestration(self, instance_id: str) -> None:
@@ -330,6 +356,10 @@ class TaskHubGrpcClient:
                       input: Optional[Any] = None) -> None:
         req = build_signal_entity_req(entity_instance_id, operation_name, input)
         self._logger.info(f"Signaling entity '{entity_instance_id}' operation '{operation_name}'.")
+        if self._payload_store is not None:
+            payload_helpers.externalize_payloads(
+                req, self._payload_store, instance_id=str(entity_instance_id),
+            )
         self._stub.SignalEntity(req, None)  # TODO: Cancellation timeout?
 
     def get_entity(self,
@@ -341,7 +371,8 @@ class TaskHubGrpcClient:
         res: pb.GetEntityResponse = self._stub.GetEntity(req)
         if not res.exists:
             return None
-
+        if self._payload_store is not None:
+            payload_helpers.deexternalize_payloads(res, self._payload_store)
         return EntityMetadata.from_entity_metadata(res.entity, include_state)
 
     def get_all_entities(self,
@@ -357,6 +388,8 @@ class TaskHubGrpcClient:
         while True:
             query_request = build_query_entities_req(entity_query, _continuation_token)
             resp: pb.QueryEntitiesResponse = self._stub.QueryEntities(query_request)
+            if self._payload_store is not None:
+                payload_helpers.deexternalize_payloads(resp, self._payload_store)
             entities += [EntityMetadata.from_entity_metadata(entity, query_request.query.includeState) for entity in resp.entities]
             if check_continuation_token(resp.continuationToken, _continuation_token, self._logger):
                 _continuation_token = resp.continuationToken
@@ -402,7 +435,8 @@ class AsyncTaskHubGrpcClient:
                  log_formatter: Optional[logging.Formatter] = None,
                  secure_channel: bool = False,
                  interceptors: Optional[Sequence[shared.AsyncClientInterceptor]] = None,
-                 default_version: Optional[str] = None):
+                 default_version: Optional[str] = None,
+                 payload_store: Optional[PayloadStore] = None):
 
         interceptors = prepare_async_interceptors(metadata, interceptors)
 
@@ -415,6 +449,7 @@ class AsyncTaskHubGrpcClient:
         self._stub = stubs.TaskHubSidecarServiceStub(channel)
         self._logger = shared.get_logger("async_client", log_handler, log_formatter)
         self.default_version = default_version
+        self._payload_store = payload_store
 
     async def close(self) -> None:
         """Closes the underlying gRPC channel."""
@@ -451,6 +486,11 @@ class AsyncTaskHubGrpcClient:
                 req.parentTraceContext.CopyFrom(parent_trace_ctx)
 
             self._logger.info(f"Starting new '{req.name}' instance with ID = '{req.instanceId}'.")
+            # Externalize any large payloads in the request
+            if self._payload_store is not None:
+                await payload_helpers.externalize_payloads_async(
+                    req, self._payload_store, instance_id=req.instanceId,
+                )
             res: pb.CreateInstanceResponse = await self._stub.StartInstance(req)
             return res.instanceId
 
@@ -458,6 +498,8 @@ class AsyncTaskHubGrpcClient:
                                       fetch_payloads: bool = True) -> Optional[OrchestrationState]:
         req = pb.GetInstanceRequest(instanceId=instance_id, getInputsAndOutputs=fetch_payloads)
         res: pb.GetInstanceResponse = await self._stub.GetInstance(req)
+        if self._payload_store is not None and res.exists:
+            await payload_helpers.deexternalize_payloads_async(res, self._payload_store)
         return new_orchestration_state(req.instanceId, res)
 
     async def get_all_orchestration_states(self,
@@ -474,6 +516,8 @@ class AsyncTaskHubGrpcClient:
         while True:
             req = build_query_instances_req(orchestration_query, _continuation_token)
             resp: pb.QueryInstancesResponse = await self._stub.QueryInstances(req)
+            if self._payload_store is not None:
+                await payload_helpers.deexternalize_payloads_async(resp, self._payload_store)
             states += [parse_orchestration_state(res) for res in resp.orchestrationState]
             if check_continuation_token(resp.continuationToken, _continuation_token, self._logger):
                 _continuation_token = resp.continuationToken
@@ -489,6 +533,8 @@ class AsyncTaskHubGrpcClient:
         try:
             self._logger.info(f"Waiting up to {timeout}s for instance '{instance_id}' to start.")
             res: pb.GetInstanceResponse = await self._stub.WaitForInstanceStart(req, timeout=timeout)
+            if self._payload_store is not None and res.exists:
+                await payload_helpers.deexternalize_payloads_async(res, self._payload_store)
             return new_orchestration_state(req.instanceId, res)
         except grpc.aio.AioRpcError as rpc_error:
             if rpc_error.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
@@ -503,6 +549,8 @@ class AsyncTaskHubGrpcClient:
         try:
             self._logger.info(f"Waiting {timeout}s for instance '{instance_id}' to complete.")
             res: pb.GetInstanceResponse = await self._stub.WaitForInstanceCompletion(req, timeout=timeout)
+            if self._payload_store is not None and res.exists:
+                await payload_helpers.deexternalize_payloads_async(res, self._payload_store)
             state = new_orchestration_state(req.instanceId, res)
             log_completion_state(self._logger, instance_id, state)
             return state
@@ -517,6 +565,10 @@ class AsyncTaskHubGrpcClient:
         with tracing.start_raise_event_span(event_name, instance_id):
             req = build_raise_event_req(instance_id, event_name, data)
             self._logger.info(f"Raising event '{event_name}' for instance '{instance_id}'.")
+            if self._payload_store is not None:
+                await payload_helpers.externalize_payloads_async(
+                    req, self._payload_store, instance_id=instance_id,
+                )
             await self._stub.RaiseEvent(req)
 
     async def terminate_orchestration(self, instance_id: str, *,
@@ -525,6 +577,10 @@ class AsyncTaskHubGrpcClient:
         req = build_terminate_req(instance_id, output, recursive)
 
         self._logger.info(f"Terminating instance '{instance_id}'.")
+        if self._payload_store is not None:
+            await payload_helpers.externalize_payloads_async(
+                req, self._payload_store, instance_id=instance_id,
+            )
         await self._stub.TerminateInstance(req)
 
     async def suspend_orchestration(self, instance_id: str) -> None:
@@ -583,6 +639,10 @@ class AsyncTaskHubGrpcClient:
                             input: Optional[Any] = None) -> None:
         req = build_signal_entity_req(entity_instance_id, operation_name, input)
         self._logger.info(f"Signaling entity '{entity_instance_id}' operation '{operation_name}'.")
+        if self._payload_store is not None:
+            await payload_helpers.externalize_payloads_async(
+                req, self._payload_store, instance_id=str(entity_instance_id),
+            )
         await self._stub.SignalEntity(req, None)
 
     async def get_entity(self,
@@ -594,7 +654,8 @@ class AsyncTaskHubGrpcClient:
         res: pb.GetEntityResponse = await self._stub.GetEntity(req)
         if not res.exists:
             return None
-
+        if self._payload_store is not None:
+            await payload_helpers.deexternalize_payloads_async(res, self._payload_store)
         return EntityMetadata.from_entity_metadata(res.entity, include_state)
 
     async def get_all_entities(self,
@@ -610,6 +671,8 @@ class AsyncTaskHubGrpcClient:
         while True:
             query_request = build_query_entities_req(entity_query, _continuation_token)
             resp: pb.QueryEntitiesResponse = await self._stub.QueryEntities(query_request)
+            if self._payload_store is not None:
+                await payload_helpers.deexternalize_payloads_async(resp, self._payload_store)
             entities += [EntityMetadata.from_entity_metadata(entity, query_request.query.includeState) for entity in resp.entities]
             if check_continuation_token(resp.continuationToken, _continuation_token, self._logger):
                 _continuation_token = resp.continuationToken

durabletask-1.3.0.dev27/durabletask/extensions/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Durable Task SDK extension packages."""

durabletask-1.3.0.dev27/durabletask/extensions/azure_blob_payloads/__init__.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Azure Blob Storage payload externalization for Durable Task.
+
+This optional extension package provides a :class:`BlobPayloadStore`
+that stores large orchestration / activity payloads in Azure Blob
+Storage, keeping gRPC message sizes within safe limits.
+
+Install the required dependency with::
+
+    pip install durabletask[azure-blob-payloads]
+
+Usage::
+
+    from durabletask.extensions.azure_blob_payloads import (
+        BlobPayloadStore,
+        BlobPayloadStoreOptions,
+    )
+
+    store = BlobPayloadStore(BlobPayloadStoreOptions(
+        connection_string="DefaultEndpointsProtocol=https;...",
+    ))
+    worker = TaskHubGrpcWorker(payload_store=store)
+"""
+
+try:
+    from azure.storage.blob import BlobServiceClient  # noqa: F401
+except ImportError as exc:
+    raise ImportError(
+        "The 'azure-storage-blob' package is required for blob payload "
+        "support. Install it with:  pip install durabletask[azure-blob-payloads]"
+    ) from exc
+
+from durabletask.extensions.azure_blob_payloads.blob_payload_store import BlobPayloadStore
+from durabletask.extensions.azure_blob_payloads.options import BlobPayloadStoreOptions
+
+__all__ = ["BlobPayloadStore", "BlobPayloadStoreOptions"]

durabletask-1.3.0.dev27/durabletask/extensions/azure_blob_payloads/blob_payload_store.py

@@ -0,0 +1,225 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Azure Blob Storage implementation of :class:`PayloadStore`."""
+
+from __future__ import annotations
+
+import gzip
+import logging
+import uuid
+from typing import Optional
+
+from azure.core.exceptions import ResourceExistsError
+from azure.storage.blob import BlobServiceClient
+from azure.storage.blob.aio import BlobServiceClient as AsyncBlobServiceClient
+
+from durabletask.extensions.azure_blob_payloads.options import BlobPayloadStoreOptions
+from durabletask.payload.store import PayloadStore
+
+logger = logging.getLogger("durabletask-blobpayloads")
+
+# Token format matching the .NET SDK: blob:v1:<container>:<blobName>
+_TOKEN_PREFIX = "blob:v1:"
+
+
+class BlobPayloadStore(PayloadStore):
+    """Stores and retrieves large payloads in Azure Blob Storage.
+
+    This implementation is compatible with the .NET SDK's
+    ``AzureBlobPayloadsSideCarInterceptor`` – both SDKs use the same
+    token format (``blob:v1:<container>:<blobName>``) and the same
+    storage layout, allowing cross-language interoperability.
+
+    Example::
+
+        store = BlobPayloadStore(BlobPayloadStoreOptions(
+            connection_string="...",
+        ))
+
+    Args:
+        options: A :class:`BlobPayloadStoreOptions` with all settings.
+    """
+
+    def __init__(self, options: BlobPayloadStoreOptions):
+        if not options.connection_string and not options.account_url:
+            raise ValueError(
+                "Either 'connection_string' or 'account_url' (with 'credential') must be provided."
+            )
+
+        self._options = options
+        self._container_name = options.container_name
+
+        # Optional kwargs shared by both sync and async clients.
+        extra_kwargs: dict = {}
+        if options.api_version:
+            extra_kwargs["api_version"] = options.api_version
+
+        # Build sync client
+        if options.connection_string:
+            self._blob_service_client = BlobServiceClient.from_connection_string(
+                options.connection_string, **extra_kwargs,
+            )
+        else:
+            assert options.account_url is not None  # guaranteed by validation above
+            self._blob_service_client = BlobServiceClient(
+                account_url=options.account_url,
+                credential=options.credential,
+                **extra_kwargs,
+            )
+
+        # Build async client
+        if options.connection_string:
+            self._async_blob_service_client = AsyncBlobServiceClient.from_connection_string(
+                options.connection_string, **extra_kwargs,
+            )
+        else:
+            assert options.account_url is not None  # guaranteed by validation above
+            self._async_blob_service_client = AsyncBlobServiceClient(
+                account_url=options.account_url,
+                credential=options.credential,
+                **extra_kwargs,
+            )
+
+        self._ensure_container_created = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle / resource management
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying sync blob service client."""
+        self._blob_service_client.close()
+
+    async def close_async(self) -> None:
+        """Close the underlying async blob service client."""
+        await self._async_blob_service_client.close()
+
+    def __enter__(self) -> BlobPayloadStore:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> BlobPayloadStore:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close_async()
+
+    @property
+    def options(self) -> BlobPayloadStoreOptions:
+        return self._options
+
+    # ------------------------------------------------------------------
+    # Sync operations
+    # ------------------------------------------------------------------
+
+    def upload(self, data: bytes, *, instance_id: Optional[str] = None) -> str:
+        self._ensure_container_sync()
+
+        if self._options.enable_compression:
+            data = gzip.compress(data)
+
+        blob_name = self._make_blob_name(instance_id)
+        container_client = self._blob_service_client.get_container_client(self._container_name)
+        container_client.upload_blob(name=blob_name, data=data, overwrite=True)
+
+        token = f"{_TOKEN_PREFIX}{self._container_name}:{blob_name}"
+        logger.debug("Uploaded %d bytes -> %s", len(data), token)
+        return token
+
+    def download(self, token: str) -> bytes:
+        container, blob_name = self._parse_token(token)
+        container_client = self._blob_service_client.get_container_client(container)
+        blob_data = container_client.download_blob(blob_name).readall()
+
+        if self._options.enable_compression:
+            blob_data = gzip.decompress(blob_data)
+
+        logger.debug("Downloaded %d bytes <- %s", len(blob_data), token)
+        return blob_data
+
+    # ------------------------------------------------------------------
+    # Async operations
+    # ------------------------------------------------------------------
+
+    async def upload_async(self, data: bytes, *, instance_id: Optional[str] = None) -> str:
+        await self._ensure_container_async()
+
+        if self._options.enable_compression:
+            data = gzip.compress(data)
+
+        blob_name = self._make_blob_name(instance_id)
+        container_client = self._async_blob_service_client.get_container_client(self._container_name)
+        await container_client.upload_blob(name=blob_name, data=data, overwrite=True)
+
+        token = f"{_TOKEN_PREFIX}{self._container_name}:{blob_name}"
+        logger.debug("Uploaded %d bytes -> %s", len(data), token)
+        return token
+
+    async def download_async(self, token: str) -> bytes:
+        container, blob_name = self._parse_token(token)
+        container_client = self._async_blob_service_client.get_container_client(container)
+        stream = await container_client.download_blob(blob_name)
+        blob_data = await stream.readall()
+
+        if self._options.enable_compression:
+            blob_data = gzip.decompress(blob_data)
+
+        logger.debug("Downloaded %d bytes <- %s", len(blob_data), token)
+        return blob_data
+
+    # ------------------------------------------------------------------
+    # Token helpers
+    # ------------------------------------------------------------------
+
+    def is_known_token(self, value: str) -> bool:
+        try:
+            self._parse_token(value)
+            return True
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _parse_token(token: str) -> tuple[str, str]:
+        """Parse ``blob:v1:<container>:<blobName>`` into (container, blobName)."""
+        if not token.startswith(_TOKEN_PREFIX):
+            raise ValueError(f"Invalid blob payload token: {token!r}")
+        rest = token[len(_TOKEN_PREFIX):]
+        parts = rest.split(":", 1)
+        if len(parts) != 2 or not parts[0] or not parts[1]:
+            raise ValueError(f"Invalid blob payload token: {token!r}")
+        return parts[0], parts[1]
+
+    @staticmethod
+    def _make_blob_name(instance_id: Optional[str] = None) -> str:
+        """Generate a blob name, optionally scoped under an instance ID folder."""
+        unique = uuid.uuid4().hex
+        if instance_id:
+            return f"{instance_id}/{unique}"
+        return unique
+
+    # ------------------------------------------------------------------
+    # Container lifecycle
+    # ------------------------------------------------------------------
+
+    def _ensure_container_sync(self) -> None:
+        if self._ensure_container_created:
+            return
+        container_client = self._blob_service_client.get_container_client(self._container_name)
+        try:
+            container_client.create_container()
+        except ResourceExistsError:
+            pass
+        self._ensure_container_created = True
+
+    async def _ensure_container_async(self) -> None:
+        if self._ensure_container_created:
+            return
+        container_client = self._async_blob_service_client.get_container_client(self._container_name)
+        try:
+            await container_client.create_container()
+        except ResourceExistsError:
+            pass
+        self._ensure_container_created = True

durabletask-1.3.0.dev27/durabletask/extensions/azure_blob_payloads/options.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Configuration options for the Azure Blob payload store."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from durabletask.payload.store import LargePayloadStorageOptions
+
+
+@dataclass
+class BlobPayloadStoreOptions(LargePayloadStorageOptions):
+    """Configuration specific to the Azure Blob payload store.
+
+    Inherits general threshold / compression settings from
+    :class:`~durabletask.payload.store.LargePayloadStorageOptions`
+    and adds Azure Blob-specific fields.
+
+    Attributes:
+        container_name: Azure Blob container used to store externalized
+            payloads.  Defaults to ``"durabletask-payloads"``.
+        connection_string: Azure Storage connection string.  Mutually
+            exclusive with *account_url*.
+        account_url: Azure Storage account URL (e.g.
+            ``"https://<account>.blob.core.windows.net"``).  Use
+            together with *credential* for token-based auth.
+        credential: A ``TokenCredential`` instance (e.g.
+            ``DefaultAzureCredential``) for authenticating to the
+            storage account when using *account_url*.
+        api_version: Azure Storage API version override (useful for
+            Azurite compatibility).
+    """
+    container_name: str = "durabletask-payloads"
+    connection_string: Optional[str] = None
+    account_url: Optional[str] = None
+    credential: Any = field(default=None, repr=False)
+    api_version: Optional[str] = None

durabletask-1.3.0.dev27/durabletask/payload/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Public payload externalization API for the Durable Task SDK.
+
+This package exposes the abstract :class:`PayloadStore` interface,
+configuration options, and helper functions for externalizing and
+de-externalizing large payloads in protobuf messages.
+"""
+
+from durabletask.payload.helpers import (
+    deexternalize_payloads,
+    deexternalize_payloads_async,
+    externalize_payloads,
+    externalize_payloads_async,
+)
+from durabletask.payload.store import (
+    LargePayloadStorageOptions,
+    PayloadStore,
+)
+
+__all__ = [
+    "LargePayloadStorageOptions",
+    "PayloadStore",
+    "deexternalize_payloads",
+    "deexternalize_payloads_async",
+    "externalize_payloads",
+    "externalize_payloads_async",
+]