Приложение staticfiles

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

Настройки

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

• 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_STORAGE после каждого запуска и передает список путей, которые были найдены командой управления. Она также получает все параметры командной строки команды 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_STORAGE на 'path.to.MyStaticFilesStorage'.

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

--noinput, --no-input

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

--ignore PATTERN, -i PATTERN

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

Изменено в Django 2.2:

Добавлена поддержка соответствия путям.

--dry-run, -n

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

--clear, -c

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

--link, -l

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

--no-post-process

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

--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/styles.css' с содержимым

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

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

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

storage.ManifestStaticFilesStorage.max_post_process_passes

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

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

• параметр STATICFILES_STORAGE должен быть установлен в значение '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_STORAGE установлен на другое значение, например, 'django.contrib.staticfiles.storage.StaticFilesStorage' (значение по умолчанию).

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

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

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

CachedStaticFilesStorage — это класс, аналогичный ManifestStaticFilesStorage, но использует фреймворк кеширования Django для хранения хешированных имён обработанных файлов вместо статического файла манифеста с именем staticfiles.json. Это в основном полезно в ситуациях, когда у вас нет доступа к файловой системе.

Если нужно переопределить определённые параметры бэкенда кеша, используемого хранилищем, укажите пользовательскую запись в параметре CACHES с именем 'staticfiles'. В противном случае используется бэкенд кеша 'default'.

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_STORAGE.
• Встроенная метка шаблона get_static_prefix, которая заполняет переменную шаблона префиксом статических файлов STATIC_URL для использования как переменной или непосредственно.
• Аналогичная метка шаблона get_media_prefix, которая работает так же, как get_static_prefix, но использует MEDIA_URL.

Представление статических файлов для разработки

Инструменты для статических файлов в основном предназначены для успешной публикации статических файлов в производство. Обычно это означает отдельный, выделенный сервер статических файлов, что создаёт значительные накладные расходы при разработке локально. Поэтому приложение 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 перед или в качестве части вашей настройки тестов.