Re-add BlobPayloadStoreOptions

Author: andystaples

CHANGELOG.md

@@ -15,7 +15,7 @@ ADDED
   Pass a `BlobPayloadStore` to the worker and client via the
   `payload_store` parameter.
 - Added `durabletask.extensions.azure_blob_payloads` extension
-  package with `BlobPayloadStore`
+  package with `BlobPayloadStore` and `BlobPayloadStoreOptions`
 - Added `PayloadStore` abstract base class in
   `durabletask.payload` for custom storage backends
 - Added `durabletask.testing` module with `InMemoryOrchestrationBackend` for testing orchestrations without a sidecar process

docs/features.md

@@ -186,15 +186,15 @@ The built-in `BlobPayloadStore` uses Azure Blob Storage. Create a
 store instance and pass it to both the worker and client:
 
 ```python
-from durabletask.extensions.azure_blob_payloads import BlobPayloadStore
+from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions
 
-store = BlobPayloadStore(
+store = BlobPayloadStore(BlobPayloadStoreOptions(
     connection_string="DefaultEndpointsProtocol=https;...",
     container_name="durabletask-payloads",  # default
     threshold_bytes=900_000,                # default (900 KB)
     max_stored_payload_bytes=10_485_760,    # default (10 MB)
     enable_compression=True,                # default
-)
+))
 ```
 
 Then pass the store to the worker and client:
@@ -225,10 +225,10 @@ You can also authenticate using `account_url` and a
 ```python
 from azure.identity import DefaultAzureCredential
 
-store = BlobPayloadStore(
+store = BlobPayloadStore(BlobPayloadStoreOptions(
     account_url="https://<account>.blob.core.windows.net",
     credential=DefaultAzureCredential(),
-)
+))
 ```
 
 #### Configuration options

docs/supported-patterns.md

