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

Не игнорировать общие шаблоны в стиле 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() в каскадных таблицах стилей.
• Комментарий карты источников в 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.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 расширяет django.test.LiveServerTestCase.

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

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