cadwyn 4.6.0a1__tar.gz → 5.0.0a1__tar.gz

{cadwyn-4.6.0a1 → cadwyn-5.0.0a1}/.pre-commit-config.yaml

@@ -37,3 +37,8 @@ repos:
     hooks:
       - id: markdownlint
         args: ["--disable", "MD013"]
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.6.5
+    hooks:
+      - id: uv-lock

{cadwyn-4.6.0a1 → cadwyn-5.0.0a1}/CHANGELOG.md

@@ -5,11 +5,32 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [5.0.0]
+
+### Added
+
+* Support for URL path version prefixes instead of version headers. You can control it with the `api_version_location` argument of `cadwyn.Cadwyn`.
+* Support for arbitrary strings as versions. You can control the format of the version with the `api_version_format` argument of `cadwyn.Cadwyn`.
+* Extensibility of version picking logic with a new `VersionPickingMiddleware` class that you can pass to the `versioning_middleware_class` argument of `cadwyn.Cadwyn`.
+* `api_version_default_value` argument to `cadwyn.Cadwyn` to set a default version for unversioned requests. It can be a string or an async callable that returns a string.
+
+### Changed
+
+* `cadwyn.Version`, `cadwyn.VersionBundle`, and `cadwyn.VersionBundle.api_version_var` now store versions as strings instead of dates. Date types can still be passed to `cadwyn.Version` but there is no guarantee that they will be supported in the future. However, ISO dates with a string type are guaranteed to be supported.
+* Cadwyn's `api_version_header_name` argument is now deprecated in favor of `api_version_parameter_name`
+* `cadwyn.Cadwyn.add_header_versioned_routers` method is now deprecated in favor of `cadwyn.Cadwyn.generate_and_include_versioned_routers`. It will be removed in version 6.0.0
+
+## Removed
+
+* `HeaderVersioningMiddleware` in favor of `VersionPickingMiddleware` because we now support more than just headers
+
+## [4.6.0]
+
 ### Added
 
-* Added support for more field attributes in `schema.had()` and `schema.didnt_have()`: `field_title_generator`, `fail_fast`, `coerce_numbers_to_str`, `union_mode`, `allow_mutation`, `pattern`, `discriminator`
-* Added support for forwardrefs in body fields (for example, when you use `from __future__ import annotations` in the file with your routes)
-* Added support for forwardrefs in route dependencies
+* Support for more field attributes in `schema.had()` and `schema.didnt_have()`: `field_title_generator`, `fail_fast`, `coerce_numbers_to_str`, `union_mode`, `allow_mutation`, `pattern`, `discriminator`
+* Support for forwardrefs in body fields (for example, when you use `from __future__ import annotations` in the file with your routes)
+* Support for forwardrefs in route dependencies
 
 ## [4.5.0]
 

{cadwyn-4.6.0a1 → cadwyn-5.0.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 4.6.0a1
+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-4.6.0a1 → cadwyn-5.0.0a1}/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-4.6.0a1 → cadwyn-5.0.0a1}/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-4.6.0a1 → cadwyn-5.0.0a1}/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-4.6.0a1 → cadwyn-5.0.0a1}/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-5.0.0a1/cadwyn/middleware.py

@@ -0,0 +1,119 @@
+# 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
+import re
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from typing import Annotated, Any, Literal, Protocol
+
+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(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_pythonic_parameter_name,
+                inspect.Parameter.KEYWORD_ONLY,
+                annotation=Annotated[
+                    validation_data_type, fastapi_depends_class(openapi_examples={"default": {"value": default_value}})
+                ],
+            ),
+        ],
+    )
+    return api_version_dependency
+
+
+class VersionPickingMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        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_parameter_name = api_version_parameter_name
+        self._api_version_manager = api_version_manager
+        self.api_version_var = api_version_var
+        self.api_version_default_value = api_version_default_value
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ):
+        # 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 = 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.
+            # In date-based versioning with waterfalling, it makes sense.
+            response.headers[self.api_version_parameter_name] = api_version
+
+        return response

{cadwyn-4.6.0a1 → cadwyn-5.0.0a1}/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)