From 6dcab75d5d8c2ef18de15323930057e6fa9ec00f Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Thu, 24 Oct 2024 16:57:04 +0200 Subject: [PATCH] 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> --- docs/ref/files/storage.txt | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) 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