Skip to content

Commit

Permalink
Refs #26029 -- Extended docs for the StorageHandler default instance.
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
carltongibson and sarahboyce authored Oct 24, 2024
1 parent 34066d6 commit 6dcab75
Showing 1 changed file with 19 additions and 1 deletion.
20 changes: 19 additions & 1 deletion docs/ref/files/storage.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 6dcab75

Please sign in to comment.