Приложение staticfiles

django.contrib.staticfiles собирает статические файлы из каждой вашей приложения (и любых других указанных вами мест) в одно место, которое легко можно использовать в рабочей среде.

Настройки

Подробные сведения о следующих настройках см. в настройках staticfiles:

• STORAGES
• STATIC_ROOT
• STATIC_URL
• STATICFILES_DIRS
• STATICFILES_FINDERS

Команды управления

django.contrib.staticfiles предоставляет три команды управления.

collectstatic

django-admin collectstatic

Собирает статические файлы в STATIC_ROOT.

Дублирующиеся имена файлов по умолчанию разрешаются аналогично тому, как работают разрешения шаблонов: файл, который первый найден в одном из указанных мест, будет использован. Если вы запутались, команда findstatic может помочь показать, какие файлы найдены.

При последующих collectstatic запусках (если STATIC_ROOT не пусто), файлы копируются только в том случае, если отметка времени изменения больше, чем отметка времени файла в STATIC_ROOT. Поэтому, если вы удаляете приложение из INSTALLED_APPS, рекомендуется использовать параметр collectstatic --clear для удаления устаревших статических файлов.

Поиск файлов выполняется с использованием enabled finders. По умолчанию ищется во всех местах, определённых в STATICFILES_DIRS, и в каталоге 'static' приложений, указанных в настройке INSTALLED_APPS.

Команда управления collectstatic вызывает метод post_process() хранилища staticfiles из STORAGES после каждого запуска и передаёт список путей, которые были найдены командой управления. Она также получает все параметры командной строки collectstatic. Это используется хранилищем ManifestStaticFilesStorage по умолчанию.

По умолчанию собранные файлы получают разрешения из FILE_UPLOAD_PERMISSIONS, а собранные каталоги — из FILE_UPLOAD_DIRECTORY_PERMISSIONS. Если вам нужны другие разрешения для этих файлов и/или каталогов, вы можете наследоваться от одного из классов хранилищ статических файлов и указать параметры file_permissions_mode и/или directory_permissions_mode соответственно. Например:

from django.contrib.staticfiles import storage


class MyStaticFilesStorage(storage.StaticFilesStorage):
    def __init__(self, *args, **kwargs):
        kwargs["file_permissions_mode"] = 0o640
        kwargs["directory_permissions_mode"] = 0o760
        super().__init__(*args, **kwargs)

Затем установите хранилище staticfiles в настройке STORAGES на 'path.to.MyStaticFilesStorage'.

Некоторые часто используемые параметры:

--noinput, --no-input

НЕ запрашивать ввод от пользователя.

--ignore PATTERN, -i PATTERN

Игнорировать файлы, каталоги или пути, соответствующие этому шаблону в стиле glob. Используйте несколько раз для игнорирования большего числа. При указании пути всегда используйте слеши, даже в Windows.

--dry-run, -n

Выполнить все действия, кроме изменения файловой системы.

--clear, -c

Очистить существующие файлы перед копированием или установкой ссылки на исходный файл.

--link, -l

Создать символическую ссылку на каждый файл вместо копирования.

--no-post-process

Не вызывать метод post_process() настроенного хранилища staticfiles из STORAGES.

--no-default-ignore

Не игнорировать стандартные шаблоны glob 'CVS', '.*' и '*~'.

Полный список параметров см. в справке по командам, выполнив:

$ python manage.py collectstatic --help

...\> py manage.py collectstatic --help

Настройка списка игнорируемых шаблонов

Список игнорируемых шаблонов по умолчанию, ['CVS', '.*', '*~'], может быть настроен более стойким способом, чем предоставление параметра --ignore при каждом вызове collectstatic. Предоставьте пользовательский класс AppConfig, переопределите атрибут ignore_patterns этого класса и замените 'django.contrib.staticfiles' этим путем к классу в вашей настройке INSTALLED_APPS:

from django.contrib.staticfiles.apps import StaticFilesConfig


class MyStaticFilesConfig(StaticFilesConfig):
    ignore_patterns = [...]  # your custom ignore list

findstatic

