Приложение staticfiles

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

Настройки

См. настройки staticfiles для подробной информации о следующих настройках:

• STORAGES
• STATIC_ROOT
• STATIC_URL
• STATICFILES_DIRS
• STATICFILES_STORAGE
• 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

Не игнорировать общие шаблоны для скрытых файлов '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, который принимает путь и выполняет urljoin с префиксом статических файлов 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 TestCase расширяет django.test.LiveServerTestCase.

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

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