cadwyn 5.2.1__py3-none-any.whl → 5.3.0__py3-none-any.whl

cadwyn/applications.py

@@ -4,7 +4,7 @@ from collections.abc import Awaitable, Callable, Coroutine, Sequence
 from datetime import date
 from logging import getLogger
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Union, cast
+from typing import TYPE_CHECKING, Annotated, Any, Optional, Union, cast
 
 import fastapi
 from fastapi import APIRouter, FastAPI, HTTPException, routing
@@ -71,6 +71,8 @@ class Cadwyn(FastAPI):
         api_version_format: APIVersionFormat = "date",
         api_version_parameter_name: str = "x-api-version",
         api_version_default_value: Union[str, None, Callable[[Request], Awaitable[str]]] = None,
+        api_version_title: Optional[str] = None,
+        api_version_description: Optional[str] = None,
         versioning_middleware_class: type[VersionPickingMiddleware] = VersionPickingMiddleware,
         changelog_url: Union[str, None] = "/changelog",
         include_changelog_url_in_schema: bool = True,
@@ -207,6 +209,8 @@ class Cadwyn(FastAPI):
         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("-", "_")
+        self.api_version_title = api_version_title
+        self.api_version_description = api_version_description
         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
@@ -465,6 +469,8 @@ class Cadwyn(FastAPI):
                             default_value=version,
                             fastapi_depends_class=self._api_version_fastapi_depends_class,
                             validation_data_type=self.api_version_validation_data_type,
+                            title=self.api_version_title,
+                            description=self.api_version_description,
                         )
                     )
                 ],

cadwyn/middleware.py

@@ -5,7 +5,7 @@ import inspect
 import re
 from collections.abc import Awaitable, Callable
 from contextvars import ContextVar
-from typing import Annotated, Any, Literal, Protocol, Union
+from typing import Annotated, Any, Literal, Optional, Protocol, Union
 
 import fastapi
 from fastapi import Request
@@ -58,6 +58,8 @@ def _generate_api_version_dependency(
     default_value: str,
     fastapi_depends_class: Callable[..., Any],
     validation_data_type: Any,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
 ):
     def api_version_dependency(**kwargs: Any):
         # TODO: What do I return?
@@ -69,7 +71,12 @@ def _generate_api_version_dependency(
                 api_version_pythonic_parameter_name,
                 inspect.Parameter.KEYWORD_ONLY,
                 annotation=Annotated[
-                    validation_data_type, fastapi_depends_class(openapi_examples={"default": {"value": default_value}})
+                    validation_data_type,
+                    fastapi_depends_class(
+                        openapi_examples={"default": {"value": default_value}},
+                        title=title,
+                        description=description,
+                    ),
                 ],
                 # Path-based parameters do not support a default value in FastAPI :(
                 default=default_value if fastapi_depends_class != fastapi.Path else inspect.Signature.empty,

cadwyn/route_generation.py

@@ -37,11 +37,13 @@ from cadwyn.schema_generation import (
 )
 from cadwyn.structure import Version, VersionBundle
 from cadwyn.structure.common import Endpoint, VersionType
+from cadwyn.structure.data import _AlterRequestByPathInstruction, _AlterResponseByPathInstruction
 from cadwyn.structure.endpoints import (
     EndpointDidntExistInstruction,
     EndpointExistedInstruction,
     EndpointHadInstruction,
 )
+from cadwyn.structure.versions import VersionChange
 
 if TYPE_CHECKING:
     from fastapi.dependencies.models import Dependant
@@ -52,6 +54,9 @@ _WR = TypeVar("_WR", bound=APIRouter, default=APIRouter)
 _RouteT = TypeVar("_RouteT", bound=BaseRoute)
 # This is a hack we do because we can't guarantee how the user will use the router.
 _DELETED_ROUTE_TAG = "_CADWYN_DELETED_ROUTE"
+_RoutePath = str
+_RouteMethod = str
+_RouteId = int
 
 
 @dataclass(**DATACLASS_SLOTS, frozen=True, eq=True)
@@ -123,6 +128,7 @@ class _EndpointTransformer(Generic[_R, _WR]):
         ]
 
     def transform(self) -> GeneratedRouters[_R, _WR]:
