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

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

См.также

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

Настройки

Примечание

Следующие настройки определяют работу приложения ’’staticfiles’’.

STATICFILES_DIRS

По умолчанию: []

Указывает каталоги, в которых бекенд FileSystemFinder будет искать статические файлы, например, при запуске команды collectstatic или findstatic или при раздачи файлов через встроенные представления.

Это должен быть список или кортеж строк, которые содержат полный путь к каталогу с файлоами, например:

STATICFILES_DIRS = (
    "/home/special.polls.com/polls/static",
    "/home/polls.com/polls/static",
    "/opt/webfiles/common",
)

Префиксы (необязательны)

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

STATICFILES_DIRS = (
    # ...
    ("downloads", "/opt/webfiles/stats"),
)

Например:

Предположим STATIC_URL содержим '/static/', команда collectstatic соберет файлы из “stats” в подкаталоге 'downloads' каталога STATIC_ROOT.

Это позволить обращаться к файлу '/opt/webfiles/stats/polls_20101022.tar.gz' по URL-у '/static/downloads/polls_20101022.tar.gz' в вашем шаблоне, например:

<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">

STATICFILES_STORAGE

По умолчанию: 'django.contrib.staticfiles.storage.StaticFilesStorage'

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

Добавлено в Django 1.4.

Примеры бекендов можно найти в django.contrib.staticfiles.storage.staticfiles_storage.

Например, Раздача статических файлов через облачный сервис или CDN.

STATICFILES_FINDERS

По умолчанию:

("django.contrib.staticfiles.finders.FileSystemFinder",
 "django.contrib.staticfiles.finders.AppDirectoriesFinder")

Список бекендов для поиска статических файлов в вашем проекте.

По умолчанию включены бекенды, которые находят файлы в каталогах указанных в STATICFILES_DIRS (django.contrib.staticfiles.finders.FileSystemFinder) и подкаталогах static приложений (django.contrib.staticfiles.finders.AppDirectoriesFinder). Если существует несколько файлов с тем же именем, будет использоваться первый найденный.

django.contrib.staticfiles.finders.DefaultStorageFinder выключен по умолчанию. Если добавить его STATICFILES_FINDERS, он будет искать файлы через бекенд указанный в DEFAULT_FILE_STORAGE.

Примечание

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

Бекенды для поиска файлов пока что не являются публичным интерфейсом, по этому он не задокументирован.

Команды

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

collectstatic

django-admin.py collectstatic

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

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

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

Добавлено в Django 1.4.

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

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

--noinput

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

-i <pattern>
--ignore <pattern>

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

-n
--dry-run

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

-c
--clear
Добавлено в Django 1.4.

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

-l

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

--no-post-process
Добавлено в Django 1.4.

Не вызывать метод 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
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css
/home/polls.com/src/django/contrib/admin/media/js/core.js

По умолчанию, выводятся все найденные файлы. Чтобы вернуть только первый найденный файлы, используйте параметрт --first:

$ python manage.py findstatic css/base.css --first
/home/special.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.

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

django-admin.py runserver --insecure

Бекенды

StaticFilesStorage

class storage.StaticFilesStorage

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

post_process(paths, **options)
Добавлено в Django 1.4.

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

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

CachedStaticFilesStorage

class storage.CachedStaticFilesStorage
Добавлено в Django 1.4.

Подкласс 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)
Добавлено в Django 1.5.

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

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

static

Добавлено в Django 1.4.

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

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

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

Добавлено в 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.

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

Это представление автоматически используется командой 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/.

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