Гарантии публичного API
PATCH-релизы сохраняют описанные импорты,
сигнатуры, значения по умолчанию и поведение. Контракт адаптера —
ADAPTER_API_VERSION = 1, контракт шаблонов — TEMPLATE_API_VERSION = 1.
Гарантии действуют для SQL reflection, нативных ORM- и сервисных адаптеров.
Для экспорта CSV/XLSX ORM не требуется.
Что входит в контракт
| Интерфейс | Гарантированная поверхность |
|---|---|
| Python-импорты | Имена из quite_admin.__all__, __version__, Adapter из quite_admin.adapters.base, публичные ошибки из quite_admin.errors, StaleRecord из quite_admin.concurrency |
| Интеграция | Конструктор Admin, ASGI-вызов, регистрация и настройка таблиц и страниц, подключение FastAPI/Litestar и методы перевода |
| Конфигурация и данные | Аргументы, defaults и описанные методы Field, ModelSchema, ModelOptions, FieldOptions, Theme, Query, фильтров, страниц записей, связей, действий и identity |
| Встроенные адаптеры | Описанные конструкторы, discovery, метаданные, CRUD, связи и checked writes; SQLAdapter.refresh() |
| Протоколы расширений | Adapter, AuthBackend, RelationAdapter, CheckedAdapter, LoggerProtocol; hooks и current_operation() |
| Шаблоны | Пути, базовые блоки и контекст, описанные ниже |
Имена с _, внутренние ORM-методы, структура DOM, CSS-классы, внутренний JavaScript
и неописанные элементы контекста относятся к реализации. Расширения контролов
используют FieldOptions.template, parser и formatter; реестра именованных виджетов нет.
Поведение адаптеров и записи
Контракт адаптера задаёт типизированные скалярные mappings,
полные первичные ключи, фильтрацию до count/pagination, проекцию и атомарную запись.
Строки ключей непрозрачны: используйте ModelSchema.record_key() / parse_key(),
не разбирайте внутреннюю кодировку в приложении. Существующие корректные ключи
сохраняют round-trip в рамках API адаптера 1. NotFound, Conflict и ValidationError остаются
наследниками AdminError со статусами 404, 409 и 422. ValidationError.errors
сопоставляет именам полей сообщения; точная формулировка переводов не входит в API.
Семь обязательных методов отделены от необязательных связей, checked writes,
расширенных операторов, фильтров по связям и поиска ключей. Старым структурным
адаптерам не нужны базовый класс или новые capability-флаги. Новые возможности
включаются явно; ядро не должно молча передавать неподдерживаемые запросы.
Делегирование не должно обходить запись через сервис приложения. Изменение
обязательных методов требует повышения ADAPTER_API_VERSION и описанного
несовместимого релиза пакета.
Проверки identity, прав, CSRF и доступных для записи полей выполняются до hooks.
Порядок hooks сохраняется: before → атомарная запись адаптера/сервиса →
after. Before может запретить операцию; ошибка after не отменяет уже завершённую запись.
Верхние уровни mappings операции доступны только для чтения; изменение вложенного
снимка не меняет подготовленную запись. current_operation() сбрасывается при успехе
и при ошибке.
API шаблонов 1
TEMPLATE_API_VERSION импортируется из quite_admin; шаблоны получают такое же
значение как template_api_version. Пользовательские файлы имеют приоритет над
встроенными. В quite_admin/base.html сохраняются блоки title, head и content.
Под этим же каталогом остаются переопределяемыми пути quite_admin/login.html,
dashboard.html, list.html, form.html, delete.html, error.html и schema.html.
Каждый render содержит следующие зарезервированные значения. Callback страницы
не может их заменить:
| Значения | Содержимое |
|---|---|
request, admin, identity |
Request, экземпляр Admin, Identity или None до входа |
csrf, url |
CSRF-токен; url(path="/") с учётом mount/proxy-префиксов |
title, description, language, theme, logo_url |
Оформление экземпляра; URL логотипа или None |
t, tn |
Функции перевода и выбора множественного числа |
resources, resource_groups, pages |
Навигация с учётом прав; группы сопоставляют названия спискам ресурсов |
breadcrumbs, scripts, template_api_version |
Mappings крошек (label, url); разрешённых скриптов (url, integrity); целая версия контракта |
Ресурсы навигации предоставляют slug, label, schema, options и
record_label(record); конкретный класс относится к реализации. Пользовательская
страница дополнительно получает свой Page как page и контекст приложения из callback.
Листинг предоставляет resource, columns (последовательность Field), result
(RecordPage), page_number, limit, query (Query), query_url(**updates) и
permissions (булевые view, create, edit, delete).
Форма предоставляет resource, fields, values (форматированные строки по именам),
errors (сообщения по именам, необязательный __all__), defaults (множество имён),
creating, writable (имя → Field), record, form_action, revision_token,
stale, editable, can_delete и record_actions.
Include из FieldOptions.template дополнительно получает field, help (FieldOptions)
и editable конкретного поля. Текущая строка находится в values[field.name], ошибка —
в errors.get(field.name). Отправляйте значение под field.name, сохраняйте autoescape.
Include вызывается только для доступных для записи полей. Внешняя форма отвечает за
CSRF и revision-токены. При замене всей формы нужно сохранить эти токены и политику
доступных полей. Пользовательские шаблоны не дают дополнительных разрешений скриптам
и не обходят CSP.
Field, ModelSchema, RecordAction и Theme — изменяемые нехешируемые объекты
конфигурации. Настройте их до запросов; последующее присваивание не запускает
проверки конструктора. Поддерживаются сравнение и dataclasses.replace().
В режиме cursor result — RecordWindow с records, без точного total.
Для навигации используйте cursor_mode, cursor_previous_url, cursor_next_url.
Обычный offset возвращает RecordPage. Шаблоны должны учитывать выбранный режим.
Изменения и deprecation
Совместимые возможности повышают MINOR, исправления — PATCH. В 0.x несовместимое
изменение требует MINOR, миграции EN/RU и записи в changelog. Deprecation обязан
указывать замену и планируемую версию удаления, выдавать DeprecationWarning при
использовании устаревшей Python-точки входа и сохраняться как минимум ещё один
совместимый MINOR-релиз до удаления. Устаревание шаблонов объявляется в тех же
документах. После 1.0 несовместимость требует MAJOR. Исправления безопасности могут
отклонять ранее допустимый небезопасный ввод; ужесточение проверки должно быть описано.
Матрица Python/framework/ORM описана в совместимости зависимостей;
PATCH не прекращает поддержку молча. Стабильный API не обещает неограниченный экспорт,
фиксированную задержку, постоянное хранилище аудита или любые версии зависимостей.
Автоматические проверки
В репозитории закреплены api/*-0.4.json: импорты, сигнатуры, defaults, поля,
изменяемость, обязательные методы протоколов, статусы ошибок, версии контрактов и
базовые блоки. python scripts/check_api.py --profile modern выполняется в CI на
CPython 3.11–3.15; изолированные окружения GINO используют --profile gino.
Необязательные именованные аргументы разрешены; удаление аргумента, новый обязательный
аргумент и смена default ломают проверку. Смена аннотации консервативно требует ревью,
даже если она может расширять допустимые типы.
При расширении API сохраняйте прежние записи baseline. Планируемый несовместимый
релиз требует явного ревью и обновления baseline и миграции. Перегенерация ради
прохождения CI не заменяет ревью API. Структурная проверка не доказывает семантику:
интеграционные тесты адаптеров, безопасности, hooks, шаблонов и браузеров обязательны.