django-admin findstatic staticfile [staticfile ...]

Ищет один или несколько относительных путей с включёнными поисковыми средствами.

Например:

$ python manage.py findstatic css/base.css admin/js/core.js
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Found 'admin/js/core.js' here:
  /home/polls.com/src/django/contrib/admin/media/js/core.js

...\> py manage.py findstatic css\base.css admin\js\core.js
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Found 'admin/js/core.js' here:
  /home/polls.com/src/django/contrib/admin/media/js/core.js

findstatic --first

По умолчанию все соответствующие места находятся. Для возвращения только первого совпадения для каждого относительного пути используйте параметр --first:

$ python manage.py findstatic css/base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

...\> py manage.py findstatic css\base.css --first
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css

Это вспомогательная функция отладки; она покажет вам именно тот статический файл, который будет собран для данного пути.

Установив флаг --verbosity в 0, вы можете подавить дополнительный вывод и получить только имена путей:

$ python manage.py findstatic css/base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css

...\> py manage.py findstatic css\base.css --verbosity 0
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css

С другой стороны, установив флаг --verbosity в 2, вы можете получить все каталоги, которые были просмотрены:

$ python manage.py findstatic css/base.css --verbosity 2
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Looking in the following locations:
  /home/special.polls.com/core/static
  /home/polls.com/core/static
  /some/other/path/static

...\> py manage.py findstatic css\base.css --verbosity 2
Found 'css/base.css' here:
  /home/special.polls.com/core/static/css/base.css
  /home/polls.com/core/static/css/base.css
Looking in the following locations:
  /home/special.polls.com/core/static
  /home/polls.com/core/static
  /some/other/path/static

runserver

django-admin runserver [addrport]

Переопределяет основную команду runserver, если приложение staticfiles включено в installed, и добавляет автоматическое предоставление статических файлов. Обслуживание файлов выполняется без использования MIDDLEWARE.

Команда добавляет следующие параметры:

--nostatic

Используйте параметр --nostatic для отключения предоставления статических файлов приложением staticfiles полностью. Этот параметр доступен только в том случае, если приложение staticfiles включено в настройке INSTALLED_APPS вашего проекта.

Пример использования:

$ django-admin runserver --nostatic

...\> django-admin runserver --nostatic

--insecure

Используйте параметр --insecure для принудительного предоставления статических файлов приложением staticfiles, даже если настройка DEBUG имеет значение False. Используя этот параметр, вы подтверждаете, что это крайне неэффективно и, вероятно, небезопасно. Этот параметр предназначен только для разработки на локальном компьютере, его никогда не следует использовать в рабочей среде и доступен только в том случае, если приложение staticfiles включено в настройку INSTALLED_APPS вашего проекта.

--insecure не работает с ManifestStaticFilesStorage.

Пример использования:

$ django-admin runserver --insecure

...\> django-admin runserver --insecure

Хранилища

StaticFilesStorage

class storage.StaticFilesStorage

Подкласс хранилища FileSystemStorage, использующего значение настройки STATIC_ROOT в качестве базовой директории файловой системы и значение настройки STATIC_URL в качестве базового URL соответственно.

storage.StaticFilesStorage.post_process(paths, **options)

Если этот метод определён в хранилище, он вызывается командой управления collectstatic после каждого выполнения и получает локальные хранилища и пути найденных файлов в виде словаря, а также опции командной строки. Он возвращает кортежи из трёх значений: original_path, processed_path, processed. Значения путей являются строками, а processed — булево значение, указывающее, был ли выполнен постпроцессинг, или исключение, если постпроцессинг не удался.

Хранилище ManifestStaticFilesStorage использует его для замены путей их хешированными аналогами и соответствующего обновления кэша.

ManifestStaticFilesStorage

class storage.ManifestStaticFilesStorage

Подкласс хранилища StaticFilesStorage, который сохраняет имена файлов, добавляя к имени файла MD5-хеш содержимого файла. Например, файл css/styles.css также будет сохранён как css/styles.55e7cbb9ba48.css.