@@ -133,14 +133,14 @@ install the optional dependency and configure a payload store on the
 worker and client:
 
 ```python
-from durabletask.extensions.azure_blob_payloads import BlobPayloadStore
+from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions
 from durabletask.azuremanaged.client import DurableTaskSchedulerClient
 from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
 
 # Configure the blob payload store
-store = BlobPayloadStore(
+store = BlobPayloadStore(BlobPayloadStoreOptions(
     connection_string="DefaultEndpointsProtocol=https;...",
-)
+))
 
 # Pass the store to both worker and client
 with DurableTaskSchedulerWorker(

durabletask/extensions/azure_blob_payloads/__init__.py

@@ -13,11 +13,14 @@
 
 Usage::
 
-    from durabletask.extensions.azure_blob_payloads import BlobPayloadStore
+    from durabletask.extensions.azure_blob_payloads import (
+        BlobPayloadStore,
+        BlobPayloadStoreOptions,
+    )
 
-    store = BlobPayloadStore(
+    store = BlobPayloadStore(BlobPayloadStoreOptions(
         connection_string="DefaultEndpointsProtocol=https;...",
-    )
+    ))
     worker = TaskHubGrpcWorker(payload_store=store)
 """
 
@@ -30,5 +33,6 @@
     ) from exc
 
 from durabletask.extensions.azure_blob_payloads.blob_payload_store import BlobPayloadStore
+from durabletask.extensions.azure_blob_payloads.options import BlobPayloadStoreOptions
 
-__all__ = ["BlobPayloadStore"]
+__all__ = ["BlobPayloadStore", "BlobPayloadStoreOptions"]

durabletask/extensions/azure_blob_payloads/blob_payload_store.py

@@ -8,12 +8,13 @@
 import gzip
 import logging
 import uuid
-from typing import Any, Optional
+from typing import Optional
 
 from azure.storage.blob import BlobServiceClient
 from azure.storage.blob.aio import BlobServiceClient as AsyncBlobServiceClient
 
-from durabletask.payload.store import LargePayloadStorageOptions, PayloadStore
+from durabletask.extensions.azure_blob_payloads.options import BlobPayloadStoreOptions
+from durabletask.payload.store import PayloadStore
 
 logger = logging.getLogger("durabletask-blobpayloads")
 
@@ -29,79 +30,60 @@ class BlobPayloadStore(PayloadStore):
     token format (``blob:v1:<container>:<blobName>``) and the same
     storage layout, allowing cross-language interoperability.
 
+    Example::
+
+        store = BlobPayloadStore(BlobPayloadStoreOptions(
+            connection_string="...",
+        ))
+
     Args:
-        connection_string: Azure Storage connection string.  Mutually
-            exclusive with *account_url*.
-        account_url: Azure Storage account URL.  Must be combined with
-            *credential*.
-        credential: A ``TokenCredential`` for token-based auth.
-        container_name: Blob container for externalized payloads.
-        threshold_bytes: Payloads larger than this are externalized.
-        max_stored_payload_bytes: Maximum externalized payload size.
-        enable_compression: GZip-compress payloads before uploading.
-        api_version: Azure Storage API version override (useful for
-            Azurite compatibility).
+        options: A :class:`BlobPayloadStoreOptions` with all settings.
     """
 
-    def __init__(
-        self,
-        *,
-        connection_string: Optional[str] = None,
-        account_url: Optional[str] = None,
-        credential: Any = None,
-        container_name: str = "durabletask-payloads",
-        threshold_bytes: int = 900_000,
-        max_stored_payload_bytes: int = 10 * 1024 * 1024,
-        enable_compression: bool = True,
-        api_version: Optional[str] = None,
-    ):
-        if not connection_string and not account_url:
+    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 = LargePayloadStorageOptions(
-            threshold_bytes=threshold_bytes,
-            max_stored_payload_bytes=max_stored_payload_bytes,
-            enable_compression=enable_compression,
-        )
-        self._container_name = container_name
+        self._options = options
+        self._container_name = options.container_name
 
         # Optional kwargs shared by both sync and async clients.
         extra_kwargs: dict = {}
-        if api_version:
-            extra_kwargs["api_version"] = api_version
+        if options.api_version:
+            extra_kwargs["api_version"] = options.api_version
 
         # Build sync client
-        if connection_string:
+        if options.connection_string:
             self._blob_service_client = BlobServiceClient.from_connection_string(
-                connection_string, **extra_kwargs,
+                options.connection_string, **extra_kwargs,
             )
         else:
-            assert account_url is not None  # guaranteed by validation above
+            assert options.account_url is not None  # guaranteed by validation above
             self._blob_service_client = BlobServiceClient(
-                account_url=account_url,
-                credential=credential,
+                account_url=options.account_url,
+                credential=options.credential,
                 **extra_kwargs,
             )
 
         # Build async client
-        if connection_string:
+        if options.connection_string:
             self._async_blob_service_client = AsyncBlobServiceClient.from_connection_string(
-                connection_string, **extra_kwargs,
+                options.connection_string, **extra_kwargs,
             )
         else:
-            assert account_url is not None  # guaranteed by validation above
+            assert options.account_url is not None  # guaranteed by validation above
             self._async_blob_service_client = AsyncBlobServiceClient(
-                account_url=account_url,
-                credential=credential,
+                account_url=options.account_url,
+                credential=options.credential,
                 **extra_kwargs,
             )
 
         self._ensure_container_created = False
 
     @property
-    def options(self) -> LargePayloadStorageOptions:
+    def options(self) -> BlobPayloadStoreOptions:
         return self._options
 
     # ------------------------------------------------------------------

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

examples/large_payload/README.md

@@ -102,7 +102,7 @@ $env:STORAGE_CONNECTION_STRING = "DefaultEndpointsProtocol=https;..."
 
 ## Configuration Options
 
-The `BlobPayloadStore` constructor supports the following settings:
+The `BlobPayloadStoreOptions` class supports the following settings:
 
 | Option | Default | Description |
 |---|---|---|

examples/large_payload/app.py

@@ -30,7 +30,7 @@
 from durabletask import client, task
 from durabletask.azuremanaged.client import DurableTaskSchedulerClient
 from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
-from durabletask.extensions.azure_blob_payloads import BlobPayloadStore
+from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions
 
 
 # --------------- Activities ---------------
@@ -77,11 +77,11 @@ def main():
     print(f"Using endpoint: {endpoint}")
 
     # Configure the blob payload store
-    store = BlobPayloadStore(
+    store = BlobPayloadStore(BlobPayloadStoreOptions(
         connection_string=storage_conn_str,
         # Use a low threshold so that we can see externalization in action
         threshold_bytes=1_024,
-    )
+    ))
 
     secure_channel = endpoint.startswith("https://")
     credential = DefaultAzureCredential() if secure_channel else None

tests/durabletask/test_large_payload.py

@@ -417,24 +417,30 @@ class TestBlobPayloadStoreDefaults:
     def test_default_options(self):
         """Constructing with connection_string should use .NET SDK defaults."""
         pytest.importorskip("azure.storage.blob")
-        from durabletask.extensions.azure_blob_payloads.blob_payload_store import BlobPayloadStore
+        from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions
 
-        store = BlobPayloadStore(connection_string="UseDevelopmentStorage=true")
+        store = BlobPayloadStore(BlobPayloadStoreOptions(
+            connection_string="UseDevelopmentStorage=true",
+        ))
         opts = store.options
         assert opts.threshold_bytes == 900_000
         assert opts.max_stored_payload_bytes == 10 * 1024 * 1024
         assert opts.enable_compression is True
+        assert opts.container_name == "durabletask-payloads"
+        assert opts.connection_string == "UseDevelopmentStorage=true"
 
     def test_custom_options(self):
         """Custom constructor params should be reflected in options."""
         pytest.importorskip("azure.storage.blob")
-        from durabletask.extensions.azure_blob_payloads.blob_payload_store import BlobPayloadStore
+        from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions
 
-        store = BlobPayloadStore(
+        store = BlobPayloadStore(BlobPayloadStoreOptions(
             connection_string="UseDevelopmentStorage=true",
             threshold_bytes=500_000,
-        )
+            container_name="my-container",
+        ))
         assert store.options.threshold_bytes == 500_000
+        assert store.options.container_name == "my-container"
 
 
 # ------------------------------------------------------------------
@@ -549,5 +555,5 @@ def test_no_credentials_raises(self):
         pytest.importorskip("azure.storage.blob")
         from durabletask.extensions.azure_blob_payloads.blob_payload_store import BlobPayloadStore
 
-        with pytest.raises(ValueError, match="Either 'connection_string' or 'account_url'"):
-            BlobPayloadStore()
+        with pytest.raises(TypeError):
+            BlobPayloadStore()  # type: ignore[call-arg]

tests/durabletask/test_large_payload_e2e.py

@@ -25,7 +25,7 @@
 # Skip the entire module if azure-storage-blob is not installed.
 azure_blob = pytest.importorskip("azure.storage.blob")
 
-from durabletask.extensions.azure_blob_payloads import BlobPayloadStore  # noqa: E402
+from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions  # noqa: E402
 
 # Azurite well-known connection string
 AZURITE_CONN_STR = "UseDevelopmentStorage=true"
@@ -76,13 +76,13 @@ def _azurite_is_running() -> bool:
 @pytest.fixture(scope="module")
 def payload_store():
     """Create a BlobPayloadStore pointing at Azurite with a low threshold."""
-    store = BlobPayloadStore(
+    store = BlobPayloadStore(BlobPayloadStoreOptions(
         connection_string=AZURITE_CONN_STR,
         container_name=TEST_CONTAINER,
         threshold_bytes=THRESHOLD_BYTES,
         enable_compression=True,
         api_version=AZURITE_API_VERSION,
-    )
+    ))
     yield store
 
     # Clean up: delete the test container.
@@ -318,13 +318,13 @@ def test_small_payload_stays_inline(self, payload_store):
 
         # Use a fresh container to isolate blob count
         fresh_container = f"small-test-{uuid.uuid4().hex[:8]}"
-        store = BlobPayloadStore(
+        store = BlobPayloadStore(BlobPayloadStoreOptions(
             connection_string=AZURITE_CONN_STR,
             container_name=fresh_container,
             threshold_bytes=THRESHOLD_BYTES,
             enable_compression=True,
             api_version=AZURITE_API_VERSION,
-        )
+        ))
 
         def echo(ctx: task.OrchestrationContext, inp: str):
             return inp