Приложение 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(MyStaticFilesStorage, self).__init__(*args, **kwargs)

Затем установите настройку STATICFILES_STORAGE на 'path.to.MyStaticFilesStorage'.

Некоторые часто используемые параметры:

--noinput, --no-input

НЕ запрашивать у пользователя ввод любого типа.

Добавлен псевдоним --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

findstatic

django-admin findstatic static file [static file ...]

Ищет один или несколько относительных путей с включенными средствами поиска.

Например:

$ 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, и добавляет автоматическое обслуживание статических файлов и следующие новые параметры.

--nostatic

Используйте параметр --nostatic для отключения обслуживания статических файлов с помощью приложения staticfiles полностью. Этот параметр доступен только в том случае, если приложение staticfiles присутствует в настройке INSTALLED_APPS вашего проекта.

Пример использования:

django-admin runserver --nostatic

--insecure

Используйте параметр --insecure для принудительного включения обслуживания статических файлов с приложением staticfiles, даже если настройка DEBUG имеет значение False. Используя этот параметр, вы подтверждаете, что это крайне неэффективно и, скорее всего, небезопасно. Это предназначено только для локального развития, никогда не должно использоваться в производстве и доступно только в том случае, если приложение staticfiles указано в настройке INSTALLED_APPS вашего проекта. runserver --insecure не работает с CachedStaticFilesStorage.

Пример использования:

django-admin runserver --insecure

Хранилища

StaticFilesStorage

class storage.StaticFilesStorage

Подкласс хранилища FileSystemStorage, который использует настройку STATIC_ROOT в качестве базового расположения файловой системы и настройку STATIC_URL соответственно в качестве базового URL.

storage.StaticFilesStorage.post_process(paths, **options)

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

Класс 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");

Для включения ManifestStaticFilesStorage необходимо убедиться, что выполнены следующие требования:

• настройка STATICFILES_STORAGE установлена в 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
• настройка DEBUG установлена в False
• вы используете тег шаблона staticfiles static для ссылки на статические файлы в ваших шаблонах
• вы собрали все статические файлы, используя команду управления collectstatic

Поскольку вычисление MD5-хеша может быть ресурсоёмким процессом для вашего веб-сайта во время выполнения, staticfiles автоматически сохранит отображение с хэшированными именами всех обработанных файлов в файле staticfiles.json. Это происходит один раз при выполнении команды управления collectstatic.

Ввиду необходимости выполнения 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'.

Теги шаблонов

static

Использует настроенное хранилище STATICFILES_STORAGE для создания полного URL для данного относительного пути, например:

{% load static from staticfiles %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />

Предыдущий пример эквивалентен вызову метода url экземпляра STATICFILES_STORAGE со значением "images/hi.jpg". Это особенно полезно при использовании хранилища, не расположенного локально, для развёртывания файлов, как описано в Развёртывание статических файлов с облачного сервиса или CDN.

Если вы хотите получить URL статического файла без его отображения, можно использовать немного другой вызов:

{% load static from staticfiles %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}" alt="Hi!" />

Модуль поиска

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.
• Встроенный тег шаблона 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

if settings.DEBUG:
    urlpatterns += [
        url(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 до или как часть настройки ваших тестов.