Приложение 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 перед или в качестве части вашей настройки тестов.