A Django static site generator
Project description
Django StaticEngine - Документация
Обзор
Django StaticEngine — это Django-приложение для обслуживания статических файлов и директорий с поддержкой шаблонов Django. Оно позволяет превратить любую папку с HTML-файлами в полнофункциональный статический сайт с обработкой Django-шаблонов.
Установка
pip install django-static-engine
Быстрый старт
1. Добавьте 'staticsite' в INSTALLED_APPS:
INSTALLED_APPS = [
...,
'staticsite.apps.StaticSiteConfig',
]
2. Настройте базовую директорию в settings.py:
STATICSITE_DIR = BASE_DIR / 'src' # или любой другой путь
3. Добавьте URL-конфигурацию в ваш urls.py:
from django.conf import settings
from django.urls import path, include
from staticsite.views import view_constructor
urlpatterns = [
# ... другие URL ...
path('site/', include('staticsite.urls')),
]
# Или создайте собственное представление
urlpatterns = [
path('src/<path:path>', view_constructor('src'), name='src')
]
4. Создайте структуру файлов:
src/
├── static_content/
│ ├── index.html
│ ├── about.html
│ ├── styles.css
│ └── images/
│ └── logo.png
Конфигурация
from pathlib import Path
# settings.py
# Обязательная настройка
BASE_DIR = Path(__file__).parent.parent
# Включить шаблон для отображения директорий
STATICSITE_USE_DIR_TEMPLATE = True # По умолчанию: False
# Путь к директории с исходными файлами (если отличается от BASE_DIR/src)
STATIC_SITE_DIR = BASE_DIR / 'my_static_files'
Использование
Базовая структура URL
После установки приложение обслуживает файлы по следующим URL:
http://localhost:8000/site/- корневая директорияhttp://localhost:8000/site/path/to/file.html- конкретный файлhttp://localhost:8000/site/directory/- директория (если включен шаблон)
Поддерживаемые типы файлов
Приложение автоматически определяет MIME-типы для:
- HTML файлы (
.html,.htm) - обрабатываются как Django-шаблоны - JSON файлы (
.json) - возвращаются как JSON-ответы - CSS/JavaScript (
.css,.js) - обслуживаются как статические файлы - Изображения (
.png,.jpg,.gif, etc.) - PDF документы (
.pdf) - Текстовые файлы (
.txt,.xml) - Другие бинарные файлы - обслуживаются с соответствующими MIME-типами
Особенности работы
HTML-файлы как шаблоны
HTML-файлы обрабатываются движком шаблонов Django, что позволяет использовать:
- Теги шаблонов ({% tag %})
- Переменные ({{ variable }})
- Наследование шаблонов
- Встроенные фильтры
Пример index.html:
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Мой сайт{% endblock %}</title>
</head>
<body>
<h1>Добро пожаловать</h1>
<p>Текущее время: {{ now|date:"H:i" }}</p>
</body>
</html>
JSON-файлы
JSON-файлы автоматически парсятся и возвращаются как JSON-ответы API.
Отображение директорий
При включении STATICSITE_USE_DIR_TEMPLATE = True, приложение будет отображать содержимое директорий в виде таблицы с информацией о файлах:
- Имя файла
- Размер (в удобном формате: b, Kb, Mb, etc.)
- Дата последнего изменения
Безопасность
Приложение включает следующие меры безопасности:
- Проверка пути: Предотвращает доступ к файлам вне базовой директории
- Скрытые файлы: Игнорирует файлы, начинающиеся с точки (.)
- Нормализация путей: Защита от path traversal атак
Кастомизация
Шаблон для директорий
Вы можете создать собственный шаблон для отображения директорий. Создайте файл __directory__.html в директории шаблонов вашего проекта:
<!DOCTYPE html>
<html>
<head>
<title>Содержимое: {{ path }}</title>
</head>
<body>
<h1>Содержимое директории: {{ path }}</h1>
<table>
<tr>
<th>Имя</th>
<th>Размер</th>
<th>Дата изменения</th>
</tr>
{% for file in files %}
<tr>
<td><a href="{{ file.name }}">{{ file.name }}</a></td>
<td>{{ file.size }}</td>
<td>{{ file.date }}</td>
</tr>
{% endfor %}
</table>
</body>
</html>
Примеры использования
Служение статического сайта
# urls.py проекта
from django.urls import path, include
from django.conf import settings
urlpatterns = [
path('', include('staticsite.urls')), # Корневой URL
]
Мультисайтовость
# urls.py проекта
from django.urls import path
from django.conf import settings
from staticsite.views import view_constructor
import os
urlpatterns = [
path('site1/', view_constructor(os.path.join(settings.BASE_DIR, 'sites/site1'))),
path('site2/', view_constructor(os.path.join(settings.BASE_DIR, 'sites/site2'))),
]
API-эндпоинты из JSON
Создайте файл api/data.json:
{
"users": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"}
]
}
Доступно по адресу: http://localhost:8000/site/api/data.json
Ограничения
- Не предназначен для замены Django Static Files в production
- Не поддерживает кэширование (используйте nginx или CDN для production)
- Не рекомендуется для больших файлов (>100MB)
- Все HTML-файлы обрабатываются через движок шаблонов Django, что может замедлить работу при большой нагрузке
Производительность
Для production-окружения рекомендуется:
- Использовать веб-сервер (nginx, Apache) для обслуживания статических файлов
- Настроить кэширование
- Использовать CDN для медиа-файлов
Отладка
При возникновении проблем проверьте:
- Правильность пути к базовой директории
- Разрешения на чтение файлов
- Корректность MIME-типов для нестандартных файлов
- Кодировку HTML-файлов (поддерживаются UTF-8 и cp1251)
Лицензия
MIT License
Поддержка
Для отчетов об ошибках и предложений используйте issue tracker на GitHub репозитории проекта.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_static_engine-0.1.8.tar.gz.
File metadata
- Download URL: django_static_engine-0.1.8.tar.gz
- Upload date:
- Size: 8.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2cdf0a51c94ab60bd676aa3ccffb57c61e4da09040f81d7d424d46366015cd61
|
|
| MD5 |
d44b94f8e1d191782062d4ea0a97268b
|
|
| BLAKE2b-256 |
9d3b36e31877de7d4a228c0072b6824c34871361a37045c13a19290965e0f040
|
File details
Details for the file django_static_engine-0.1.8-py3-none-any.whl.
File metadata
- Download URL: django_static_engine-0.1.8-py3-none-any.whl
- Upload date:
- Size: 9.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
be4a44afdd4958132e53c05bc04e43fb97e87b1fb1cbcca421527f19446fc22a
|
|
| MD5 |
182469f41ba856834e15a0b1a846fe22
|
|
| BLAKE2b-256 |
bec10c23046aa61bcb29316fad532d112ea1f2cb2e8f8c93862bf19eee00b110
|
