cadwyn 5.2.1__tar.gz → 5.3.0__tar.gz

{cadwyn-5.2.1 → cadwyn-5.3.0}/CHANGELOG.md

@@ -5,6 +5,18 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [5.3.0]
+
+### Added
+
+* `api_version_title` and `api_version_description` arguments to `Cadwyn` to allow customizing the API version parameter in the OpenAPI schema
+
+## [5.2.2]
+
+### Fixed
+
+* Whenever a route was migrated by path, we used the path and methods of the request. So if the request wanted "/v1/webhook_settings" and we renamed them to "/v1/webhook_subscriptions" -- all migrations for "/v1/webhook_subscriptions" would not get applied to any requests that wanted "/v1/webhook_settings". This effectively means that previously route renamings were incompatible with by path converters. Now we use the head route id instead of the path and methods of the request for matching so we always know which migrations to apply.
+
 ## [5.2.1]
 
 ### Fixed

{cadwyn-5.2.1 → cadwyn-5.3.0}/PKG-INFO

@@ -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 → cadwyn-5.3.0}/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-5.2.1 → cadwyn-5.3.0}/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-5.2.1 → cadwyn-5.3.0}/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-5.2.1 → cadwyn-5.3.0}/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-5.2.1 → cadwyn-5.3.0}/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/docs/concepts/where_to_put_the_version_and_how_to_format_it.md → cadwyn-5.3.0/docs/concepts/api_version_parameter.md

@@ -1,4 +1,4 @@
-# Where to put the version and how to format it
+# API Version Parameter
 
 Cadwyn adds another routing layer to FastAPI by default: by version parameter. This means that before FastAPI tries to route us to the correct route, Cadwyn will first decide on which version of the route to use based on a version parameter. Feel free to look at the example app with URL path version prefixes and arbitrary strings as versions [here](../how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md).
 
@@ -91,3 +91,21 @@ If the app has two versions: 2022-01-02 and 2022-01-05, and the request date par
 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 Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. 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.
+
+## API Version Parameter Title and Description
+
+You can pass a title and/or a description to `Cadwyn` constructor. They are equivalent to passing `title` and `description` to `fastapi.Path` or `fastapi.Header` constructors.
+
+```python
+app = Cadwyn(
+    ...,
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
+```
+
+## API Version Context Variables
+
+Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
+
+You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.

{cadwyn-5.2.1 → cadwyn-5.3.0}/docs/concepts/endpoint_migrations.md

@@ -1,10 +1,10 @@
 # Endpoint migrations
 
-Note that the endpoint constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- both of them are going to be changed as you would expect.
+Note that the `endpoint(...)` constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- both of them are going to be changed as you would expect.
 
 ## Defining endpoints that didn't exist in new versions
 
-If you had an endpoint in old version but do not have it in a new one, you must still define it but mark it as deleted.
+If you had an endpoint in an old version **but want to delete it in a new version**, you must still define it as usual with all your other endpoints but mark it as deleted.
 
 ```python
 @router.only_exists_in_older_versions
@@ -28,7 +28,7 @@ class MyChange(VersionChange):
 
 ## Defining endpoints that didn't exist in old versions
 
-If you have an endpoint in your new version that must not exist in older versions, you define it as usual and then mark it as "non-existing" in old versions:
+If you have an endpoint in your new version that must not exist in older versions for some reason, you define it as usual and then mark it as "non-existing" in old versions. Note that this is [not the recommended approach when adding new endpoints](../how_to/change_endpoints/index.md#add-a-new-endpoint).
 
 ```python
 from cadwyn import VersionChange, endpoint
@@ -58,6 +58,8 @@ class MyChange(VersionChange):
     )
 ```
 
+However, you only need to have a migration if it is a breaking change for your users.
+
 ### Dependency alteration warning
 
 Note that changing endpoint `dependencies` is only going to affect the initial validation. So Cadwyn will take your altered dependencies and run them on each request to the endpoint but ultimately your endpoint code is always going to use the HEAD version of your dependencies. So be careful.

{cadwyn-5.2.1 → cadwyn-5.3.0}/docs/concepts/schema_migrations.md

@@ -2,6 +2,8 @@
 
 All of the following instructions affect only openapi schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
 
+Please note that you only need to have a migration if it is a breaking change for your users. The scenarios below only describe "what you can do" but not "what you should do". For the "should", please refer to the [how-to docs](../how_to/change_openapi_schemas/add_field.md).
+
 ## Add a field to the older version
 
 ```python

