Django и статические файлы

Исходник со статическими файлами

В исходнике на языке Python реализованы примеры обслуживания статических файлов приложения electronics и статических файлов общих для проекта Django. Статические файлы – это общее определение для файлов, которые хранятся и загружаются без изменения при работе веб-приложения: css, javascript, изображения, текстовые, двоичные. В качестве начального исходного кода взято приложение со страницы Административная панель Django для веб-приложений.

В формировании внешнего вида описываемого веб-приложения участвуют статические файлы, принадлежащие приложению electronics и файлы библиотеки bootstrap в отдельном каталоге проекта. CSS файл приложения содержит стили текста ссылок на веб-страницах. Общие стили и javascript по пути STATICFILES_DIRS библиотеки bootstrap создают внешний вид всего сайта, не привязаны никакому приложению, но могут использоваться любым приложением входящим в состав проекта Django.

При работе с исходником в Visual Studio можно тестировать обработку статических файлов в отладочном и производственном режимах проекта Python Django. Для обслуживания статических файлов в производственном режиме используется параметр запуска сервера runserver --insecure.

Добавление в веб-приложение стилей CSS

Статические файлы для конкретного приложения Django (например: css, js, img) добавляются в подкаталог приложения по пути:
название_приложения/static/название_приложения/
в данном исходном коде: electronics/static/electronics/
Папки static/electronics/ создаются вручную в среде Visual Studio или в проводнике Windows, находясь в каталоге приложения.

Повторение папки с названием приложения требует специфика работы фреймворка Django. Дело в том, что поиск статических файлов зарегистрированных в проекте приложений происходит относительно их каталогов static/, и без дополнительных папок с уникальным названием возникнет высокая вероятность конфликта имен статических файлов. Кроме того, при публикации проекта, когда все статические файлы собираются в папке, установленной в константе STATIC_ROOT, папка с названием приложения позволит быстро определять принадлежность файлов конкретному приложению.

Установка bootstrap в проект Django

Для установки интерфейса bootstrap в корневом каталоге проекта Django создадим папку assets, в этой папке будут находиться эталонные файлы bootstrap, которые при развертывании проекта будут копироваться в глобальную папку статических файлов проекта.

Bootstrap можно установить или добавить в проект Django несколькими способами: прямым скачиванием с официального сайта в соответствующую папку или с помощью сервиса Visual Studio. Очень удобная установка из Обозревателя решений Visual Studio:
из контекстного меню названия созданной папки assets вызвать пункт Добавить->Клиентская библиотека… В открывшемся окне выбрать:
Поставщик->unpkg
Библиотека->Bootstrap5.3.1 (на другой момент времени для вас последняя версия может отличаться).
Для нашего примера достаточно выбрать два файла: bootstrap.min.css и bootstrap.bundle.min.js. После нажатия кнопки Установить выбранные файлы скопируются в assets.

Константы конфигурации проекта settings.py

Для работы со статическими файлами необходимо определить некоторые константы в модуле конфигурации проекта settings.py. Данные константы закрепляют координаты доступа и расположения для всех статических файлов проекта Django.

STATIC_URL – константа участвует в формировании URL для доступа к статическому файлу. Данная константа обычно определяется автоматически при создании проекта Django.
STATIC_ROOT – константа хранит абсолютный путь до папки хранения статических файлов при работе сайта в производственном режиме.
STATICFILES_DIRS – константный список определяет пути размещения дополнительных статических файлов, не привязанных к приложениям, которые при развертывании проекта копируются в папку STATIC_ROOT.

. . .
# Static files (CSS, JavaScript, Images)

STATIC_URL = 'static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
STATICFILES_DIRS = [
    BASE_DIR / "assets/",
]
. . .

URL статических файлов в HTML

Безусловно, чтобы статические файлы загружались в браузере, в HTML шаблонах должны быть ссылки на них. В приложении electronics стили css и скрипты js подключаются на мастер-странице layout.html и используются всеми дочерними страницами приложения.

Перед вставкой ссылок на статические файлы, вверху веб-страницы прописывается директива генерации строки URL указанного в константе STATIC_URL:
{% load static %}
Далее, в необходимых местах, можно создавать ссылки используя шаблон, например:
<link rel="stylesheet" type="text/css" href="{% static 'electronics/css/style.css' %}">

Директива static работает по-разному в отладочном и производственном режимах, и это необходимо учитывать, работая с фреймворком Django:
- при установленной константе модуля setting.py DEBUG = True, директива возвращает путь до статических файлов в папках static приложений и в папках, прописанных в списке STATICFILES_DIRS.
- в производственном режиме, при DEBUG = False директива возвращает путь до статических файлов, собранных в папке проекта по пути, установленном в константе STATIC_ROOT.