+        # Copy MUST keep the order and number of routes. Otherwise, a ton of code below will break.
         router = copy_router(self.parent_router)
         webhook_router = copy_router(self.parent_webhooks_router)
         routers: dict[VersionType, _R] = {}
@@ -132,7 +138,7 @@ class _EndpointTransformer(Generic[_R, _WR]):
             self.schema_generators[str(version.value)].annotation_transformer.migrate_router_to_version(router)
             self.schema_generators[str(version.value)].annotation_transformer.migrate_router_to_version(webhook_router)
 
-            self._validate_all_data_converters_are_applied(router, version)
+            self._attach_routes_to_data_converters(router, self.parent_router, version)
 
             routers[version.value] = router
             webhook_routers[version.value] = webhook_router
@@ -193,9 +199,11 @@ class _EndpointTransformer(Generic[_R, _WR]):
             ]
         return GeneratedRouters(routers, webhook_routers)
 
-    def _validate_all_data_converters_are_applied(self, router: APIRouter, version: Version):
-        path_to_route_methods_mapping, head_response_models, head_request_bodies = self._extract_all_routes_identifiers(
-            router
+    def _attach_routes_to_data_converters(self, router: APIRouter, head_router: APIRouter, version: Version):
+        # This method is way out of its league in terms of complexity. We gotta refactor it.
+
+        path_to_route_methods_mapping, head_response_models, head_request_bodies = (
+            self._extract_all_routes_identifiers_for_route_to_converter_matching(router)
         )
 
         for version_change in version.changes:
@@ -204,21 +212,10 @@ class _EndpointTransformer(Generic[_R, _WR]):
                 *version_change.alter_request_by_path_instructions.values(),
             ]:
                 for by_path_converter in by_path_converters:
-                    missing_methods = by_path_converter.methods.difference(
-                        path_to_route_methods_mapping[by_path_converter.path]
+                    self._attach_routes_by_path_converter(
+                        head_router, path_to_route_methods_mapping, version_change, by_path_converter
                     )
 
-                    if missing_methods:
-                        raise RouteByPathConverterDoesNotApplyToAnythingError(
-                            f"{by_path_converter.repr_name} "
-                            f'"{version_change.__name__}.{by_path_converter.transformer.__name__}" '
-                            f"failed to find routes with the following methods: {list(missing_methods)}. "
-                            f"This means that you are trying to apply this converter to non-existing endpoint(s). "
-                            "Please, check whether the path and methods are correct. (hint: path must include "
-                            "all path variables and have a name that was used in the version that this "
-                            "VersionChange resides in)"
-                        )
-
             for by_schema_converters in version_change.alter_request_by_schema_instructions.values():
                 for by_schema_converter in by_schema_converters:
                     if not by_schema_converter.check_usage:  # pragma: no cover
@@ -249,14 +246,50 @@ class _EndpointTransformer(Generic[_R, _WR]):
                             f"{version_change.__name__}.{by_schema_converter.transformer.__name__}"
                         )
 
-    def _extract_all_routes_identifiers(
-        self, router: APIRouter
-    ) -> tuple[defaultdict[str, set[str]], set[Any], set[Any]]:
-        response_models: set[Any] = set()
-        request_bodies: set[Any] = set()
-        path_to_route_methods_mapping: dict[str, set[str]] = defaultdict(set)
+    def _attach_routes_by_path_converter(
+        self,
+        head_router: APIRouter,
+        path_to_route_methods_mapping: dict[_RoutePath, dict[_RouteMethod, set[_RouteId]]],
+        version_change: type[VersionChange],
+        by_path_converter: Union[_AlterResponseByPathInstruction, _AlterRequestByPathInstruction],
+    ):
+        missing_methods = set()
+        for method in by_path_converter.methods:
+            if method in path_to_route_methods_mapping[by_path_converter.path]:
+                for route_index in path_to_route_methods_mapping[by_path_converter.path][method]:
+                    route = head_router.routes[route_index]
+                    if isinstance(by_path_converter, _AlterResponseByPathInstruction):
+                        version_change._route_to_response_migration_mapping[id(route)].append(by_path_converter)
+                    else:
+                        version_change._route_to_request_migration_mapping[id(route)].append(by_path_converter)
+            else:
+                missing_methods.add(method)
+
+        if missing_methods:
+            raise RouteByPathConverterDoesNotApplyToAnythingError(
+                f"{by_path_converter.repr_name} "
+                f'"{version_change.__name__}.{by_path_converter.transformer.__name__}" '
+                f"failed to find routes with the following methods: {list(missing_methods)}. "
+                f"This means that you are trying to apply this converter to non-existing endpoint(s). "
+                "Please, check whether the path and methods are correct. (hint: path must include "
+                "all path variables and have a name that was used in the version that this "
+                "VersionChange resides in)"
+            )
 
