Приложение 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 из STORAGES и передает ему список путей, найденных командой управления. Также ей передаются все параметры командной строки команды collectstatic. По умолчанию это используется классом ManifestStaticFilesStorage.

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

Затем укажите бэкенд хранилища staticfiles в настройке STORAGES как 'path.to.MyStaticFilesStorage'.

Часто используемые параметры:

--noinput, --no-input

НЕ запрашивать у пользователя ввод каких-либо данных.

--ignore PATTERN, -i PATTERN

Игнорировать файлы, каталоги или пути, соответствующие этому шаблону в стиле glob. Чтобы игнорировать больше объектов, используйте параметр несколько раз. При указании пути всегда используйте прямые косые черты, в том числе в Windows.

--dry-run, -n

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

--clear, -c

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

--link, -l

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

--no-post-process

Не вызывать метод post_process() настроенного бэкенда хранилища staticfiles из STORAGES.

--no-default-ignore

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

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

$ python manage.py collectstatic --help

...\> py manage.py collectstatic --help

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

...\> py 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

...\> py 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

...\> py 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

...\> py 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

...\> django-admin runserver --nostatic

--insecure

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

--insecure несовместим с ManifestStaticFilesStorage.

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

$ django-admin runserver --insecure

...\> django-admin runserver --insecure

StaticFilesStorage

class storage.StaticFilesStorage

Подкласс бэкенда хранилища FileSystemStorage, который использует настройку STATIC_ROOT в качестве базового расположения файловой системы, а настройку STATIC_URL — в качестве базового URL.

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

Если хранилище определяет этот метод, команда управления collectstatic вызывает его после каждого запуска и передает ему локальные хранилища и пути найденных файлов в виде словаря, а также параметры командной строки. Метод возвращает кортежи из трех значений: original_path, processed_path, processed. Значения путей — строки, а processed — булево значение, указывающее, была ли обработана величина после сохранения, либо исключение, если обработка после сохранения завершилась ошибкой.

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

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 и JavaScript.

Создайте подкласс ManifestStaticFilesStorage и установите атрибут support_js_module_import_aggregation в True, если хотите использовать экспериментальные регулярные выражения для охвата:

• Импорта модулей в JavaScript.
• Объединения модулей в JavaScript.

Например, файл 'css/styles.css' с таким содержимым:

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

…будет заменен вызовом метода url() бэкенда хранилища ManifestStaticFilesStorage, в результате чего будет сохранен файл 'css/styles.55e7cbb9ba48.css' со следующим содержимым:

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

Изменить расположение файла манифеста можно с помощью пользовательского подкласса ManifestStaticFilesStorage, задав аргумент manifest_storage. Например:

from django.conf import settings
from django.contrib.staticfiles.storage import (
    ManifestStaticFilesStorage,
    StaticFilesStorage,
)


class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def __init__(self, *args, **kwargs):
        manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
        super().__init__(*args, manifest_storage=manifest_storage, **kwargs)

storage.ManifestStaticFilesStorage.manifest_hash

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

storage.ManifestStaticFilesStorage.max_post_process_passes

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

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

• бэкенд хранилища staticfiles в настройке STORAGES должен иметь значение '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 в настройке STORAGES задано другое значение, например 'django.contrib.staticfiles.storage.StaticFilesStorage' (значение по умолчанию).

storage.ManifestStaticFilesStorage.file_hash(name, content=None)

Метод, используемый при создании хешированного имени файла. Он должен возвращать хеш для заданных имени и содержимого файла. По умолчанию метод вычисляет MD5-хеш фрагментов содержимого, как описано выше. Вы можете переопределить этот метод и использовать собственный алгоритм хеширования.

ManifestFilesMixin

class storage.ManifestFilesMixin

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

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

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

views.serve(request, path)

Эта функция-представление раздает статические файлы в процессе разработки.

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

from django.conf import settings
from django.contrib.staticfiles import views
from django.urls import re_path

if settings.DEBUG:
    urlpatterns += [
        re_path(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 до тестов или в рамках их настройки не требуется.