Приложение 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. Это используется по умолчанию для CachedStaticFilesStorage.

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

--dry-run, -n

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

--clear, -c

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

--link, -l

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

--no-post-process

Не вызывать метод post_process() настроек STATICFILES_STORAGE.

--no-default-ignore

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

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

$ python 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

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

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

Установив флаг --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

С другой стороны, установив флаг --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

runserver

django-admin runserver [addrport]

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

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

--nostatic

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

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

django-admin runserver --nostatic

--insecure

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

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

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

django-admin runserver --insecure

Хранилища

StaticFilesStorage

class storage.StaticFilesStorage

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

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

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

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

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'.

Модуль поиска

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 TestCase расширяет django.test.LiveServerTestCase.

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

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