Приложение 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 после каждого запуска и получает локальные хранилища и пути к найденным файлам в виде словаря, а также параметры командной строки. Он возвращает кортежи из трёх значений: original_path, processed_path, processed. Пути — строки, а processed — булево значение, указывающее, был ли результат послеобработки, или исключение, если послеобработка завершилась ошибкой.

Класс 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'.

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

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

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

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