-        for route in router.routes:
+    def _extract_all_routes_identifiers_for_route_to_converter_matching(
+        self, router: APIRouter
+    ) -> tuple[dict[_RoutePath, dict[_RouteMethod, set[_RouteId]]], set[Any], set[Any]]:
+        # int is the index of the route in the router.routes list.
+        # So we essentially keep track of which routes have which response models and request bodies.
+        # and their indices in the router.routes list. The indices will allow us to match them to the same
+        # routes in the head version. This gives us the ability to later apply changes to these routes
+        # without thinking about any renamings or response model changes.
+
+        response_models = set()
+        request_bodies = set()
+        path_to_route_methods_mapping: dict[str, dict[str, set[int]]] = defaultdict(lambda: defaultdict(set))
+
+        for index, route in enumerate(router.routes):
             if isinstance(route, APIRoute):
                 if route.response_model is not None and lenient_issubclass(route.response_model, BaseModel):
                     response_models.add(route.response_model)
@@ -265,7 +298,8 @@ class _EndpointTransformer(Generic[_R, _WR]):
                     annotation = route.body_field.field_info.annotation
                     if annotation is not None and lenient_issubclass(annotation, BaseModel):
                         request_bodies.add(annotation)
-                path_to_route_methods_mapping[route.path] |= route.methods
+                for method in route.methods:
+                    path_to_route_methods_mapping[route.path][method].add(index)
 
         head_response_models = {model.__cadwyn_original_model__ for model in response_models}
         head_request_bodies = {getattr(body, "__cadwyn_original_model__", body) for body in request_bodies}

cadwyn/schema_generation.py

@@ -196,8 +196,7 @@ def migrate_response_body(
         response,
         current_version=version,
         head_response_model=latest_response_model,
-        path="\0\0\0",
-        method="GET",
+        head_route=None,
     )
 
     versioned_response_model: type[pydantic.BaseModel] = generate_versioned_models(versions)[str(version)][

cadwyn/structure/versions.py

@@ -53,6 +53,7 @@ _CADWYN_REQUEST_PARAM_NAME = "cadwyn_request_param"
 _CADWYN_RESPONSE_PARAM_NAME = "cadwyn_response_param"
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
+_RouteId = int
 
 PossibleInstructions: TypeAlias = Union[
     AlterSchemaSubInstruction, AlterEndpointSubInstruction, AlterEnumSubInstruction, SchemaHadInstruction, staticmethod
@@ -85,6 +86,8 @@ class VersionChange:
     alter_response_by_schema_instructions: ClassVar[dict[type, list[_AlterResponseBySchemaInstruction]]] = Sentinel
     alter_response_by_path_instructions: ClassVar[dict[str, list[_AlterResponseByPathInstruction]]] = Sentinel
     _bound_version_bundle: "Union[VersionBundle, None]"
+    _route_to_request_migration_mapping: ClassVar[dict[_RouteId, list[_AlterRequestByPathInstruction]]] = Sentinel
+    _route_to_response_migration_mapping: ClassVar[dict[_RouteId, list[_AlterResponseByPathInstruction]]] = Sentinel
 
     def __init_subclass__(cls, _abstract: bool = False) -> None:
         super().__init_subclass__()
@@ -96,6 +99,8 @@ class VersionChange:
         cls._extract_body_instructions_into_correct_containers()
         cls._check_no_subclassing()
         cls._bound_version_bundle = None
+        cls._route_to_request_migration_mapping = defaultdict(list)
+        cls._route_to_response_migration_mapping = defaultdict(list)
 
     @classmethod
     def _extract_body_instructions_into_correct_containers(cls):
@@ -358,7 +363,6 @@ class VersionBundle:
         self,
         body_type: Union[type[BaseModel], None],
         head_dependant: Dependant,
-        path: str,
         request: FastapiRequest,
         response: FastapiResponse,
         request_info: RequestInfo,
@@ -369,18 +373,17 @@ class VersionBundle:
         embed_body_fields: bool,
         background_tasks: Union[BackgroundTasks, None],
     ) -> dict[str, Any]:
-        method = request.method
-
         start = self.reversed_version_values.index(current_version)
+        head_route_id = id(head_route)
         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]:
                         instruction(request_info)
