Разработка и совместимость
Понятный код
Проверки и вычисляемые значения по умолчанию задаются в явных конструкторах.
Field, ModelSchema, RecordAction и Theme используют обычные присваивания,
без post-init callbacks и изменения frozen-объектов. Dataclasses сохранены для сравнения,
представления и dataclasses.replace(). Это изменяемые объекты конфигурации: завершайте
их настройку до обработки запросов. Не изменяйте зарегистрированные метаданные во время
запросов; для замены настроек коллекции используйте Admin.configure(). Присваивание
атрибуту после создания не вызывает проверки конструктора. Эти объекты нехешируемы.
Снимки операций, identity, запросы и условия конкурентной записи имеют отдельные
контракты неизменяемости.
Для выбора транзакции и составных условий запросов используйте явные ветвления и циклы.
ORM-интроспекция и асинхронные границы нужны по контракту; отдельная абстракция ради
нескольких сэкономленных строк не нужна.
История выпусков и инструкции перехода
находятся в CHANGELOG.md; правила совместимости — в
гарантиях публичного API. Перед коммитом запускайте
python scripts/check_api.py --profile modern; GINO проверяется отдельно с --profile gino.
Обновление версии не публикует релиз.
Python
Поддерживаются CPython 3.11–3.15. CI запускает полный SQLite-набор тестов для каждой версии без continue-on-error.
Каждый пуш в любую ветку запускает полный CI, оба аудита зависимостей, сборку
документации и проверку дистрибутивов. В PR проверки выбираются по изменённым файлам;
необязательный ручной запуск CI также всегда полный.
См. выбор проверок и условия релиза.
Локально проверены Python 3.14.7 и 3.15.2. Нет отдельных гарантий для free-threaded сборок и альтернативных реализаций Python.
Матрица версий зависимостей проверяет поддерживаемые нижние
границы и новое разрешение дополнительно к lockfile. HTTP-тесты используют
httpx.ASGITransport и настоящие lifespan-контексты фреймворков в примерах. Это сохраняет
покрытие HTTP и жизненного цикла со Starlette 0.x и 1.x без разных библиотек TestClient.
Pytest считает DeprecationWarning ошибкой; предупреждения зависимостей не подавляются.
Проверка кода
uv run pytest -q
uv run ruff check src tests examples scripts
uv run ruff format --check src tests examples scripts
Интеграционные тесты проходят CRUD на SQLite для sync/async SQL reflection,
sync/async SQLAlchemy/SQLModel, Tortoise и Peewee под FastAPI и Litestar. Проверяются
CSRF, mass assignment, read-only поля, XSS, права, rollback, шаблоны, host sessions,
составные ключи, proxy prefixes, конкурентные изменения, поиск связей, фильтры
и метаданные схемы с учётом прав.
PostgreSQL 17 и MySQL 8.4 имеют отдельные контрактные CI jobs.
Обе СУБД также проверены локальными контрактными запусками.
Загрузка файлов и row-level permission API не реализованы.
История действий записывает операции админки с настраиваемым уровнем;
это не атомарный аудит всех изменений приложения. Встроенные формы атомарно обнаруживают устаревшие записи;
свои адаптеры подключают CheckedAdapter. См. настройку.
Свои страницы пока GET-only.
Reflection не восстанавливает логические типы, потерянные в схеме: UUID в SQLite
может оказаться строкой, а enum — обычным VARCHAR. Для сохранения типов используйте
ORM-адаптер. Автообнаружение требует импортированных моделей и не импортирует весь проект.
Поддержка и ограничения редактора связей описаны в разделе связей.
Документация Diplodoc
Исходный язык — английский (docs/en), перевод — русский (docs/ru). Структура страниц и toc.yaml совпадает.
Требования: Node.js 24+ и npm 11.5.1+. Из корня репозитория:
npm ci
npm run docs:build
npm run docs:serve
Сборка появляется в build/docs. Откройте localhost:8001: корневой URL ведёт в английскую версию. Русская версия доступна по /ru/. Сборка проверяет состав переводов, ссылки и предупреждения Diplodoc. CI сохраняет HTML как artifact.
Документация по умолчанию открывается в тёмной теме. В Настройки → Тёмная тема можно выбрать
тёмную или светлую; Diplodoc сохраняет выбор в сессии текущей вкладки браузера.
Обе палитры заданы в docs/theme.yaml: тёмно-серые поверхности и яркий синий акцент
в тёмной теме, светлые нейтральные поверхности и более тёмный синий для читаемых ссылок — в светлой.
Штатный темизатор также оформляет таблицы, код, примечания и навигацию по статье.
docs/_assets/script/quite-admin-theme.js задаёт начальную тему;
scripts/prepare-pages.mjs ставит его перед содержимым и скриптами вьюера, чтобы избежать светлой вспышки.
Админка и браузерное демо сохраняют собственные настройки темы.
Перед сборкой очищается build/docs, чтобы удалённые из исходников страницы не оставались на опубликованном сайте.
После изменения браузерного демо или общих скриптов запускайте npm run demo:test.
Команда пересобирает фиктивные данные и проверяет запись связей, конкурентные изменения,
условия фильтров, компоновку схемы, раскрытие промежуточных таблиц и точность контролов форм.
Отдельный workflow pages публикует артефакт quite-admin-docs из успешного полного CI
в master после релиза или обновления только документации опубликованной версии.
Для обновления документации проверенный коммит должен оставаться вершиной master,
а его полный diff от опубликованного релиза — содержать только документацию и явно
разрешённые инструменты документации. Оба пути требуют успеха CI ready и
Release ready и используют точный артефакт CI. Обновление документации не меняет
версию пакета, не переносит тег и не загружает пакет в PyPI. Триггер workflow_run
сохраняет деплой из основной ветки, разрешённой окружением github-pages.
Полные условия деплоя описаны в политике релизов.
В Settings → Pages выберите GitHub Actions как источник. Не запускайте Jekyll над корнем
репозитория или исходной папкой docs: Liquid воспринимает Jinja-примеры {% extends %}
как свои теги. Готовый artifact содержит .nojekyll и сохраняет ассеты _bundle Diplodoc.
Новые страницы добавляйте в обе языковые папки и оба toc.yaml. Меняйте примеры API синхронно. Настройки находятся в docs/.yfm, версия CLI закреплена в package-lock.json.
Обновление скриншотов интерфейса
После установки Python- и npm-зависимостей для разработки и Chromium командой
npx playwright install chromium запустите из корня репозитория:
node scripts/capture_screenshots.mjs
Скрипт заменяет все 14 общих PNG в docs/assets/screenshots/ снимками актуального
Python-примера при размере окна 1440 × 1000. Он запускает отдельный локальный сервер
на порту 8131, использует временные SQLite-базы с вымышленными записями и удаляет
их после съёмки. Подключений к уже запущенному приложению или его базе нет.
В QUITE_ADMIN_SCREENSHOT_PORT можно задать свободный порт, в QUITE_ADMIN_PYTHON —
интерпретатор вместо .venv/bin/python. Просмотрите полученные изображения,
затем запустите npm run docs:build для проверки ссылок на опубликованные файлы.
Браузер и установленный пакет
npm run browser:test собирает статическое демо, запускает временные локальные серверы
и браузерные тесты. Подготовка демо завершается до отсчёта времени готовности серверов.
В CI каждому серверу отводится до 120 секунд; в логах видны запуск и HTTP-проверки
готовности. При локальном запуске сохраняется лимит 30 секунд.
Сначала установите закреплённые браузеры: npx playwright install --with-deps.
Стенд использует только вымышленные записи во временной SQLite БД. В Linux CI
Chromium и Firefox запускаются в официальном контейнере Playwright той же версии,
что и @playwright/test, с готовыми браузерами и системными библиотеками.
Домашний каталог контейнера принадлежит пользователю процесса, чтобы Firefox мог
запуститься. WebKit работает нативно на macOS. Все браузерные задания сохраняют
скриншоты и трассы ошибок.
Python-матрица проверяет исходный checkout без сборки дистрибутивов. Отдельная job
полного CI собирает одну универсальную пару wheel/sdist, запускает строгую проверку
Twine и устанавливает оба файла в чистые окружения для проверки ресурсов и подключения
FastAPI/Litestar. Проверенная пара сохраняется как quite-admin-distributions. После
проверенного GitHub release pypi.yml скачивает эти же файлы из CI и передаёт их в
изолированную job загрузки без повторной сборки. Локально запустите uv build, затем
uvx --from 'twine>=6,<7' twine check --strict dist/* и
uv run python scripts/check_distributions.py. Метаданные пакета должны оставаться 2.4.
В GitHub остаются архивы исходников; см. публикацию.
Компоненты frontend
Интерфейс использует шаблоны Jinja, обычный JavaScript и CSS без сборки frontend.
Общая разметка находится в templates/quite_admin/_ui.html (навигация, логотип,
CSRF-поля, пустые состояния и пагинация), _controls.html (варианты выбора и
атрибуты доступности) и _fields.html (поля записи). Импортируйте макросы с
контекстом, чтобы сохранялись переводы, URL с префиксом монтирования, ограничения
полей и пользовательские шаблоны полей. Эти фрагменты внутренние; существующие
точки входа шаблонов и версия API шаблонов остаются прежними.
forms.js отвечает за улучшение полей и конструктор контролов, общий для inline-редактора
и браузерного демо. Повторная инициализация живой области сохраняет один переключатель
и JSON-редактор на нативный контрол. При удалении области вызывайте возвращённую
функцию очистки: через неё календари удаляют обработчики document/window.
datetime.js содержит общий календарь, проверку точности времени и жизненный цикл
всплывающих панелей для форм и черновиков фильтров. Не добавляйте динамические импорты
скриптов: встроенные скрипты сохраняют существующие CSP-хеши и атрибуты integrity.
После изменений frontend запускайте npm run demo:test, npm run browser:test и
интеграционные тесты Python. Браузерные проверки охватывают повторную инициализацию,
точность отправляемого JSON, удаление обработчиков, валидацию скрытых черновиков,
управление с клавиатуры и работу без JavaScript.