История изменений¶

Здесь описаны все заметные изменения проекта.

Формат основан на Keep a Changelog, проект придерживается семантического версионирования.

0.5.0 — 2026-10-21¶

versionize(app, version) объявляет версию субприложения — замена FastAPI(api_version=N), который FastAPI 0.145+ не принимает. Функция возвращает то же приложение, поэтому работает app.mount("/v1", versionize(FastAPI(), 1)); неверные типы аргументов дают TypeError, а объявление приложения другой версией — ValueError.

Ломающее. Снята верхняя граница <0.145 из 0.4.2 — FastAPI 0.145+ снова поддерживается. Свежая установка теперь может подтянуть FastAPI 0.145+, где FastAPI(api_version=N) падает с TypeError: переведите объявления на versionize до обновления или закрепите fastapi<0.145. См. миграцию с 0.4.x.

FastAPI(api_version=N) и API_VERSION_KEY. Ключевой аргумент продолжает работать на FastAPI < 0.145, если приложение не объявлено через versionize; его FutureWarning теперь называет затронутые маунты и указывает на versionize. Оба будут удалены вместе с поддержкой FastAPI < 0.145.

Для FastAPI добавлена верхняя граница <0.145: в этом релизе удалён FastAPI(**extra), а вместе с ним и объявление FastAPI(api_version=N), на котором держится библиотека.
Ограничение сборочного бэкенда расширено до uv_build>=0.8.3,<0.14.0.

Объявление версии через FastAPI(api_version=N) теперь выдаёт FutureWarning. На FastAPI < 0.145 оно продолжает работать; в 0.5.0 его заменит новый интерфейс, который поддерживает и FastAPI 0.145+.

На FastAPI 0.143.1+ версионированный WebSocket-эндпоинт из подключённого роутера падал с «Versioning is not initialized» в своей версии и наследовался без include-префикса и include-зависимостей.
Роуты, унаследованные из подключённого роутера, сохраняют его strict_content_type: раньше APIRouter(strict_content_type=False) в новых версиях снова становился строгим.

Функциональных изменений нет: библиотека ведёт себя ровно так же, как в 0.4.0.

Docstrings публичного API существенно расширены — теперь в них описаны правила разрешения until, однократность сборки и диагностика ошибок; именно их показывает IDE при наведении. На них же построен новый авто-генерируемый справочник API.
Метаданные пакета: заполнены keywords, Homepage переведён с репозитория на сайт документации, добавлены ссылки Issues и Changelog.
Ограничение сборочного бэкенда расширено до uv_build>=0.8.3,<0.12.0.

WebSocket-роуты версионируются наравне с HTTP: APIWebSocketRoute наследуется между версиями с той же семантикой until, а затенение стало видозависимым — HTTP-роут и WebSocket на одном пути больше не конфликтуют.
Валидация api_version и until. Значение api_version не типа int (или bool) и until меньше версии объявления теперь приводят к UserWarning, а не отрабатывают молча.
API_VERSION_KEY экспортируется из корня пакета.

Ломающее. Middleware переписан как чистый ASGI-middleware (без BaseHTTPMiddleware) и строит наследование ровно один раз — при первом ASGI-событии. Роуты и версии, добавленные позже, требуют явного вызова rebuild_versioning(app), ставшего публичным.
Ломающее. Каждая наследующая версия получает собственную копию роута с dependency_overrides, привязанными к целевому приложению, вместо общего объекта роута на все версии.
Ломающее. Метаданные версии хранятся по роутам в реестре на версионном субприложении, а не через мутацию общего экземпляра зависимости. Роутер, включённый в несколько версий, теперь разрешается корректно.
Прекращена поддержка Python 3.9; поддерживаемый диапазон — 3.10–3.14.

Поддержан FastAPI 0.137+: обход роутов идёт через публичный итератор iter_route_contexts нового дерева роутинга, поэтому эндпоинты, добавленные через include_router, версионируются вместе с include-префиксами и зависимостями. Версии 0.137.0 и 0.137.1 исключены на уровне зависимости — дерево там уже появилось, а публичный итератор только в 0.137.2.
Версия 0 считается допустимой (явные проверки на None вместо проверки на истинность).
Приложение, не монтирующее ни одного версионного субприложения, корректно ничего не делает вместо ошибки.

Флаг rebuild_openapi у VersioningMiddleware. Со значением False эндпоинты по-прежнему наследуются и обслуживаются, но унаследованные не попадают в OpenAPI-схему и /docs версии.

Первый релиз: VersioningMiddleware и зависимость versioning() — одно FastAPI-субприложение на версию, наследование помеченных эндпоинтов из старых версий в новые и перестройка OpenAPI-схемы каждой версии.