-                if path in version_change.alter_request_by_path_instructions:
-                    for instruction in version_change.alter_request_by_path_instructions[path]:
-                        if method in instruction.methods:  # pragma: no branch # safe branch to skip
-                            instruction(request_info)
+                if head_route_id in version_change._route_to_request_migration_mapping:
+                    for instruction in version_change._route_to_request_migration_mapping[head_route_id]:
+                        instruction(request_info)
+
         request.scope["headers"] = tuple((key.encode(), value.encode()) for key, value in request_info.headers.items())
         del request._headers
         # This gives us the ability to tell the user whether cadwyn is running its dependencies or FastAPI
@@ -406,10 +409,10 @@ class VersionBundle:
         self,
         response_info: ResponseInfo,
         current_version: VersionType,
-        head_response_model: type[BaseModel],
-        path: str,
-        method: str,
+        head_response_model: Union[type[BaseModel], None],
+        head_route: Union[APIRoute, None],
     ) -> ResponseInfo:
+        head_route_id = id(head_route)
         end = self.version_values.index(current_version)
         for v in self.versions[:end]:
             for version_change in v.changes:
@@ -420,10 +423,8 @@ class VersionBundle:
                         version_change.alter_response_by_schema_instructions[head_response_model]
                     )
 
-                if path in version_change.alter_response_by_path_instructions:
-                    for instruction in version_change.alter_response_by_path_instructions[path]:
-                        if method in instruction.methods:  # pragma: no branch # Safe branch to skip
-                            migrations_to_apply.append(instruction)  # noqa: PERF401
+                if head_route_id in version_change._route_to_response_migration_mapping:
+                    migrations_to_apply.extend(version_change._route_to_response_migration_mapping[head_route_id])
 
                 for migration in migrations_to_apply:
                     if response_info.status_code < 300 or migration.migrate_http_errors:
@@ -576,8 +577,7 @@ class VersionBundle:
             response_info,
             api_version,
             head_route.response_model,
-            route.path,
-            method,
+            head_route,
         )
         if isinstance(response_or_response_body, FastapiResponse):
             # a webserver (uvicorn for instance) calculates the body at the endpoint level.
