From 123b9b97c362d1136c7622151951f3f626077185 Mon Sep 17 00:00:00 2001
From: David Davis <daviddavis@users.noreply.github.com>
Date: Sat, 20 Jul 2024 12:51:07 -0400
Subject: [PATCH] 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                      | 13 +++++++++++++
 docs/backends/azure.rst            | 12 ++++++++++++
 storages/backends/azure_storage.py | 11 ++++++++++-
 tests/test_azure.py                | 11 +++++++++++
 4 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 61200738..dbe83bb6 100644
--- a/CHANGELOG.rst
+++ b/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)
 *******************
 
diff --git a/docs/backends/azure.rst b/docs/backends/azure.rst
index 20c94399..fb242ff8 100644
--- a/docs/backends/azure.rst
+++ b/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.
 
diff --git a/storages/backends/azure_storage.py b/storages/backends/azure_storage.py
index f821df08..a696e220 100644
--- a/storages/backends/azure_storage.py
+++ b/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)
 
diff --git a/tests/test_azure.py b/tests/test_azure.py
index 8c15f6a7..3700b60d 100644
--- a/tests/test_azure.py
+++ b/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"
+            )