Приложение 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.

--dry-run, -n

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

--clear, -c

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

--link, -l

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

--no-post-process

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

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

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

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

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