Add AZURE_CLIENT_OPTIONS setting (#1432)

This allows users to customize the kwarg options for the
BlobServiceClient.

This change also deprecates the AZURE_API_VERSION setting as well.

CHANGELOG.rst

@@ -1,6 +1,19 @@
 django-storages CHANGELOG
 =========================
 
+X.YY.Z (UNRELEASED)
+*******************
+
+Azure
+-----
+
+- **Deprecated**: The setting ``AZURE_API_VERSION/api_version`` setting is deprecated in favor of
+  the new ``AZURE_CLIENT_OPTIONS`` setting. A future version will remove support for this setting.
+- Add ``AZURE_CLIENT_OPTIONS`` settings to enable customization of all ``BlobServiceClient`` parameters
+  such as ``api_version`` and all ``retry*`` options. (`#1432`_)
+
+.. _#1432: https://github.com/jschneier/django-storages/pull/1432
+
 1.14.4 (2024-07-09)
 *******************
 

docs/backends/azure.rst

@@ -185,10 +185,22 @@ Settings
 
   This is a Python ``dict`` and the possible parameters are: ``content_type``, ``content_encoding``, ``content_language``, ``content_disposition``, ``cache_control``, and ``content_md5``.
 
+``client_options`` or ``AZURE_CLIENT_OPTIONS``
+
+  Default: ``{}``
+
+  A dict of kwarg options to send to the ``BlobServiceClient``. A partial list of options can be found
+  `in the client docs <https://learn.microsoft.com/en-us/python/api/azure-storage-blob/azure.storage.blob.blobserviceclient?view=azure-python#keyword-only-parameters>`__.
+
+  Additionally, this setting can be used to configure the client retry settings. To see how follow the
+  `Python retry docs <https://learn.microsoft.com/en-us/azure/storage/blobs/storage-retry-policy-python>`__.
+
 ``api_version`` or ``AZURE_API_VERSION``
 
   Default: ``None``
 
+  **Note: This option is deprecated. Use client_options/AZURE_CLIENT_OPTIONS instead.**
+
   The Azure Storage API version to use. Default value is the most recent service version that is compatible with the current SDK.
   Setting to an older version may result in reduced feature compatibility.
 

storages/backends/azure_storage.py

@@ -1,4 +1,5 @@
 import mimetypes
+import warnings
 from datetime import datetime
 from datetime import timedelta
 from tempfile import SpooledTemporaryFile
@@ -152,6 +153,7 @@ def get_default_settings(self):
             "connection_string": setting("AZURE_CONNECTION_STRING"),
             "token_credential": setting("AZURE_TOKEN_CREDENTIAL"),
             "api_version": setting("AZURE_API_VERSION", None),
+            "client_options": setting("AZURE_CLIENT_OPTIONS", {}),
         }
 
     def _get_service_client(self):
@@ -171,8 +173,15 @@ def _get_service_client(self):
             credential = self.sas_token
         elif self.token_credential:
             credential = self.token_credential
-        options = {}
+
+        options = self.client_options
         if self.api_version:
+            warnings.warn(
+                "The AZURE_API_VERSION/api_version setting is deprecated "
+                "and will be removed in a future version. Use AZURE_CLIENT_OPTIONS "
+                "to customize any of the BlobServiceClient kwargs.",
+                DeprecationWarning,
+            )
             options["api_version"] = self.api_version
         return BlobServiceClient(account_url, credential=credential, **options)
 

tests/test_azure.py

@@ -367,3 +367,14 @@ def test_override_init_argument(self):
         self.assertEqual(storage.azure_container, "foo1")
         storage = azure_storage.AzureStorage(azure_container="foo2")
         self.assertEqual(storage.azure_container, "foo2")
+
+    @mock.patch("storages.backends.azure_storage.BlobServiceClient", autospec=True)
+    def test_client_settings(self, bsc):
+        with override_settings(AZURE_CLIENT_OPTIONS={"api_version": "1.3"}):
+            storage = azure_storage.AzureStorage(account_name="test")
+            client_mock = mock.MagicMock()
+            bsc.return_value.get_container_client.return_value = client_mock
+            self.assertEqual(storage.client, client_mock)
+            bsc.assert_called_once_with(
+                "https://test.blob.core.windows.net", credential=None, api_version="1.3"
+            )