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

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.

По умолчанию, созданные файлы получают права доступа из 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(CustomStaticFilesStorage, self).__init__(*args, **kwargs)

Теперь поменяйте настройку STATICFILES_STORAGE на 'path.to.MyStaticFilesStorage'.

Добавлено в Django 1.7:

Возможность переопределить file_permissions_mode и directory_permissions_mode была добавлена в Django 1.7. Раньше всегда использовались права доступа из настроек FILE_UPLOAD_PERMISSIONS и FILE_UPLOAD_DIRECTORY_PERMISSIONS.

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

--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

Установив же --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
Добавлено в Django 1.7:

Был добавлен вывод каталогов, в которых выполняется поиск.

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.

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

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

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

ManifestStaticFilesStorage

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

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

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

Т.к. вычисление MD5 хеша может понизить производительность приложения, staticfiles автоматически сохраняет соответствия названий файлов с новыми в файле ``staticfiles.json`. Это выполняется один раз при вызове команды collectstatic.

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

Был добавлен атрибут searched_locations.

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

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

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

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

views.serve(request, path)

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

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

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

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

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

Это представление теперь вызывает исключение Http404 вместо ImproperlyConfigured, если DEBUG равна False.

Примечание

Для определения “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/.

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

Специальный test case для “живого тестирования”

class testing.StaticLiveServerTestCase

Этот unittest TestCase является дочерним классом django.test.LiveServerTestCase.

Как и родительский класс, позволяет писать тесты с использованием Selenium, PhantomJS, и др., для которых необходим доступ к статическим файлам.

Для раздачи статики использует django.contrib.staticfiles.views.serve(). По этому вам не нужно выполнять collectstatic перед запуском тестов.

Добавлено в Django 1.7:

StaticLiveServerTestCase добавлен в Django 1.7. Раньше этот функционал был в django.test.LiveServerTestCase.