Цель этого хранилища — продолжать обслуживание старых файлов на случай, если некоторые страницы всё ещё ссылаются на эти файлы, например, из-за кэширования со стороны пользователя или стороннего прокси-сервера. Кроме того, это очень полезно, если вы хотите применять заголовки Expires с датой в далёком будущем к развёрнутым файлам для ускорения времени загрузки при последующих посещениях страницы.

Хранилище автоматически заменяет пути, найденные в сохранённых файлах, соответствующие другим сохранённым файлам, путём кэшированной копии (используя метод post_process()). Регулярные выражения, используемые для поиска этих путей (django.contrib.staticfiles.storage.HashedFilesMixin.patterns), охватывают:

• Правило @import и оператор url() Каскадных таблиц стилей.
• Комментарии карты источников в файлах CSS и JavaScript.

Подкласс ManifestStaticFilesStorage и установите атрибут support_js_module_import_aggregation в значение True, если вы хотите использовать экспериментальные регулярные выражения для покрытия:

• Импорт модулей в JavaScript.
• Агрегация модулей в JavaScript.

Например, файл 'css/styles.css' с этим содержимым:

@import url("../admin/css/base.css");

…будет заменён вызовом метода url() хранилища ManifestStaticFilesStorage, в конечном итоге сохраняя файл 'css/styles.55e7cbb9ba48.css' с последующим содержимым:

@import url("../admin/css/base.27e20196a850.css");

Вы можете изменить местоположение файла манифеста, используя подкласс настраиваемого хранилища ManifestStaticFilesStorage, который задаёт аргумент manifest_storage. Например:

from django.conf import settings
from django.contrib.staticfiles.storage import (
    ManifestStaticFilesStorage,
    StaticFilesStorage,
)


class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def __init__(self, *args, **kwargs):
        manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
        super().__init__(*args, manifest_storage=manifest_storage, **kwargs)

storage.ManifestStaticFilesStorage.manifest_hash

Этот атрибут предоставляет единый хеш, который изменяется всякий раз, когда изменяется файл в манифесте. Это может быть полезно для оповещения SPA о том, что активы на сервере изменились (из-за нового развёртывания).

storage.ManifestStaticFilesStorage.max_post_process_passes

Поскольку статические файлы могут ссылаться на другие статические файлы, которые необходимо заменить, для замены путей может потребоваться несколько проходов, пока хеши файлов не сойдутся. Чтобы предотвратить бесконечный цикл из-за несовпадения хешей (например, если 'foo.css' ссылается на 'bar.css', которое ссылается на 'foo.css') существует максимальное количество проходов, после которого постпроцессинг прекращается. В случаях с большим количеством ссылок может потребоваться большее число проходов. Увеличение максимального количества проходов путём наследования класса ManifestStaticFilesStorage и установки атрибута max_post_process_passes. По умолчанию он равен 5.

Для включения ManifestStaticFilesStorage необходимо убедиться, что выполнены следующие требования:

• хранилище staticfiles в настройке STORAGES установлено в значение 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
• настройка DEBUG установлена в значение False
• вы собрали все статические файлы с помощью команды управления collectstatic

Поскольку вычисление MD5-хеша может быть ресурсоёмкой операцией для вашего сайта во время выполнения, staticfiles будет автоматически сохранять отображение с хешированными именами для всех обработанных файлов в файле staticfiles.json. Это происходит один раз при выполнении команды управления collectstatic.

storage.ManifestStaticFilesStorage.manifest_strict

Если файл не найден в манифесте staticfiles.json во время выполнения, будет поднято исключение ValueError. Это поведение можно отключить, создав подкласс ManifestStaticFilesStorage и установив атрибут manifest_strict в значение False — несуществующие пути останутся без изменений.

Из-за необходимости запуска команды collectstatic, это хранилище обычно не следует использовать при выполнении тестов, так как collectstatic не выполняется в рамках стандартной настройки тестов. Во время тестирования убедитесь, что хранилище staticfiles в настройке STORAGES установлено на другое значение, например, 'django.contrib.staticfiles.storage.StaticFilesStorage' (по умолчанию).

storage.ManifestStaticFilesStorage.file_hash(name, content=None)

