cadwyn 4.6.0__py3-none-any.whl → 5.0.0a1__py3-none-any.whl

cadwyn/_render.py

@@ -146,7 +146,10 @@ def _generate_field_ast(field: PydanticFieldWrapper) -> ast.Call:
         func=ast.Name("Field"),
         args=[],
         keywords=[
-            ast.keyword(arg=attr, value=ast.parse(get_fancy_repr(attr_value), mode="eval").body)
+            ast.keyword(
+                arg=attr,
+                value=ast.parse(get_fancy_repr(attr_value), mode="eval").body,
+            )
             for attr, attr_value in field.passed_field_attributes.items()
         ],
     )

cadwyn/applications.py

@@ -1,11 +1,12 @@
 import dataclasses
-import datetime
-from collections.abc import Callable, Coroutine, Sequence
+import warnings
+from collections.abc import Awaitable, Callable, Coroutine, Sequence
 from datetime import date
 from logging import getLogger
 from pathlib import Path
-from typing import Any, cast
+from typing import TYPE_CHECKING, Annotated, Any, cast
 
+import fastapi
 from fastapi import APIRouter, FastAPI, HTTPException, routing
 from fastapi.datastructures import Default
 from fastapi.openapi.docs import (
@@ -23,15 +24,26 @@ from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 from starlette.routing import BaseRoute, Route
 from starlette.types import Lifespan
-from typing_extensions import Self
+from typing_extensions import Self, assert_never, deprecated
 
 from cadwyn._utils import same_definition_as_in
 from cadwyn.changelogs import CadwynChangelogResource, _generate_changelog
-from cadwyn.middleware import HeaderVersioningMiddleware, _get_api_version_dependency
+from cadwyn.exceptions import CadwynStructureError
+from cadwyn.middleware import (
+    APIVersionFormat,
+    APIVersionLocation,
+    HeaderVersionManager,
+    URLVersionManager,
+    VersionPickingMiddleware,
+    _generate_api_version_dependency,
+)
 from cadwyn.route_generation import generate_versioned_routers
-from cadwyn.routing import _RootHeaderAPIRouter
+from cadwyn.routing import _RootCadwynAPIRouter
 from cadwyn.structure import VersionBundle
 
+if TYPE_CHECKING:
+    from cadwyn.structure.common import VersionType
+
 CURR_DIR = Path(__file__).resolve()
 logger = getLogger(__name__)
 
@@ -48,7 +60,18 @@ class Cadwyn(FastAPI):
         self,
         *,
         versions: VersionBundle,
-        api_version_header_name: str = "x-api-version",
+        api_version_header_name: Annotated[
+            str | None,
+            deprecated(
+                "api_version_header_name is deprecated and will be removed in the future. "
+                "Use api_version_parameter_name instead."
+            ),
+        ] = None,
+        api_version_location: APIVersionLocation = "custom_header",
+        api_version_format: APIVersionFormat = "date",
+        api_version_parameter_name: str = "x-api-version",
+        api_version_default_value: str | None | Callable[[Request], Awaitable[str]] = None,
+        versioning_middleware_class: type[VersionPickingMiddleware] = VersionPickingMiddleware,
         changelog_url: str | None = "/changelog",
         include_changelog_url_in_schema: bool = True,
         debug: bool = False,
@@ -100,6 +123,15 @@ class Cadwyn(FastAPI):
         self._dependency_overrides_provider = FakeDependencyOverridesProvider({})
         self._cadwyn_initialized = False
 
+        if api_version_header_name is not None:
+            warnings.warn(
+                "api_version_header_name is deprecated and will be removed in the future. "
+                "Use api_version_parameter_name instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            api_version_parameter_name = api_version_header_name
+
         super().__init__(
             debug=debug,
             title=title,
@@ -137,6 +169,18 @@ class Cadwyn(FastAPI):
             separate_input_output_schemas=separate_input_output_schemas,
             **extra,
         )
+
+        self._versioned_webhook_routers: dict[VersionType, APIRouter] = {}
+        self._latest_version_router = APIRouter(dependency_overrides_provider=self._dependency_overrides_provider)
+
+        self.changelog_url = changelog_url
+        self.include_changelog_url_in_schema = include_changelog_url_in_schema
+
+        self.docs_url = docs_url
+        self.redoc_url = redoc_url
+        self.openapi_url = openapi_url
+        self.redoc_url = redoc_url
+
         self._kwargs_to_router: dict[str, Any] = {
             "routes": routes,
             "redirect_slashes": redirect_slashes,
@@ -152,32 +196,48 @@ class Cadwyn(FastAPI):
             "responses": responses,
             "generate_unique_id_function": generate_unique_id_function,
         }
-        self.router: _RootHeaderAPIRouter = _RootHeaderAPIRouter(  # pyright: ignore[reportIncompatibleVariableOverride]
+        self.api_version_format = api_version_format
+        self.api_version_parameter_name = api_version_parameter_name
+        self.api_version_pythonic_parameter_name = api_version_parameter_name.replace("-", "_")
+        if api_version_location == "custom_header":
+            self._api_version_manager = HeaderVersionManager(api_version_parameter_name=api_version_parameter_name)
+            self._api_version_fastapi_depends_class = fastapi.Header
+        elif api_version_location == "path":
+            self._api_version_manager = URLVersionManager(possible_version_values=self.versions._version_values_set)
+            self._api_version_fastapi_depends_class = fastapi.Path
+        else:
+            assert_never(api_version_location)
+        # TODO: Add a test validating the error message when there are no versions
+        default_version_example = next(iter(self.versions._version_values_set))
+        if api_version_format == "date":
+            self.api_version_validation_data_type = date
+        elif api_version_format == "string":
+            self.api_version_validation_data_type = str
+        else:
+            assert_never(default_version_example)
+        self.router: _RootCadwynAPIRouter = _RootCadwynAPIRouter(  # pyright: ignore[reportIncompatibleVariableOverride]
             **self._kwargs_to_router,
-            api_version_header_name=api_version_header_name,
+            api_version_parameter_name=api_version_parameter_name,
             api_version_var=self.versions.api_version_var,
+            api_version_format=api_version_format,
         )
-        self._versioned_webhook_routers: dict[date, APIRouter] = {}
-        self._latest_version_router = APIRouter(dependency_overrides_provider=self._dependency_overrides_provider)
-
-        self.changelog_url = changelog_url
-        self.include_changelog_url_in_schema = include_changelog_url_in_schema
-
-        self.docs_url = docs_url
-        self.redoc_url = redoc_url
-        self.openapi_url = openapi_url
-        self.redoc_url = redoc_url
-
         unversioned_router = APIRouter(**self._kwargs_to_router)
         self._add_utility_endpoints(unversioned_router)
         self._add_default_versioned_routers()
         self.include_router(unversioned_router)
         self.add_middleware(
-            HeaderVersioningMiddleware,
-            api_version_header_name=self.router.api_version_header_name,
+            versioning_middleware_class,
+            api_version_parameter_name=api_version_parameter_name,
+            api_version_manager=self._api_version_manager,
+            api_version_default_value=api_version_default_value,
             api_version_var=self.versions.api_version_var,
-            default_response_class=default_response_class,
         )
+        if self.api_version_format == "date" and (
+            sorted(self.versions.versions, key=lambda v: v.value, reverse=True) != list(self.versions.versions)
+        ):
+            raise CadwynStructureError(
+                "Versions are not sorted correctly. Please sort them in descending order.",
+            )
 
     @same_definition_as_in(FastAPI.__call__)
     async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
@@ -193,7 +253,7 @@ class Cadwyn(FastAPI):
             versions=self.versions,
         )
         for version, router in generated_routers.endpoints.items():
-            self.add_header_versioned_routers(router, header_value=version.isoformat())
+            self._add_versioned_routers(router, version=version)
 
         for version, router in generated_routers.webhooks.items():
             self._versioned_webhook_routers[version] = router
@@ -267,26 +327,19 @@ class Cadwyn(FastAPI):
             self._latest_version_router.include_router(router)
 
     async def openapi_jsons(self, req: Request) -> JSONResponse:
-        raw_version = req.query_params.get("version") or req.headers.get(self.router.api_version_header_name)
-        not_found_error = HTTPException(
-            status_code=404,
-            detail=f"OpenApi file of with version `{raw_version}` not found",
-        )
-        try:
-            version = datetime.date.fromisoformat(raw_version)  # pyright: ignore[reportArgumentType]
-        # TypeError when raw_version is None
-        # ValueError when raw_version is of the non-iso format
-        except (ValueError, TypeError):
-            version = raw_version
+        version = req.query_params.get("version") or req.headers.get(self.router.api_version_parameter_name)
 
-        if isinstance(version, date) and version in self.router.versioned_routers:
+        if version in self.router.versioned_routers:
             routes = self.router.versioned_routers[version].routes
-            formatted_version = version.isoformat()
+            formatted_version = version
         elif version == "unversioned" and self._there_are_public_unversioned_routes():
             routes = self.router.unversioned_routes
             formatted_version = "unversioned"
         else:
-            raise not_found_error
+            raise HTTPException(
+                status_code=404,
+                detail=f"OpenApi file of with version `{version}` not found",
+            )
 
         # Add root path to servers when mounted as sub-app or proxy is used
         urls = (server_data.get("url") for server_data in self.servers)
@@ -296,7 +349,7 @@ class Cadwyn(FastAPI):
             self.servers.insert(0, {"url": root_path})
 
         webhook_routes = None
-        if isinstance(version, date) and version in self._versioned_webhook_routers:
+        if version in self._versioned_webhook_routers:
             webhook_routes = self._versioned_webhook_routers[version].routes
 
         return JSONResponse(
@@ -354,7 +407,7 @@ class Cadwyn(FastAPI):
         base_host = str(req.base_url).rstrip("/")
         root_path = self._extract_root_path(req)
         base_url = base_host + root_path
-        table = {version: f"{base_url}{docs_url}?version={version}" for version in self.router.sorted_versions}
+        table = {version: f"{base_url}{docs_url}?version={version}" for version in self.router.versions}
         if self._there_are_public_unversioned_routes():
             table |= {"unversioned": f"{base_url}{docs_url}?version=unversioned"}
         return self._templates.TemplateResponse(
@@ -362,6 +415,7 @@ class Cadwyn(FastAPI):
             {"request": req, "table": table},
         )
 
+    @deprecated("Use generate_and_include_versioned_routers and VersionBundle versions instead")
     def add_header_versioned_routers(
         self,
         first_router: APIRouter,
@@ -370,15 +424,20 @@ class Cadwyn(FastAPI):
     ) -> list[BaseRoute]:
         """Add all routes from routers to be routed using header_value and return the added routes"""
         try:
-            header_value_as_dt = date.fromisoformat(header_value)
+            date.fromisoformat(header_value)
         except ValueError as e:
             raise ValueError("header_value should be in ISO 8601 format") from e
 
+        return self._add_versioned_routers(first_router, *other_routers, version=header_value)
+
+    def _add_versioned_routers(
+        self, first_router: APIRouter, *other_routers: APIRouter, version: str
+    ) -> list[BaseRoute]:
         added_routes: list[BaseRoute] = []
-        if header_value_as_dt not in self.router.versioned_routers:  # pragma: no branch
-            self.router.versioned_routers[header_value_as_dt] = APIRouter(**self._kwargs_to_router)
+        if version not in self.router.versioned_routers:  # pragma: no branch
+            self.router.versioned_routers[version] = APIRouter(**self._kwargs_to_router)
 
-        versioned_router = self.router.versioned_routers[header_value_as_dt]
+        versioned_router = self.router.versioned_routers[version]
         if self.openapi_url is not None:  # pragma: no branch
             versioned_router.add_route(
                 path=self.openapi_url,
@@ -389,9 +448,18 @@ class Cadwyn(FastAPI):
 
         added_route_count = 0
         for router in (first_router, *other_routers):
-            self.router.versioned_routers[header_value_as_dt].include_router(
+            self.router.versioned_routers[version].include_router(
                 router,
-                dependencies=[Depends(_get_api_version_dependency(self.router.api_version_header_name, header_value))],
+                dependencies=[
+                    Depends(
+                        _generate_api_version_dependency(
+                            api_version_pythonic_parameter_name=self.api_version_pythonic_parameter_name,
+                            default_value=version,
+                            fastapi_depends_class=self._api_version_fastapi_depends_class,
+                            validation_data_type=self.api_version_validation_data_type,
+                        )
+                    )
+                ],
             )
             added_route_count += len(router.routes)
 

cadwyn/changelogs.py

@@ -1,5 +1,4 @@
 import copy
-import datetime
 import sys
 from enum import auto
 from logging import getLogger
@@ -22,7 +21,7 @@ from pydantic import BaseModel, Field, RootModel
 from cadwyn._asts import GenericAliasUnion
 from cadwyn._utils import Sentinel
 from cadwyn.route_generation import _get_routes
-from cadwyn.routing import _RootHeaderAPIRouter
+from cadwyn.routing import _RootCadwynAPIRouter
 from cadwyn.schema_generation import SchemaGenerator, _change_field_in_model, generate_versioned_models
 from cadwyn.structure.versions import PossibleInstructions, VersionBundle, VersionChange, VersionChangeWithSideEffects
 
@@ -62,15 +61,15 @@ def hidden(instruction_or_version_change: T) -> T:
     return instruction_or_version_change
 
 
-def _generate_changelog(versions: VersionBundle, router: _RootHeaderAPIRouter) -> "CadwynChangelogResource":
+def _generate_changelog(versions: VersionBundle, router: _RootCadwynAPIRouter) -> "CadwynChangelogResource":
     changelog = CadwynChangelogResource()
     schema_generators = generate_versioned_models(versions)
     for version, older_version in zip(versions, versions.versions[1:], strict=False):
         routes_from_newer_version = router.versioned_routers[version.value].routes
         schemas_from_older_version = get_fields_from_routes(router.versioned_routers[older_version.value].routes)
         version_changelog = CadwynVersion(value=version.value)
-        generator_from_newer_version = schema_generators[version.value.isoformat()]
-        generator_from_older_version = schema_generators[older_version.value.isoformat()]
+        generator_from_newer_version = schema_generators[version.value]
+        generator_from_older_version = schema_generators[older_version.value]
         for version_change in version.changes:
             if version_change.is_hidden_from_changelog:
                 continue
@@ -284,7 +283,7 @@ class CadwynChangelogResource(BaseModel):
 
 
 class CadwynVersion(BaseModel):
-    value: datetime.date
+    value: str
     changes: "list[CadwynVersionChange]" = Field(default_factory=list)
 
 

cadwyn/exceptions.py

@@ -1,5 +1,4 @@
 import json
-from datetime import date
 from typing import Any
 
 from fastapi.routing import APIRoute
@@ -14,12 +13,12 @@ class CadwynError(Exception):
 
 
 class CadwynHeadRequestValidationError(CadwynError):
-    def __init__(self, errors: list[Any], body: Any, version: date) -> None:
+    def __init__(self, errors: list[Any], body: Any, version: str) -> None:
         self.errors = errors
         self.body = body
         self.version = version
         super().__init__(
-            f"We failed to migrate the request with version={self.version!s}. "
+            f"We failed to migrate the request with version={self.version}. "
             "This means that there is some error in your migrations or schema structure that makes it impossible "
             "to migrate the request of that version to latest.\n"
             f"body={self.body}\n\nerrors={json.dumps(self.errors, indent=4, ensure_ascii=False)}"

cadwyn/middleware.py

@@ -1,54 +1,97 @@
+# NOTE: It's OK that any_string might not be correctly sortable such as v10 vs v9.
+# we can simply remove waterfalling from any_string api version style.
+
 import inspect
-from contextlib import AsyncExitStack
+import re
+from collections.abc import Awaitable, Callable
 from contextvars import ContextVar
-from datetime import date
-from typing import Annotated, Any, cast
+from typing import Annotated, Any, Literal, Protocol
 
-from fastapi import Header, Request, Response
-from fastapi._compat import _normalize_errors
-from fastapi.dependencies.utils import get_dependant, solve_dependencies
-from fastapi.responses import JSONResponse
+from fastapi import Request
 from starlette.middleware.base import BaseHTTPMiddleware, DispatchFunction, RequestResponseEndpoint
 from starlette.types import ASGIApp
 
+from cadwyn.structure.common import VersionType
+
+
+class VersionManager(Protocol):
+    def get(self, request: Request) -> str | None: ...
+
+
+VersionValidatorC = Callable[[str], VersionType]
+VersionDependencyFactoryC = Callable[[], Callable[..., Any]]
+
+APIVersionLocation = Literal["custom_header", "path"]
+APIVersionFormat = Literal["date", "string"]
+
+
+class HeaderVersionManager:
+    __slots__ = ("api_version_parameter_name",)
+
+    def __init__(self, *, api_version_parameter_name: str) -> None:
+        super().__init__()
+        self.api_version_parameter_name = api_version_parameter_name
 
-def _get_api_version_dependency(api_version_header_name: str, version_example: str):
+    def get(self, request: Request) -> str | None:
+        return request.headers.get(self.api_version_parameter_name)
+
+
+class URLVersionManager:
+    __slots__ = ("possible_version_values", "url_version_regex")
+
+    def __init__(self, *, possible_version_values: set[str]) -> None:
+        super().__init__()
+        self.possible_version_values = possible_version_values
+        self.url_version_regex = re.compile(f"/({'|'.join(re.escape(v) for v in possible_version_values)})/")
+
+    def get(self, request: Request) -> str | None:
+        if m := self.url_version_regex.search(request.url.path):
+            return m.group(1)
+        return None
+
+
+def _generate_api_version_dependency(
+    *,
+    api_version_pythonic_parameter_name: str,
+    default_value: str,
+    fastapi_depends_class: Callable[..., Any],
+    validation_data_type: Any,
+):
     def api_version_dependency(**kwargs: Any):
+        # TODO: What do I return?
         return next(iter(kwargs.values()))
 
     api_version_dependency.__signature__ = inspect.Signature(
         parameters=[
             inspect.Parameter(
-                api_version_header_name.replace("-", "_"),
+                api_version_pythonic_parameter_name,
                 inspect.Parameter.KEYWORD_ONLY,
-                annotation=Annotated[date, Header(examples=[version_example])],
-                default=version_example,
+                annotation=Annotated[
+                    validation_data_type, fastapi_depends_class(openapi_examples={"default": {"value": default_value}})
+                ],
             ),
         ],
     )
     return api_version_dependency
 
 
-class HeaderVersioningMiddleware(BaseHTTPMiddleware):
+class VersionPickingMiddleware(BaseHTTPMiddleware):
     def __init__(
         self,
         app: ASGIApp,
         *,
-        api_version_header_name: str,
-        api_version_var: ContextVar[date] | ContextVar[date | None],
-        default_response_class: type[Response] = JSONResponse,
+        api_version_parameter_name: str,
+        api_version_default_value: str | None | Callable[[Request], Awaitable[str]],
+        api_version_var: ContextVar[VersionType | None],
+        api_version_manager: VersionManager,
         dispatch: DispatchFunction | None = None,
     ) -> None:
         super().__init__(app, dispatch)
-        self.api_version_header_name = api_version_header_name
+
+        self.api_version_parameter_name = api_version_parameter_name
+        self._api_version_manager = api_version_manager
         self.api_version_var = api_version_var
-        self.default_response_class = default_response_class
-        # We use the dependant to apply fastapi's validation to the header, making validation at middleware level
-        # consistent with validation and route level.
-        self.version_header_validation_dependant = get_dependant(
-            path="",
-            call=_get_api_version_dependency(api_version_header_name, "2000-08-23"),
-        )
+        self.api_version_default_value = api_version_default_value
 
     async def dispatch(
         self,
@@ -57,24 +100,20 @@ class HeaderVersioningMiddleware(BaseHTTPMiddleware):
     ):
         # We handle api version at middleware level because if we try to add a Dependency to all routes, it won't work:
         # we use this header for routing so the user will simply get a 404 if the header is invalid.
-        api_version: date | None = None
-        if self.api_version_header_name in request.headers:
-            async with AsyncExitStack() as async_exit_stack:
-                solved_result = await solve_dependencies(
-                    request=request,
-                    dependant=self.version_header_validation_dependant,
-                    async_exit_stack=async_exit_stack,
-                    embed_body_fields=False,
-                )
-                if solved_result.errors:
-                    return self.default_response_class(status_code=422, content=_normalize_errors(solved_result.errors))
-                api_version = cast(date, solved_result.values[self.api_version_header_name.replace("-", "_")])
-                self.api_version_var.set(api_version)
+        api_version = self._api_version_manager.get(request)
+
+        if api_version is None:
+            if callable(self.api_version_default_value):  # pragma: no cover # TODO
+                api_version = await self.api_version_default_value(request)
+            else:
+                api_version = self.api_version_default_value
 
+        self.api_version_var.set(api_version)
         response = await call_next(request)
 
         if api_version is not None:
             # We return it because we will be returning the **matched** version, not the requested one.
-            response.headers[self.api_version_header_name] = api_version.isoformat()
+            # In date-based versioning with waterfalling, it makes sense.
+            response.headers[self.api_version_parameter_name] = api_version
 
         return response

cadwyn/route_generation.py

@@ -36,7 +36,7 @@ from cadwyn.schema_generation import (
     generate_versioned_models,
 )
 from cadwyn.structure import Version, VersionBundle
-from cadwyn.structure.common import Endpoint, VersionDate
+from cadwyn.structure.common import Endpoint, VersionType
 from cadwyn.structure.endpoints import (
     EndpointDidntExistInstruction,
     EndpointExistedInstruction,
@@ -62,8 +62,8 @@ class _EndpointInfo:
 
 @dataclass(slots=True, frozen=True)
 class GeneratedRouters(Generic[_R, _WR]):
-    endpoints: dict[VersionDate, _R]
-    webhooks: dict[VersionDate, _WR]
+    endpoints: dict[VersionType, _R]
+    webhooks: dict[VersionType, _WR]
 
 
 def generate_versioned_routers(
@@ -125,8 +125,8 @@ class _EndpointTransformer(Generic[_R, _WR]):
     def transform(self) -> GeneratedRouters[_R, _WR]:
         router = copy_router(self.parent_router)
         webhook_router = copy_router(self.parent_webhooks_router)
-        routers: dict[VersionDate, _R] = {}
-        webhook_routers: dict[VersionDate, _WR] = {}
+        routers: dict[VersionType, _R] = {}
+        webhook_routers: dict[VersionType, _WR] = {}
 
         for version in self.versions:
             self.schema_generators[str(version.value)].annotation_transformer.migrate_router_to_version(router)

cadwyn/routing.py

@@ -1,7 +1,6 @@
 import bisect
 from collections.abc import Sequence
 from contextvars import ContextVar
-from datetime import date
 from functools import cached_property
 from logging import getLogger
 from typing import Any
@@ -13,79 +12,56 @@ from starlette.routing import BaseRoute, Match
 from starlette.types import Receive, Scope, Send
 
 from cadwyn._utils import same_definition_as_in
-
-from .route_generation import generate_versioned_routers
-
-# TODO: Remove this in a major version. This is only here for backwards compatibility
-__all__ = ["generate_versioned_routers"]
+from cadwyn.middleware import APIVersionFormat
+from cadwyn.structure.common import VersionType
 
 _logger = getLogger(__name__)
 
 
-class _RootHeaderAPIRouter(APIRouter):
-    """Root router of the FastAPI app when using header based versioning.
-
-    It will be used to route the requests to the correct versioned route
-    based on the headers. It also supports waterflowing the requests to the latest
-    version of the API if the request header doesn't match any of the versions.
-
-    If the app has two versions: 2022-01-02 and 2022-01-05, and the request header
-    is 2022-01-03, then the request will be routed to 2022-01-02 version as it the closest
-    version, but lower than the request header.
-
-    Exact match is always preferred over partial match and a request will never be
-    matched to the higher versioned route
-    """
-
+class _RootCadwynAPIRouter(APIRouter):
     def __init__(
         self,
         *args: Any,
-        api_version_header_name: str,
-        api_version_var: ContextVar[date] | ContextVar[date | None],
+        api_version_parameter_name: str,
+        api_version_var: ContextVar[str | None],
+        api_version_format: APIVersionFormat,
         **kwargs: Any,
     ):
         super().__init__(*args, **kwargs)
-        self.versioned_routers: dict[date, APIRouter] = {}
-        self.api_version_header_name = api_version_header_name.lower()
+        self.versioned_routers: dict[VersionType, APIRouter] = {}
+        self.api_version_parameter_name = api_version_parameter_name.lower()
         self.api_version_var = api_version_var
         self.unversioned_routes: list[BaseRoute] = []
-
-    @cached_property
-    def sorted_versions(self):
-        return sorted(self.versioned_routers.keys())
-
-    @cached_property
-    def min_routes_version(self):
-        return min(self.sorted_versions)
-
-    def find_closest_date_but_not_new(self, request_version: date) -> date:
-        index = bisect.bisect_left(self.sorted_versions, request_version)
-        # as bisect_left returns the index where to insert item x in list a, assuming a is sorted
-        # we need to get the previous item and that will be a match
-        return self.sorted_versions[index - 1]
-
-    def pick_version(self, request_header_value: date) -> list[BaseRoute]:
-        request_version = request_header_value.isoformat()
-
-        if self.min_routes_version > request_header_value:
-            # then the request version is older that the oldest route we have
-            _logger.info(
-                "Request version is older than the oldest version. No route can match this version",
-                extra={
-                    "oldest_version": self.min_routes_version.isoformat(),
-                    "request_version": request_version,
-                },
-            )
-            return []
-        version_chosen = self.find_closest_date_but_not_new(request_header_value)
-        _logger.info(
-            "Partial match. The endpoint with a lower version was selected for the API call",
-            extra={
-                "version_chosen": version_chosen,
-                "request_version": request_version,
-            },
-        )
-        return self.versioned_routers[version_chosen].routes
+        self.api_version_format = api_version_format
+
+    async def _get_routes_from_closest_suitable_version(self, version: VersionType) -> list[BaseRoute]:
+        """Pick the versioned routes for the given version in case we failed to pick a concrete version
+
+        If the app has two versions: 2022-01-02 and 2022-01-05, and the request header
+        is 2022-01-03, then the request will be routed to 2022-01-02 version as it the closest
+        version, but lower than the request header.
+
+        Exact match is always preferred over partial match and a request will never be
+        matched to the higher versioned route.
+
+        We implement routing like this because it is extremely convenient with microservice
+        architecture. For example, imagine that you have two Cadwyn services: Payables and Receivables,
+        each defining its own API versions. Payables service might contain 10 versions while receivables
+        service might contain only 2 versions because it didn't need as many breaking changes.
+        If a client requests a version that does not exist in receivables -- we will just waterfall
+        to some earlier version, making receivables behavior consistent even if API keeps getting new versions.
+        """
+        if self.api_version_format == "date":
+            index = bisect.bisect_left(self.versions, version)
+            # That's when we try to get a version earlier than the earliest possible version
+            if index == 0:
+                return []
+            picked_version = self.versions[index - 1]
+            self.api_version_var.set(picked_version)
+            # as bisect_left returns the index where to insert item x in list a, assuming a is sorted
+            # we need to get the previous item and that will be a match
+            return self.versioned_routers[picked_version].routes
+        return []  # pragma: no cover # This should not be possible
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         if "router" not in scope:  # pragma: no cover
@@ -95,18 +71,22 @@ class _RootHeaderAPIRouter(APIRouter):
             await self.lifespan(scope, receive, send)
             return
 
-        header_value = self.api_version_var.get(None)
+        version = self.api_version_var.get(None)
 
-        # if header_value is None, then it's an unversioned request and we need to use the unversioned routes
+        # if version is None, then it's an unversioned request and we need to use the unversioned routes
         # if there will be a value, we search for the most suitable version
-        if not header_value:
+        if not version:
             routes = self.unversioned_routes
-        elif header_value in self.versioned_routers:
-            routes = self.versioned_routers[header_value].routes
+        elif version in self.versioned_routers:
+            routes = self.versioned_routers[version].routes
         else:
-            routes = self.pick_version(request_header_value=header_value)
+            routes = await self._get_routes_from_closest_suitable_version(version)
         await self.process_request(scope=scope, receive=receive, send=send, routes=routes)
 
+    @cached_property
+    def versions(self):
+        return sorted(self.versioned_routers.keys())
+
     @same_definition_as_in(APIRouter.add_api_route)
     def add_api_route(self, *args: Any, **kwargs: Any):
         super().add_api_route(*args, **kwargs)

cadwyn/schema_generation.py

@@ -45,8 +45,8 @@ from pydantic.fields import ComputedFieldInfo, FieldInfo
 from typing_extensions import Doc, Self, _AnnotatedAlias, assert_never
 
 from cadwyn._utils import Sentinel, UnionType, fully_unwrap_decorator, lenient_issubclass
-from cadwyn.exceptions import InvalidGenerationInstructionError
-from cadwyn.structure.common import VersionDate
+from cadwyn.exceptions import CadwynError, InvalidGenerationInstructionError
+from cadwyn.structure.common import VersionType
 from cadwyn.structure.data import ResponseInfo
 from cadwyn.structure.enums import AlterEnumSubInstruction, EnumDidntHaveMembersInstruction, EnumHadMembersInstruction
 from cadwyn.structure.schemas import (
@@ -158,15 +158,18 @@ def migrate_response_body(
     latest_response_model: type[pydantic.BaseModel],
     *,
     latest_body: Any,
-    version: VersionDate | str,
+    version: VersionType | date,
 ) -> Any:
     """Convert the data to a specific version
 
     Apply all version changes from latest until the passed version in reverse order
     and wrap the result in the correct version of latest_response_model
     """
-    if isinstance(version, str):
-        version = date.fromisoformat(version)
+    if isinstance(version, date):
+        version = version.isoformat()
+        version = versions._get_closest_lesser_version(version)
+    if version not in versions._version_values_set:
+        raise CadwynError(f"Version {version} not found in version bundle")
     response = ResponseInfo(Response(status_code=200), body=latest_body)
     migrated_response = versions._migrate_response(
         response,
@@ -176,8 +179,6 @@ def migrate_response_body(
         method="GET",
     )
 
-    version = versions._get_closest_lesser_version(version)
-
     versioned_response_model: type[pydantic.BaseModel] = generate_versioned_models(versions)[str(version)][
         latest_response_model
     ]

cadwyn/structure/common.py

@@ -1,4 +1,3 @@
-import datetime
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import ParamSpec, TypeAlias, TypeVar
@@ -6,7 +5,7 @@ from typing import ParamSpec, TypeAlias, TypeVar
 from pydantic import BaseModel
 
 VersionedModel = BaseModel
-VersionDate = datetime.date
+VersionType: TypeAlias = str
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
 Endpoint: TypeAlias = Callable[_P, _R]

cadwyn/structure/versions.py

@@ -33,7 +33,7 @@ from cadwyn.exceptions import (
 )
 
 from .._utils import Sentinel
-from .common import Endpoint, VersionDate, VersionedModel
+from .common import Endpoint, VersionedModel, VersionType
 from .data import (
     RequestInfo,
     ResponseInfo,
@@ -58,7 +58,7 @@ PossibleInstructions: TypeAlias = (
     | SchemaHadInstruction
     | staticmethod
 )
-APIVersionVarType: TypeAlias = ContextVar[VersionDate | None] | ContextVar[VersionDate]
+APIVersionVarType: TypeAlias = ContextVar[VersionType | None] | ContextVar[VersionType]
 IdentifierPythonPath = str
 
 
@@ -201,11 +201,11 @@ class VersionChangeWithSideEffects(VersionChange, _abstract=True):
 
 
 class Version:
-    def __init__(self, value: VersionDate | str, *changes: type[VersionChange]) -> None:
+    def __init__(self, value: str | date, *changes: type[VersionChange]) -> None:
         super().__init__()
 
-        if isinstance(value, str):
-            value = date.fromisoformat(value)
+        if isinstance(value, date):
+            value = value.isoformat()
         self.value = value
         self.changes = changes
 
@@ -252,7 +252,7 @@ class VersionBundle:
         latest_version_or_head_version: Version | HeadVersion,
         /,
         *other_versions: Version,
-        api_version_var: APIVersionVarType | None = None,
+        api_version_var: ContextVar[VersionType | None] | None = None,
     ) -> None:
         super().__init__()
 
@@ -262,27 +262,21 @@ class VersionBundle:
         else:
             self.head_version = HeadVersion()
             self.versions = (latest_version_or_head_version, *other_versions)
+        self.reversed_versions = tuple(reversed(self.versions))
 
-        self.version_dates = tuple(version.value for version in self.versions)
         if api_version_var is None:
             api_version_var = ContextVar("cadwyn_api_version")
+        self.version_values = tuple(version.value for version in self.versions)
+        self.reversed_version_values = tuple(reversed(self.version_values))
         self.api_version_var = api_version_var
-        if sorted(self.versions, key=lambda v: v.value, reverse=True) != list(self.versions):
-            raise CadwynStructureError(
-                "Versions are not sorted correctly. Please sort them in descending order.",
-            )
-        if not self.versions:
-            raise CadwynStructureError("You must define at least one non-head version in a VersionBundle.")
-        if self.versions[-1].changes:
-            raise CadwynStructureError(
-                f'The first version "{self.versions[-1].value}" cannot have any version changes. '
-                "Version changes are defined to migrate to/from a previous version so you "
-                "cannot define one for the very first version.",
-            )
-        version_values = set()
+        self._all_versions = (self.head_version, *self.versions)
+        self._version_changes_to_version_mapping = {
+            version_change: version.value for version in self.versions for version_change in version.changes
+        }
+        self._version_values_set: set[str] = set()
         for version in self.versions:
-            if version.value not in version_values:
-                version_values.add(version.value)
+            if version.value not in self._version_values_set:
+                self._version_values_set.add(version.value)
             else:
                 raise CadwynStructureError(
                     f"You tried to define two versions with the same value in the same "
@@ -295,13 +289,23 @@ class VersionBundle:
                         "It is prohibited.",
                     )
                 version_change._bound_version_bundle = self
+        if not self.versions:
+            raise CadwynStructureError("You must define at least one non-head version in a VersionBundle.")
+
+        if self.versions[-1].changes:
+            raise CadwynStructureError(
+                f'The first version "{self.versions[-1].value}" cannot have any version changes. '
+                "Version changes are defined to migrate to/from a previous version so you "
+                "cannot define one for the very first version.",
+            )
 
     def __iter__(self) -> Iterator[Version]:
         yield from self.versions
 
-    @functools.cached_property
-    def _all_versions(self):
-        return (self.head_version, *self.versions)
+    @property
+    @deprecated("Use 'version_values' instead.")
+    def version_dates(self):  # pragma: no cover
+        return self.version_values
 
     @functools.cached_property
     def versioned_schemas(self) -> dict[IdentifierPythonPath, type[VersionedModel]]:
@@ -330,18 +334,12 @@ class VersionBundle:
             for instruction in version_change.alter_enum_instructions
         }
 
-    def _get_closest_lesser_version(self, version: VersionDate):
-        for defined_version in self.version_dates:
+    def _get_closest_lesser_version(self, version: VersionType):
+        for defined_version in self.version_values:
             if defined_version <= version:
                 return defined_version
         raise CadwynError("You tried to migrate to version that is earlier than the first version which is prohibited.")
 
-    @functools.cached_property
-    def _version_changes_to_version_mapping(
-        self,
-    ) -> dict[type[VersionChange] | type[VersionChangeWithSideEffects], VersionDate]:
-        return {version_change: version.value for version in self.versions for version_change in version.changes}
-
     async def _migrate_request(
         self,
         body_type: type[BaseModel] | None,
@@ -350,7 +348,7 @@ class VersionBundle:
         request: FastapiRequest,
         response: FastapiResponse,
         request_info: RequestInfo,
-        current_version: VersionDate,
+        current_version: VersionType,
         head_route: APIRoute,
         *,
         exit_stack: AsyncExitStack,
@@ -358,9 +356,9 @@ class VersionBundle:
         background_tasks: BackgroundTasks | None,
     ) -> dict[str, Any]:
         method = request.method
-        for v in reversed(self.versions):
-            if v.value <= current_version:
-                continue
+
+        start = self.reversed_version_values.index(current_version)
+        for v in self.reversed_versions[start + 1 :]:
             for version_change in v.changes:
                 if body_type is not None and body_type in version_change.alter_request_by_schema_instructions:
                     for instruction in version_change.alter_request_by_schema_instructions[body_type]:
@@ -391,14 +389,13 @@ class VersionBundle:
     def _migrate_response(
         self,
         response_info: ResponseInfo,
-        current_version: VersionDate,
+        current_version: VersionType,
         head_response_model: type[BaseModel],
         path: str,
         method: str,
     ) -> ResponseInfo:
-        for v in self.versions:
-            if v.value <= current_version:
-                break
+        end = self.version_values.index(current_version)
+        for v in self.versions[:end]:
             for version_change in v.changes:
                 migrations_to_apply: list[_BaseAlterResponseInstruction] = []
 

{cadwyn-4.6.0.dist-info → cadwyn-5.0.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 4.6.0
+Version: 5.0.0a1
 Summary: Production-ready community-driven modern Stripe-like API versioning in FastAPI
 Project-URL: Source code, https://github.com/zmievsa/cadwyn
 Project-URL: Documentation, https://docs.cadwyn.dev

cadwyn-5.0.0a1.dist-info/RECORD

@@ -0,0 +1,28 @@
+cadwyn/__init__.py,sha256=gWsp-oNP5LhBqWF_rsrv6sEYP9KchTu8xhxAR8uaPm0,1035
+cadwyn/__main__.py,sha256=fGoKJPNVueqqXW4rqwmRUBBMoDGeLEyATdT-rel5Pvs,2449
+cadwyn/_asts.py,sha256=kd6Ngwr8c-uTNx-R-pP48Scf0OdjrTyEeSYe5DLoGqo,5095
+cadwyn/_importer.py,sha256=QV6HqODCG9K2oL4Vc15fAqL2-plMvUWw_cgaj4Ln4C8,1075
+cadwyn/_render.py,sha256=VArS68879hXRntMKCQJ7LUpCv8aToavHZV1JuBFmtfY,5513
+cadwyn/_utils.py,sha256=rlD1SkswtZ1bWgKj6PLYbVaHYkD-NzY4iUcHdPd2Y68,1475
+cadwyn/applications.py,sha256=bBO5kK-lDbjk3Rrbx8TdSY5EHDq4BkwlOzQruZ4Vj00,20128
+cadwyn/changelogs.py,sha256=-ft0Rpx_xDoVWNuAH8NYmUpE9UnSZfreyL-Qa2fP78Y,20004
+cadwyn/exceptions.py,sha256=gLCikeUPeLJwVjM8_DoSTIFHwmNI7n7vw1atpgHvbMU,1803
+cadwyn/middleware.py,sha256=lP8bFHHhXEMjOyDdljxiC2fH5K826qPe07qERq1nnG8,4274
+cadwyn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cadwyn/route_generation.py,sha256=EclCM9CI05ZRQW1qa052cBnF3Zb8Qj4lbIvHQSy0g_8,25152
+cadwyn/routing.py,sha256=cG3ieQ9NlF-PvslT9fy5AHBNco4lMgDoqQu42klnCLk,6899
+cadwyn/schema_generation.py,sha256=pM5bM0Tfi10ahSWRaD4h3zjzH-ERRkySh1iVURwf010,42089
+cadwyn/static/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cadwyn/static/docs.html,sha256=WNm5ANJVy51TcIUFOaqKf1Z8eF86CC85TTHPxACtkzw,3455
+cadwyn/structure/__init__.py,sha256=Wgvjdq3vfl9Yhe-BkcFGAMi_Co11YOfTmJQqgF5Gzx4,655
+cadwyn/structure/common.py,sha256=3UEbxzAjDfHT2GPMQ3tNA3pEqJd9ZnDclqsj2ZDpzv4,399
+cadwyn/structure/data.py,sha256=uViRW4uOOonXZj90hOlPNk02AIwp0fvDNoF8M5_CEes,7707
+cadwyn/structure/endpoints.py,sha256=8lrc4xanCt7gat106yYRIQC0TNxzFkLF-urIml_d_X0,5934
+cadwyn/structure/enums.py,sha256=bZL-iUOUFi9ZYlMZJw-tAix2yrgCp3gH3N2gwO44LUU,1043
+cadwyn/structure/schemas.py,sha256=v_wDTn84SgHVDFDlTgoalUzBXpDbT5Hl73Skp0UyGAM,10081
+cadwyn/structure/versions.py,sha256=p0Ui00RX8DW9M-wndiaXBK2t85Bd4ypGigPCfVZ9PiE,33167
+cadwyn-5.0.0a1.dist-info/METADATA,sha256=qJdUYZjLL1OUUixdtsSZOaj-Ee6ZIfDZgDKStnJEPys,4506
+cadwyn-5.0.0a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cadwyn-5.0.0a1.dist-info/entry_points.txt,sha256=mGX8wl-Xfhpr5M93SUmkykaqinUaYAvW9rtDSX54gx0,47
+cadwyn-5.0.0a1.dist-info/licenses/LICENSE,sha256=KeCWewiDQYpmSnzF-p_0YpoWiyDcUPaCuG8OWQs4ig4,1072
+cadwyn-5.0.0a1.dist-info/RECORD,,

cadwyn-4.6.0.dist-info/RECORD

@@ -1,28 +0,0 @@
-cadwyn/__init__.py,sha256=gWsp-oNP5LhBqWF_rsrv6sEYP9KchTu8xhxAR8uaPm0,1035
-cadwyn/__main__.py,sha256=fGoKJPNVueqqXW4rqwmRUBBMoDGeLEyATdT-rel5Pvs,2449
-cadwyn/_asts.py,sha256=kd6Ngwr8c-uTNx-R-pP48Scf0OdjrTyEeSYe5DLoGqo,5095
-cadwyn/_importer.py,sha256=QV6HqODCG9K2oL4Vc15fAqL2-plMvUWw_cgaj4Ln4C8,1075
-cadwyn/_render.py,sha256=LJ-R1TrBgMJpTkJb6pQdRWaMjKyw3R6eTlXXEieqUw0,5466
-cadwyn/_utils.py,sha256=rlD1SkswtZ1bWgKj6PLYbVaHYkD-NzY4iUcHdPd2Y68,1475
-cadwyn/applications.py,sha256=-MQL8_WWQSvnP1Z3zS7BlVwjrUWUGW9s1xVV1mKha6E,17008
-cadwyn/changelogs.py,sha256=uveMizeeqNv0JuXza9Rkg0ulDEWyJL24bRxcHkHlwjI,20054
-cadwyn/exceptions.py,sha256=VlJKRmEGfFTDtHbOWc8kXK4yMi2N172K684Y2UIV8rI,1832
-cadwyn/middleware.py,sha256=kUZK2dmoricMbv6knPCIHpXEInX2670XIwAj0v_XQxk,3408
-cadwyn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cadwyn/route_generation.py,sha256=tdIsdDIBY4hVUlTGMh4pTMM92LzxhV9CmGs6J8iAhaw,25152
-cadwyn/routing.py,sha256=mZRe7ivfTY2qdgrCBO4AHvKQq6Dazf7g_8B6aCrTgN8,7221
-cadwyn/schema_generation.py,sha256=W3SnBPF4fRK48bXGF-EooJHhkKoQMhzJgP-jC5FP98k,41951
-cadwyn/static/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cadwyn/static/docs.html,sha256=WNm5ANJVy51TcIUFOaqKf1Z8eF86CC85TTHPxACtkzw,3455
-cadwyn/structure/__init__.py,sha256=Wgvjdq3vfl9Yhe-BkcFGAMi_Co11YOfTmJQqgF5Gzx4,655
-cadwyn/structure/common.py,sha256=GUclfxKLRlFwPjT237fCtLIzdvjvC9gI3acuxBizwbg,414
-cadwyn/structure/data.py,sha256=uViRW4uOOonXZj90hOlPNk02AIwp0fvDNoF8M5_CEes,7707
-cadwyn/structure/endpoints.py,sha256=8lrc4xanCt7gat106yYRIQC0TNxzFkLF-urIml_d_X0,5934
-cadwyn/structure/enums.py,sha256=bZL-iUOUFi9ZYlMZJw-tAix2yrgCp3gH3N2gwO44LUU,1043
-cadwyn/structure/schemas.py,sha256=v_wDTn84SgHVDFDlTgoalUzBXpDbT5Hl73Skp0UyGAM,10081
-cadwyn/structure/versions.py,sha256=L07vdC9d7_h4WKV8TArgZKfgfzB8-M4f62FXZm8o1TM,33232
-cadwyn-4.6.0.dist-info/METADATA,sha256=KFK2JacLS-rYQju0mqFUk-c1niFrYZa1Kitkj7gOYGw,4504
-cadwyn-4.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cadwyn-4.6.0.dist-info/entry_points.txt,sha256=mGX8wl-Xfhpr5M93SUmkykaqinUaYAvW9rtDSX54gx0,47
-cadwyn-4.6.0.dist-info/licenses/LICENSE,sha256=KeCWewiDQYpmSnzF-p_0YpoWiyDcUPaCuG8OWQs4ig4,1072
-cadwyn-4.6.0.dist-info/RECORD,,