@@ -671,7 +671,6 @@ class VersionBundle:
         new_kwargs = await self._migrate_request(
             head_body_field,
             head_dependant,
-            route.path,
             request,
             response,
             request_info,

{cadwyn-5.2.1.dist-info → cadwyn-5.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 5.2.1
+Version: 5.3.0
 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.2.1.dist-info → cadwyn-5.3.0.dist-info}/RECORD

@@ -4,15 +4,15 @@ cadwyn/_asts.py,sha256=QvqZmDdwH8U-Ocpj9vYR6MRrIANF8ugk9oZgAo76qLs,5223
 cadwyn/_importer.py,sha256=QV6HqODCG9K2oL4Vc15fAqL2-plMvUWw_cgaj4Ln4C8,1075
 cadwyn/_render.py,sha256=VAY2Twd_MfKaC8_X22AMIQd72_UHy87icdAbKL8hd90,5526
 cadwyn/_utils.py,sha256=q_mTtMKTNTDzqCza67XST-jaPSfuTgnFLmOe0dlGeYY,2295
-cadwyn/applications.py,sha256=xE-r96qSIWji6-mrpRhQVGTLHEvayfMDi0cRaIVPkds,20777
+cadwyn/applications.py,sha256=sHfsgjy1ofotIPyLmL4FCAXyuzpjRtYLTQPR1ds471w,21133
 cadwyn/changelogs.py,sha256=aBTlsZ8PQpw9t4sSyezNTYDs6CMPtzIGulgAHA1ELPs,19622
 cadwyn/dependencies.py,sha256=phUJ4Fy3UTegpOfDfHMjxsvASWo-1NQgwqphNnPdoVQ,241
 cadwyn/exceptions.py,sha256=8D1G7ewLrMF5jq7leald1g0ulcH9zQl8ufEK3b7HHAE,1749
-cadwyn/middleware.py,sha256=jWhuISMEMo7kYLMJ8y4wzso1SNSpaW7Zkxocqi9MLEA,4617
+cadwyn/middleware.py,sha256=4Ziq1ysnc8j5KmeZpsr9VJKllEFC8uYwXnG01I2FPR4,4853
 cadwyn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cadwyn/route_generation.py,sha256=Po9wC4IvLBgX6EodWH3JFzEO7j3ckoXmIKMO-ubCGcA,25194
+cadwyn/route_generation.py,sha256=RTZYfml03oKaNm_-SJX8N6PnafFXdsPpN0qEapHSzTw,27181
 cadwyn/routing.py,sha256=Ii6Qbgm9lGks1IAk-kDuIu_dX3FXsA77KSfGOFmLbgc,7604
-cadwyn/schema_generation.py,sha256=QK_G-G56S1brGTSpEGEE77tbifSi7IzwNK1oiVfMkPA,46850
+cadwyn/schema_generation.py,sha256=76T5MgfJHoQNfr_GdN5VVIUbGgA-KCV666r94jGSp0I,46830
 cadwyn/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cadwyn/_internal/context_vars.py,sha256=VcM8eAoSlvrIMFQhjZmjflV5o1yrPSEZZGkwOK4OSf4,378
 cadwyn/static/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -23,9 +23,9 @@ cadwyn/structure/data.py,sha256=NWURVnP_84VI2ugp9ppo0Ofyve3pVYjymF9K82Jh-SA,7791
 cadwyn/structure/endpoints.py,sha256=zUgzglNhBPnmWdJ03A8pFT4zPs_lj8nQ7c7Uo2d-ejU,6246
 cadwyn/structure/enums.py,sha256=4FCc9aniLE3VuWAVIacrNP_FWxTIUm9JkeeHA_zZdwQ,1254
 cadwyn/structure/schemas.py,sha256=O9yNw1OB0Qz-PvNB0FYlQm34gQsjyG2l9gg9x-RnJIY,10781
-cadwyn/structure/versions.py,sha256=XeaZo6fUjQ_u32JBSLDKcuHkWm_z3z2mB_4yTe_Hr84,34307
-cadwyn-5.2.1.dist-info/METADATA,sha256=HE7pZOYLsS3B8aW5VA-e5_-W1OxAE0T933Zy_0kDWco,4529
-cadwyn-5.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cadwyn-5.2.1.dist-info/entry_points.txt,sha256=mGX8wl-Xfhpr5M93SUmkykaqinUaYAvW9rtDSX54gx0,47
-cadwyn-5.2.1.dist-info/licenses/LICENSE,sha256=KeCWewiDQYpmSnzF-p_0YpoWiyDcUPaCuG8OWQs4ig4,1072
-cadwyn-5.2.1.dist-info/RECORD,,
+cadwyn/structure/versions.py,sha256=FNHhgqCVe9Q5TO5ZMOSJgR846mli4ubGLvNDUERyPYs,34447
+cadwyn-5.3.0.dist-info/METADATA,sha256=yiKkJUKdxCbsDG0c0TDFH8KgtK6OvTvoh9cnGcw6frw,4529
+cadwyn-5.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cadwyn-5.3.0.dist-info/entry_points.txt,sha256=mGX8wl-Xfhpr5M93SUmkykaqinUaYAvW9rtDSX54gx0,47
+cadwyn-5.3.0.dist-info/licenses/LICENSE,sha256=KeCWewiDQYpmSnzF-p_0YpoWiyDcUPaCuG8OWQs4ig4,1072
+cadwyn-5.3.0.dist-info/RECORD,,