diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/contrib/staticfiles.txt | 30 | ||||
| -rw-r--r-- | docs/ref/files/storage.txt | 21 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 37 | ||||
| -rw-r--r-- | docs/ref/templates/builtins.txt | 2 |
4 files changed, 64 insertions, 26 deletions
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 08fc23bdb1..a72e2ae286 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -60,11 +60,12 @@ specified by the :setting:`INSTALLED_APPS` setting. The :djadmin:`collectstatic` management command calls the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process` -method of the :setting:`STATICFILES_STORAGE` after each run and passes -a list of paths that have been found by the management command. It also -receives all command line options of :djadmin:`collectstatic`. This is used -by the :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` -by default. +method of the ``staticfiles`` storage backend from :setting:`STORAGES` after +each run and passes a list of paths that have been found by the management +command. It also receives all command line options of :djadmin:`collectstatic`. +This is used by the +:class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` by +default. By default, collected files receive permissions from :setting:`FILE_UPLOAD_PERMISSIONS` and collected directories receive permissions @@ -82,7 +83,7 @@ respectively. For example:: kwargs['directory_permissions_mode'] = 0o760 super().__init__(*args, **kwargs) -Then set the :setting:`STATICFILES_STORAGE` setting to +Then set the ``staticfiles`` storage backend in :setting:`STORAGES` setting to ``'path.to.MyStaticFilesStorage'``. Some commonly used options are: @@ -113,7 +114,8 @@ Some commonly used options are: Don't call the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process` - method of the configured :setting:`STATICFILES_STORAGE` storage backend. + method of the configured ``staticfiles`` storage backend from + :setting:`STORAGES`. .. django-admin-option:: --no-default-ignore @@ -360,7 +362,7 @@ attribute. It defaults to 5. To enable the ``ManifestStaticFilesStorage`` you have to make sure the following requirements are met: -* the :setting:`STATICFILES_STORAGE` setting is set to +* the ``staticfiles`` storage backend in :setting:`STORAGES` setting is set to ``'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'`` * the :setting:`DEBUG` setting is set to ``False`` * you've collected all your static files by using the @@ -381,9 +383,9 @@ If a file isn't found in the ``staticfiles.json`` manifest at runtime, a Due to the requirement of running :djadmin:`collectstatic`, this storage typically shouldn't be used when running tests as ``collectstatic`` isn't run -as part of the normal test setup. During testing, ensure that the -:setting:`STATICFILES_STORAGE` setting is set to something else like -``'django.contrib.staticfiles.storage.StaticFilesStorage'`` (the default). +as part of the normal test setup. During testing, ensure that ``staticfiles`` +storage backend in the :setting:`STORAGES` setting is set to something else +like ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` (the default). .. method:: storage.ManifestStaticFilesStorage.file_hash(name, content=None) @@ -434,7 +436,8 @@ files: - The builtin template tag :ttag:`static` which takes a path and urljoins it with the static prefix :setting:`STATIC_URL`. If ``django.contrib.staticfiles`` is installed, the tag uses the ``url()`` - method of the :setting:`STATICFILES_STORAGE` instead. + method of the ``staticfiles`` storage backend from :setting:`STORAGES` + instead. - The builtin template tag :ttag:`get_static_prefix` which populates a template variable with the static prefix :setting:`STATIC_URL` to be @@ -443,6 +446,9 @@ files: - The similar template tag :ttag:`get_media_prefix` which works like :ttag:`get_static_prefix` but uses :setting:`MEDIA_URL`. +- The ``staticfiles`` key in :data:`django.core.files.storage.storages` + contains a ready-to-use instance of the staticfiles storage backend. + .. _staticfiles-development-view: Static file development view diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index d5daccf834..47a5788574 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -18,9 +18,9 @@ Django provides convenient ways to access the default storage class: .. class:: DefaultStorage :class:`~django.core.files.storage.DefaultStorage` provides - lazy access to the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses - :func:`~django.core.files.storage.get_storage_class` internally. + lazy access to the default storage system as defined by ``default`` key in + :setting:`STORAGES`. :class:`DefaultStorage` uses + :data:`~django.core.files.storage.storages` internally. .. data:: default_storage @@ -32,11 +32,16 @@ Django provides convenient ways to access the default storage class: Returns a class or module which implements the storage API. When called without the ``import_path`` parameter ``get_storage_class`` - will return the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided, - ``get_storage_class`` will attempt to import the class or module from the - given path and will return it if successful. An exception will be - raised if the import is unsuccessful. + will return the default storage system as defined by ``default`` key in + :setting:`STORAGES`. If ``import_path`` is provided, ``get_storage_class`` + will attempt to import the class or module from the given path and will + return it if successful. An exception will be raised if the import is + unsuccessful. + + .. deprecated:: 4.2 + + The ``get_storage_class()`` function is deprecated. Use + :data:`storages` instead The ``FileSystemStorage`` class =============================== diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index d1b638f4b6..aa8606a08b 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1356,6 +1356,12 @@ Default: ``'``:class:`django.core.files.storage.FileSystemStorage`\ ``'`` Default file storage class to be used for any file-related operations that don't specify a particular storage system. See :doc:`/topics/files`. +.. deprecated:: 4.2 + + This setting is deprecated. Starting with Django 4.2, default file storage + engine can be configured with the :setting:`STORAGES` setting under the + ``default`` key. + .. setting:: DEFAULT_FROM_EMAIL ``DEFAULT_FROM_EMAIL`` @@ -2615,13 +2621,28 @@ See also the :doc:`/ref/checks` documentation. Default:: - {} + { + "default": { + "BACKEND": "django.core.files.storage.FileSystemStorage", + }, + "staticfiles": { + "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage", + }, + } A dictionary containing the settings for all storages to be used with Django. It is a nested dictionary whose contents map a storage alias to a dictionary containing the options for an individual storage. -Storages can have any alias you choose. +Storages can have any alias you choose. However, there are two aliases with +special significance: + +* ``default`` for :doc:`managing files </topics/files>`. + ``'``:class:`django.core.files.storage.FileSystemStorage`\ ``'`` is the + default storage engine. +* ``staticfiles`` for :doc:`managing static files </ref/contrib/staticfiles>`. + ``'``:class:`django.contrib.staticfiles.storage.StaticFilesStorage`\ ``'`` is + the default storage engine. The following is an example ``settings.py`` snippet defining a custom file storage called ``example``:: @@ -3598,10 +3619,16 @@ The file storage engine to use when collecting static files with the :djadmin:`collectstatic` management command. A ready-to-use instance of the storage backend defined in this setting -can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``. +can be found under ``staticfiles`` key in ``django.core.files.storage.storages``. For an example, see :ref:`staticfiles-from-cdn`. +.. deprecated:: 4.2 + + This setting is deprecated. Starting with Django 4.2, static files storage + engine can be configured with the :setting:`STORAGES` setting under the + ``staticfiles`` key. + .. setting:: STATICFILES_FINDERS ``STATICFILES_FINDERS`` @@ -3627,8 +3654,8 @@ used. One finder is disabled by default: ``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to your :setting:`STATICFILES_FINDERS` setting, it will look for static files in -the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` -setting. +the default file storage as defined by the ``default`` key in the +:setting:`STORAGES` setting. .. note:: diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 13a8694ad6..5804f455bd 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -2629,7 +2629,7 @@ A set of Django template filters useful for adding a "human touch" to data. See To link to static files that are saved in :setting:`STATIC_ROOT` Django ships with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles` app is installed, the tag will serve files using ``url()`` method of the -storage specified by :setting:`STATICFILES_STORAGE`. For example:: +storage specified by ``staticfiles`` in :setting:`STORAGES`. For example:: {% load static %} <img src="{% static 'images/hi.jpg' %}" alt="Hi!"> |