{# Загрузка абсолютного пути до папки static #}
{% load static %}
<!DOCTYPE html>
<html lang="ru-ru" 
    style="position: relative; min-height: 100%;">
<head>
    <meta charset="utf-8" />
    <title>{{ title }}</title>

    {# Загрузка стилей относительно папки static #}
    <link rel="stylesheet" type="text/css" 
        href="{% static 'bootstrap/dist/css/bootstrap.min.css' %}">
    <link rel="stylesheet" type="text/css" 
        href="{% static 'electronics/css/style.css' %}">
</head>
<body style="padding:0;margin:0;margin-bottom:50px;">
    {% include 'electronics/shared/partial/menu.html' %}
    <div class="container">
        <div class="pt-5">
            {% block content %}{% endblock %}
        </div>
    </div>
    {% include 'electronics/shared/partial/footer.html' %}

    {# Загрузка js скриптов относительно папки static #}
    <script src="{% static 'bootstrap/dist/js/bootstrap.bundle.min.js' %}"></script>
</body>
</html>

Запуск проекта Django в Visual Studio

После настроек необходимых для загрузки статических файлов протестировать запуск проекта Django в Visual Studio. Для работы веб-приложения со стилями необходимо включить отладочный режим в модуле проекта settings.py, т. е. DEBUG = True. В этом режиме статические файлы обслуживаются собственным сервером Django, предназначенным (по крайней мере, на данный момент) только для целей разработки приложений.

Insecure для тестирования статических файлов в производственном режиме

Стили четко работают и интерфейсный вид приложения значительно обновился в лучшую сторону. Но стоит только перевести работу проекта на производственный режим, установив DEBUG = False и веб-страницы возвращаются к виду без стилей, Django перестает «видеть» static файлы. Это нормально, никакой ошибки здесь нет, и связано с особенностями функционирования фреймворка.

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

Но все же по завершении разработки веб-приложения, в целях заключительного тестирования бывает необходимо протестировать производственный режим непосредственно в среде разработки. Для таких целей разработчики Django предоставляют специальный параметр запуска отладочного сервера --insecure и команда запуска сервера выглядит так:
runserver --insecure
В этом случае отладочный сервер будет принудительно обслуживать статические файлы, читая их из папок приложений и путей STATICFILES_DIRS, как и в отладочном режиме.

Включить такой режим в Visual Studio можно в свойствах проекта, на вкладке Отладка в разделе Команда сервера отладки, смотрите скриншот ниже. Включая параметр insecure необходимо помнить предупреждение разработчиков Django:
«это крайне неэффективно и, вероятно, небезопасно. Это предназначено только для локальной разработки и никогда не должно использоваться в производстве...»

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

Перед публикацией проекта на внешний сервер необходимо собрать статические файлы в одну папку, указанную константой STATIC_ROOT модуля settings.py. Для этого необходимо вызвать командную строку в Обозревателе решений Visual Studio из контекстного меню названия проекта пунктом Открыть командную строку здесь… Команда сбора статических файлов:
python manage.py collectstatic - команда собирает статические файлы всех приложений, зарегистрированных в проекте Django в папку по пути, определенному вышеуказанной константой. Данную команду можно использовать и на внешнем хосте, предварительно активировав виртуальную среду.

После процедуры сбора статические файлы будут доступны производственному серверу, обслуживающему веб-проект Django.

Основные выводы при работе со статическими файлами в Django

• Django обрабатывает статические файлы своим сервером отладки только в режиме разработки.
• Настоятельно рекомендуется хранить оригиналы статических файлов в отдельных каталогах и для обслуживания производственным сервером собирать их в местоположении указанном в STATIC_ROOT.
• В производственном режиме статические файлы обслуживаются из специального каталога STATIC_ROOT.

Исходник примера работы со статическими файлами в Python Django

Все что упущено в описании дополнит практический пример исходного кода веб-приложения Django для работы со статическими файлами. Исходник на языке Python написан в среде Visual Studio 2022.

Файл архива включает полный код проекта Django с веб-приложением electronics в комплекте с виртуальной средой и базой данных MySQL. После небольшой настройки исходник готов к работе.

Требуемая версия базового интерпретатора Python от 3.8 до последних 3.9. Нижнюю версию определяет фреймворк Django, верхнюю версию интерпретатора определяет пакет mysqlclient (на момент написания статьи не выпущена версия для Python 3.10 и выше).

home = G:\MyProjects\Programming\Pythons\Python39_4
include-system-site-packages = false
version = 3.9.4

Перед началом работ с приложением создайте базу данных MySQL «shop_electronics», заполните данными из sql-файла приложенному к архиву и пропишите реквизиты доступа к базе данных в модуле settings.py.