dbwebform — документация

dbwebform — это пакет для быстрого создания веб-форм на основе моделей базы данных с использованием Flask, SQLAlchemy и WTForms. Пакет предоставляет готовый класс App, который автоматизирует настройку приложения, работу с базой данных и отображение форм.

---

Установка

pip install dbwebform

Быстрый старт

1. Создание модели и формы

Используйте db-model-generator для автоматической генерации модели и формы:

# Рекомендуемые параметры db-model-generator
db-model-generator sqlite:///example.db users orm.py https://magilyasdoma.github.io/dbwebform/recommended-config.json -a

2. Создание приложения

from dbwebform import App
from orm import Model, Form, db


app = App(
    __name__,
    db=db,
    model_class=Model,
    form_class=Form,
    title="Регистрация пользователя",
    notification_text="Пользователь успешно создан",
    port=5000
)

if __name__ == "__main__":
    app.run(debug=True)

---

Конфигурация класса App

Параметры конструктора:

Параметр	Тип	По умолчанию	Описание
db	SQLAlchemy	—	Экземпляр SQLAlchemy для работы с БД
model_class	db.Model	—	Класс модели SQLAlchemy
form_class	FlaskForm	—	Класс формы WTForms
port	int	8000	Порт для запуска сервера
database_url	str	'sqlite:///db.sqlite3'	URL подключения к БД
title	str	"Создание нового объекта"	Заголовок страницы
notification_text	str	"Объект создан"	Текст уведомления после отправки формы
index_template	str	'dbwebform/index.html'	Путь к шаблону формы
model_fields	Iterable[str]	None	Список полей модели для сохранения (если None — сохраняются все)

---

Структура пакета

dbwebform/
├── __init__.py
├── app.py
├── templates/
│   ├── dbwebform/
│   │   ├── base.html
│   │   └── index.html
└── favicon.ico

---

Шаблоны

base.html

Базовый шаблон с подключением:

• Bootstrap 5

• hrenpack-theme-style

• Темная/светлая тема

• Иконка базы данных

index.html

Шаблон формы. Наследуется от base.html. Может быть переопределён через параметр index_template.

Блоки для расширения:

• {% block index_pre_content %} — контент перед формой

• {% block index_post_content %} — контент после формы

• {% block index_scripts %} — дополнительные скрипты

---

Методы класса App

_init_db(database_url: str)

Инициализирует базу данных, создаёт все таблицы.

_get_form_model_data(form) -> dict

Фильтрует данные формы для сохранения в модель (если задан model_fields).

_create_new_object(form)

Создаёт и сохраняет новый объект в БД.

index()

Обрабатывает GET/POST запросы, отображает форму и сохраняет данные.

favicon()

Возвращает иконку для сайта.

---

Пример кастомизации шаблона

<!-- my_custom_index.html -->
{% extends 'dbwebform/base.html' %}

{% block index_pre_content %}
    <div class="alert alert-info">
        Заполните все поля формы ниже.
    </div>
{% endblock %}

{% block index_scripts %}
    <script>
        console.log("Форма загружена!");
    </script>
{% endblock %}

---

Запуск приложения

app = App(
    __name__,
    db=db,
    model_class=MyModel,
    form_class=MyForm,
    port=8080
)

app.run(debug=True, host="0.0.0.0")

Зависимости

Пакет требует установки следующих зависимостей:

flask~=3.1.1
sqlalchemy==2.0.44
flask-sqlalchemy==3.1.1
flask-wtf==1.2.2
wtforms==3.2.1
db-model-generator>=1.5.1, <=2.0.0
hrenpack>=2.2.2, <=3.0.0

Пакет	Версия	Назначение
flask	~=3.1.1	Веб-фреймворк для создания приложения
sqlalchemy	==2.0.44	ORM для работы с базой данных
flask-sqlalchemy	==3.1.1	Интеграция SQLAlchemy с Flask
flask-wtf	==1.2.2	Интеграция WTForms с Flask
wtforms	==3.2.1	Создание и валидация веб-форм
db-model-generator	==1.4.2	Автогенерация моделей и форм из схемы БД
hrenpack	>=2.2.2, <=3.0.0	Набор утилит, стилей и компонентов для фронтенда

Все зависимости устанавливаются автоматически при установке пакета через pip.

Лицензия

Распространяется под лицензией MIT. Полный текст лицензии доступен в файле LICENSE или по ссылке: MIT License

Поддержка и вклад

Для предложений и сообщений об ошибках создавайте issue в репозитории проекта. Pull-requests приветствуются.