{cadwyn-5.2.1 → cadwyn-5.3.0}/docs/concepts/version_changes.md

@@ -93,6 +93,8 @@ HEAD is very similar to your latest version with a few key differences:
 
 `VersionChange` classes describe each atomic group of business capabilities that you have altered in a version.
 
+Note, however, that you only need to have a migration if it is a breaking change for your users. If you add a new endpoint or add a new field to your response schema, you do not need to have a migration for it because your users' code will not break. So by not having a migration you automatically add this change to all versions.
+
 ### VersionChange.\_\_name\_\_
 
 The name of the version change, `RemoveTaxIDEndpoints`, describes what breaking change has happened. It must be a verb and it is the best resource for your new developers to quickly understand what happened between the versions. Do not be shy to use really long names -- it is better to have a long name than to create a misunderstanding. Avoid generic names such as `RefactorUserFields`. Better have an ugly name such as `RenameCreationDatetimeAndUpdateDatetimeToCreatedAtAndUpdatedAt` then to have a generic name such as `RefactorFields`. Because after just a few of such version changes, your versioning structure can become completely unreadable:

{cadwyn-5.2.1 → cadwyn-5.3.0}/docs/how_to/change_openapi_schemas/add_field.md

@@ -14,7 +14,7 @@ Now you have everything you need at your disposal: field `created_at` is availab
 
 Let's say we want our users to be able to specify a middle name but it is nullable. It is not a breaking change so no new version is necessary whether it is requests or responses.
 
-You just need to add a nullable `middle_name` field into `users.BaseUser`
+You just need to add a nullable `middle_name` field into `users.BaseUser` as if you were working with a barebones FastAPI app.
 
 ### Field is required
 
@@ -59,7 +59,6 @@ Let's say that our users had a field `country` that defaulted to `USA` but our p
     )
     ```
 
-
 That's it! Our old schemas will now contain a default but in HEAD country will be required. You might notice a weirdness: if we set a default in the old version, why would we also write a migration? That's because of a sad implementation detail of pydantic that [prevents us](../../concepts/schema_migrations.md#change-a-field-in-the-older-version) from using defaults from old versions.
 
 #### With incompatible default value in older versions
@@ -118,5 +117,4 @@ So we will make `phone` nullable in HEAD, then make it required in `latest`, and
     )
     ```
 
-
 See how we didn't remove the `phone` field from old versions? Instead, we allowed a nullable `phone` field to be passed into both old `UserResource` and old `UserCreateRequest`. This gives our users new functionality without needing to update their API version! It is one of the best parts of Cadwyn's approach: our users can get years worth of updates without switching their API version and without their integration getting broken.

{cadwyn-5.2.1 → cadwyn-5.3.0}/docs/how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md

@@ -3,7 +3,7 @@
 Cadwyn uses version headers with ISO dates by default for versioning. However, you can use any strings instead of ISO dates and/or you can use path version prefixes instead of version headers. Here's our quickstart tutorial example but using version numbers and path prefixes:
 
 Feel free to mix and match the API version formats and version locations as you see fit.
