Приложение 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, рекомендуется использовать параметр --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

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

-i <pattern>

--ignore <pattern>

Игнорировать файлы или каталоги, соответствующие шаблону в стиле glob. Можно использовать несколько раз для игнорирования большего количества.

-n

--dry-run

Выполнить все действия, кроме изменения файловой системы.

-c

--clear

Очистить существующие файлы перед попыткой копирования или создания ссылки на исходный файл.

-l

--link

Создать символическую ссылку на каждый файл вместо копирования.

--no-post-process

Не вызывать метод post_process() подключенного хранилища STATICFILES_STORAGE.

--no-default-ignore

Не игнорировать общие шаблоны частных файлов в стиле glob 'CVS', '.*' и '*~'.

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

$ python manage.py collectstatic --help

findstatic

django-admin findstatic

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

Например:

$ 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

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

Переопределяет базовую команду 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, который представляет собой список путей к каталогам, в которых производился поиск finders. Пример использования:

from django.contrib.staticfiles import finders

result = finders.find('css/base.css')
searched_locations = finders.searched_locations

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