Приложения для работы со статическими файлами

django.contrib.staticfiles собирает статические файлы со всех ваших приложений (и остальных мест, которые вы укажите) в одном месте, что позволяет легко настроить выдачу статических файлов на боевом сервере.

См.также

Примеры использования этого приложения для работы со статикой можно найти в разделе Работа со статическими файлами (CSS, изображения). Как работать со статикой на боевом сервере описано в разделе Развертывание статических файлов.

Команды

django.contrib.staticfiles предоставляет три команды.

collectstatic

django-admin.py collectstatic

Собирает статические файлы в STATIC_ROOT.

Одинаковые имена файлов обрабатываются как и шаблоны: будет использоватся первый найденный файл. Если вы запутались, команда findstatic может показать какой конкретно файл используется.

Файлы ищутся используя бекенды из enabled finders. По умолчанию проверяются каталоги из STATICFILES_DIRS и подкаталоги 'static' приложений из INSTALLED_APPS.

Команда collectstatic вызывает метод post_process() бекенда STATICFILES_STORAGE и передает список найденных файлов. Также передаются все опции переданные при вызове collectstatic. По умолчанию используется CachedStaticFilesStorage.

Обычно используются следующие параметры:

--noinput

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

-i <pattern>
--ignore <pattern>

Игнорировать файлы и каталоги подходящие под шаблон. Используйте несколько раз, если необходимо передать несколько шаблонов.

-n
--dry-run

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

-c
--clear

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

-l

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

--no-post-process

Не вызывать метод post_process() указанного в STATICFILES_STORAGE бекенда для работы с файлами.

--no-default-ignore

Не игнорировать файлы 'CVS', '.*' and ``*~’``(по умолчанию игнорируются).

Полный список параметров можно посмотреть выполнив:

$ python manage.py collectstatic --help

findstatic

django-admin.py 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

runserver

django-admin.py runserver

Переопределяет встроенную команду runserver, если приложение staticfiles добавлено в installed, которая автоматом добавляет раздачу статических файлов.

--nostatic

Используйте --nostatic чтобы отключить раздачу статических файлов через staticfiles. Опция доступна только если приложение staticfiles добавлено в INSTALLED_APPS.

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

django-admin.py runserver --nostatic
--insecure

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

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

django-admin.py runserver --insecure

Бекенды

StaticFilesStorage

class storage.StaticFilesStorage

Наследуется от FileSystemStorage, используйте STATIC_ROOT как расположение файлов и STATIC_URL как основной URL.

post_process(paths, **options)

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

CachedStaticFilesStorage использует этот метод, чтобы подменить путя на хешированную версию и соответственно обновить кеш при необходимости.

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage

Подкласс StaticFilesStorage, который кеширует файлы добавляя MD5 хеш содержимого файла к его названию. Например, файл css/styles.css будет сохранен как css/styles.55e7cbb9ba48.css.

Этот бекенд необходим, чтобы раздавать старые версии файлов, если они все еще используются некоторыми страницами, например, если страницы кешированы вами или прокси-сервером. Также, это полезно при большом значении заголовка Expires для статических файлов, чтобы ускорить загрузку страниц.

Бекенд автоматом заменяет путя найденые в статических файлах, которые указывают на другие статические файлы, на кешированные версии (используя метод post_process()). Регулряки, которые использутся для этого (django.contrib.staticfiles.storage.CachedStaticFilesStorage.cached_patterns), по умолчанию заменяют @import и url() в Cascading Style Sheets. Например, 'css/styles.css' содержащий

@import url("../admin/css/base.css");

будет сохранен как 'css/styles.55e7cbb9ba48.css' содержащий:

@import url("../admin/css/base.27e20196a850.css");

Чтобы включить CachedStaticFilesStorage необходимо выполнить следующие действия:

  • указать в STATICFILES_STORAGE 'django.contrib.staticfiles.storage.CachedStaticFilesStorage'

  • установить DEBUG в False

  • используйте шаблонный тег staticfiles static при обращении к статическим файлам

  • вы собрали статические файлы командой collectstatic

Т.к. вычисление MD5 хеша может понизить производительность приложения, staticfiles пытается автоматом закешировать хеши используя кеширование Django. Если вы хотите переопределить параметры кеширования, просто создайте настройки в CACHES с названием 'staticfiles'. По умолчанию используются настройки кеша 'default'.

file_hash(name, content=None)
New in Django 1.5.

Метод, который вычисляет хеш для файла. По умолчанию вычисляет MD5 хеш содержимого файла.

Шаблонные теги

static

Использует бекенд указанный в STATICFILES_STORAGE для создания полного URL-а для переданного относительного пути, например:

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

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

New in Django 1.5.

Если вы хотите получить URL не выводя его, используйте следующий код:

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

Дополнительные фукнции

Есть дополнительные функции вне staticfiles для работы со статическими файлами:

Представления для разработки

Инстументы для работой со статикой предназначены для простого развертывания на боевом сервере. Обычно это выделенный сервер, которые не практично использовать при разработке. По этому приложение staticfiles содержит простые представления для раздачи статики dev-сервером.

views.serve(request, path)

Представление, которое раздает статические файлы при разработке.

Предупреждение

Работает только при DEBUG равном True.

Потому что представление крайне неэффективно и возможно небезопасно. Оно предназначено для разработки и никогда не должно использоваться на боевом сервере.

Примечание

Для определения “content type” файлов, представление использует стандартный модуль Python mimetypes, который в свою очередь использует системную библиотеку типов файлов. Если представление использует не правильный “content type” файлов, скорее всего вам необходимо обновить системную библиотеку. Для Red Hat, например, это пакет mailcap, или mime-support для Debian пакетов.

Это представление автоматически используется командой runserver (при DEBUG равном True). Чтобы использовать его с другим dev-сервером, добавьте следующий код в настройки URL-ов:

from django.conf import settings

if settings.DEBUG:
    urlpatterns += patterns('django.contrib.staticfiles.views',
        url(r'^static/(?P<path>.*)$', 'serve'),
    )

Обратите внимание, что начало URL-шаблона (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 мог найти статические файлы.

Предупреждение

Эта функция работает только при DEBUG равном True, настройка STATIC_URL не может быть пустой или полным URL-ом, таким как http://static.example.com/.

Потому что представление крайне неэффективно и возможно небезопасно. Оно предназначено для разработки и никогда не должно использоваться на боевом сервере.