[5.1.x] Refs #26029 -- Extended docs for the StorageHandler default instance.

Third-party packages that provide storages need to rely on the
StorageHandler API in order to allow users to use the `storages` module
instance to override defaults. Minimally documenting these methods
allows package authors to rely on them.

Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>

Backport of 6dcab75d5d8c2ef18de15323930057e6fa9ec00f from main.

1 files changed, 19 insertions, 1 deletions

diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt
index f7c290a150..52c8f90427 100644
--- a/docs/ref/files/storage.txt
+++ b/docs/ref/files/storage.txt
@@ -11,7 +11,25 @@ Django provides convenient ways to access the default storage class:
 
 .. data:: storages
 
-    Storage instances as defined by :setting:`STORAGES`.
+    A dictionary-like object that allows retrieving a storage instance using
+    its alias as defined by :setting:`STORAGES`.
+
+    ``storages`` has an attribute ``backends``, which defaults to the raw value
+    provided in :setting:`STORAGES`.
+
+    Additionally, ``storages`` provides a ``create_storage()`` method that
+    accepts the dictionary used in :setting:`STORAGES` for a backend, and
+    returns a storage instance based on that backend definition. This may be
+    useful for third-party packages needing to instantiate storages in tests:
+
+    .. code-block:: pycon
+
+        >>> from django.core.files.storage import storages
+        >>> storages.backends
+        {'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
+         'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
+         'custom': {'BACKEND': 'package.storage.CustomStorage'}}
+        >>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})
 
 .. class:: DefaultStorage