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

Не запрашивать ввод от пользователя.

Изменено в Django 1.9:

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

Настройка списка игнорируемых шаблонов

Список игнорируемых шаблонов по умолчанию, ['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

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() таблиц стилей Cascading Style Sheets. Например, файл '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
• вы собрали все статические файлы, используя команду управления 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'.

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

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

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