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

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

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 перед или в качестве части настройки ваших тестов.