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

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

--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, и добавляет автоматическое предоставление статических файлов. Обслуживание файлов происходит без участия MIDDLEWARE.

Команда добавляет следующие опции:

--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");

storage.ManifestStaticFilesStorage.max_post_process_passes

Так как статические файлы могут ссылаться на другие статические файлы, которые необходимо заменить, может потребоваться несколько проходов замены путей, пока хеши файлов не сойдутся. Чтобы предотвратить бесконечный цикл из-за несовпадения хешей (например, если 'foo.css' ссылается на 'bar.css', который ссылается на 'foo.css') существует максимальное число проходов, после которого дальнейшая обработка прекращается. В случаях с большим количеством ссылок может потребоваться большее количество проходов. Увеличьте максимальное количество проходов, наследуя класс ManifestStaticFilesStorage и задав атрибут max_post_process_passes. По умолчанию значение равно 5.

Для включения ManifestStaticFilesStorage необходимо выполнить следующие требования:

• настройка STATICFILES_STORAGE должна быть установлена в значение 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
• настройка DEBUG должна быть установлена в значение False
• все статические файлы должны быть собраны с помощью команды управления collectstatic

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

storage.ManifestStaticFilesStorage.manifest_strict

Если файл не найден в манифесте staticfiles.json во время выполнения, генерируется исключение ValueError. Это поведение можно отключить, унаследовав от класса ManifestStaticFilesStorage и установив атрибут manifest_strict в значение False — несуществующие пути останутся без изменений.

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