Метод, используемый при создании хешированного имени файла. Должен вернуть хеш для данного имени файла и содержимого. По умолчанию он вычисляет MD5-хеш из фрагментов содержимого, как описано выше. Вы можете переопределить этот метод для использования собственного алгоритма хеширования.

ManifestFilesMixin

class storage.ManifestFilesMixin

Используйте этот миксин со своим хранилищем, чтобы добавить MD5-хеш содержимого файла к имени файла, как это делает ManifestStaticFilesStorage.

Модуль нахождения

staticfiles модуль нахождения имеет атрибут searched_locations — список путей к каталогам, в которых выполнялся поиск. Пример использования:

from django.contrib.staticfiles import finders

result = finders.find("css/base.css")
searched_locations = finders.searched_locations

Другие вспомогательные функции

Существуют несколько других вспомогательных функций за пределами приложения staticfiles для работы со статическими файлами:

• Процессор контекста django.template.context_processors.static(), который добавляет STATIC_URL в каждый контекст шаблона, отрисованный с помощью контекстов RequestContext.
• Встроенная метка шаблона static, которая принимает путь и объединяет его с префиксом статических файлов STATIC_URL. Если установлен django.contrib.staticfiles, метка использует метод url() хранилища статических файлов staticfiles из STORAGES.
• Встроенная метка шаблона get_static_prefix, которая заполняет переменную шаблона префиксом статических файлов STATIC_URL, чтобы использовать её как переменную или напрямую.
• Аналогичная метка шаблона get_media_prefix, которая работает так же, как get_static_prefix, но использует MEDIA_URL.
• Ключ staticfiles в django.core.files.storage.storages содержит готовый экземпляр хранилища статических файлов.

Просмотр статических файлов в режиме разработки

Инструменты работы со статическими файлами в основном предназначены для успешной их публикации в рабочей среде. Это обычно означает отдельный, выделенный сервер статических файлов, что создаёт избыточную нагрузку при разработке локально. Поэтому приложение staticfiles поставляется с помощной функцией для быстрого и простого обслуживания файлов локально в режиме разработки.

views.serve(request, path)

Эта функция-представление обслуживает статические файлы в режиме разработки.

Эта функция-представление автоматически включается при запуске runserver (с настройкой DEBUG, установленной в True).

Чтобы использовать функцию-представление с другим локальным сервером разработки, добавьте следующий фрагмент в конец вашей основной конфигурации URL:

from django.conf import settings
from django.contrib.staticfiles import views
from django.urls import re_path

if settings.DEBUG:
    urlpatterns += [
        re_path(r"^static/(?P<path>.*)$", views.serve),
    ]

Обратите внимание, что начало шаблона (r'^static/') должно совпадать с вашей настройкой STATIC_URL.

Поскольку это может быть немного сложно, есть также вспомогательная функция, которая сделает это за вас:

urls.staticfiles_urlpatterns()

Эта функция вернёт правильный шаблон URL для обслуживания статических файлов в уже определённом вами списке шаблонов. Используйте её так:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

Это позволит проанализировать вашу настройку STATIC_URL и подключить представление для обслуживания статических файлов соответственно. Не забудьте правильно настроить настройку STATICFILES_DIRS, чтобы django.contrib.staticfiles знало, где искать файлы помимо файлов в каталогах приложений.

Специализированный тест для поддержки «тестирования в реальном времени»

class testing.StaticLiveServerTestCase

Этот подкласс теста unittest расширяет django.test.LiveServerTestCase.

Как и его родительский класс, его можно использовать для написания тестов, которые включают запуск тестируемого кода и его использование с помощью инструментов тестирования через HTTP (например, Selenium, PhantomJS и т. д.), для чего необходимо опубликовать статические ресурсы.

Но, учитывая тот факт, что он использует функцию-представление django.contrib.staticfiles.views.serve(), описанную выше, он может прозрачно накладывать в процессе выполнения тестов ресурсы, предоставляемые поисковиками staticfiles. Это означает, что вам не нужно запускать collectstatic перед или как часть настройки ваших тестов.