-But beware that Cadwyn does not support [version waterfalling](../concepts/where_to_put_the_version_and_how_to_format_it.md#api-version-waterfalling) for arbitrary strings as versions.
+But beware that Cadwyn does not support [version waterfalling](../concepts/api_version_parameter.md#api-version-waterfalling) for arbitrary strings as versions.
 
 ```python
 {! ./docs_src/how_to/version_with_path_and_numbers_instead_of_headers_and_dates/block001.py !}

{cadwyn-5.2.1 → cadwyn-5.3.0}/mkdocs.yml

@@ -119,8 +119,7 @@ nav:
       - "Endpoint migrations": "concepts/endpoint_migrations.md"
       - "Enum migrations": "concepts/enum_migrations.md"
       - "Schema migrations": "concepts/schema_migrations.md"
-      - "API Version parameter and context variables": "concepts/api_version_parameter_and_context_variables.md"
-      - "Where to put the version and how to format it": "concepts/where_to_put_the_version_and_how_to_format_it.md"
+      - "API Version parameter": "concepts/api_version_parameter.md"
       - "Changelogs": "concepts/changelogs.md"
       - "Testing": concepts/testing.md
   - "Contributing": "home/CONTRIBUTING.md"

{cadwyn-5.2.1 → cadwyn-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cadwyn"
-version = "5.2.1"
+version = "5.3.0"
 description = "Production-ready community-driven modern Stripe-like API versioning in FastAPI"
 authors = [{ name = "Stanislav Zmiev", email = "zmievsa@gmail.com" }]
 license = "MIT"

{cadwyn-5.2.1 → cadwyn-5.3.0}/ruff.toml

@@ -135,7 +135,7 @@ ignore = [
 ]
 
 [lint.mccabe]
-max-complexity = 14
+max-complexity = 15
 
 [format]
 quote-style = "double"

{cadwyn-5.2.1 → cadwyn-5.3.0}/tests/test_router_generation.py

@@ -20,11 +20,13 @@ from starlette.responses import FileResponse
 from typing_extensions import Any, NewType, TypeAlias, TypeAliasType, get_args
 
 from cadwyn import VersionBundle, VersionedAPIRouter
+from cadwyn.applications import Cadwyn
 from cadwyn.dependencies import current_dependency_solver
 from cadwyn.exceptions import CadwynError, RouterGenerationError, RouterPathParamsModifiedError
 from cadwyn.route_generation import generate_versioned_routers
 from cadwyn.schema_generation import generate_versioned_models
 from cadwyn.structure import Version, convert_request_to_next_version_for, endpoint, schema
+from cadwyn.structure.data import RequestInfo, ResponseInfo, convert_response_to_previous_version_for
 from cadwyn.structure.enums import enum
 from cadwyn.structure.versions import VersionChange
 from tests._data.unversioned_schema_dir import UnversionedSchema2
@@ -252,6 +254,50 @@ def test__endpoint_had_another_path_variable(
         )
 
 
+def test__endpoint_had__another_path_with_the_other_migration_at_the_same_time__should_require_old_name(
+    create_versioned_app: CreateVersionedApp,
+):
+    router = VersionedAPIRouter()
+
+    @router.post("/A")
+    async def test_endpoint_post(body: list[str]):
+        return body
+
+    @router.put("/A")
+    async def test_endpoint_put(body: list[str]):
+        return body
+
+    @convert_response_to_previous_version_for("/A", ["POST"])
+    def response_migration(response: ResponseInfo):
+        response.body.append("response")
+
+    @convert_request_to_next_version_for("/A", ["POST"])
+    def request_migration(request: RequestInfo):
+        request.body.append("request")
+
+    app = Cadwyn(
+        versions=VersionBundle(
+            Version(
+                "2001-01-01",
+                version_change(
+                    endpoint("/A", ["POST"]).had(path="/B"),
+                    request_migration=request_migration,
+                    response_migration=response_migration,
+                ),
+            ),
+            Version("2000-01-01"),
+        )
+    )
+    app.generate_and_include_versioned_routers(router)
+
+    with TestClient(app) as client:
+        assert client.post("/B", headers={"X-API-VERSION": "2000-01-01"}, json=[]).json() == ["request", "response"]
+        assert client.post("/A", headers={"X-API-VERSION": "2001-01-01"}, json=[]).json() == []
+
+        assert client.put("/A", headers={"X-API-VERSION": "2000-01-01"}, json=[]).json() == []
+        assert client.put("/A", headers={"X-API-VERSION": "2001-01-01"}, json=[]).json() == []
+
+
 def test__endpoint_had_dependencies(
     test_endpoint: Endpoint,
     test_path: str,

{cadwyn-5.2.1 → cadwyn-5.3.0}/tests/tutorial/main.py

@@ -123,9 +123,14 @@ async def get_user_addresses(user_id: uuid.UUID):
     return {"data": database_parody[f"addr_{user_id}"]}
 
 
-app = Cadwyn(versions=version_bundle, title="My amazing API")
+app = Cadwyn(
+    versions=version_bundle,
+    title="My amazing API",
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
 app.generate_and_include_versioned_routers(router)
 
 
 if __name__ == "__main__":
-    uvicorn.run(app)
+    uvicorn.run(app, port=8011)

{cadwyn-5.2.1 → cadwyn-5.3.0}/uv.lock

@@ -94,7 +94,7 @@ wheels = [
 
 [[package]]
 name = "cadwyn"
-version = "5.2.1"
+version = "5.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "backports-strenum", marker = "python_full_version < '3.11'" },

cadwyn-5.2.1/docs/concepts/api_version_parameter_and_context_variables.md

@@ -1,5 +0,0 @@
-# API Version parameter and context variables
-
-Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
-
-You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.