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

Команда staticfiles-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- и 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, который принимает путь и выполняет urljoin с префиксом статики 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 до или в качестве части настройки ваших тестов.