cadwyn 3.5.0__tar.gz → 3.6.0__tar.gz

{cadwyn-3.5.0 → cadwyn-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cadwyn
-Version: 3.5.0
+Version: 3.6.0
 Summary: Production-ready community-driven modern Stripe-like API versioning in FastAPI
 Home-page: https://github.com/zmievsa/cadwyn
 License: MIT

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/__init__.py

@@ -1,7 +1,7 @@
 import importlib.metadata
 
+from .applications import Cadwyn
 from .codegen import generate_code_for_versioned_packages
-from .main import Cadwyn
 from .routing import InternalRepresentationOf, VersionedAPIRouter, generate_versioned_routers
 from .structure import VersionBundle
 

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/_utils.py

@@ -1,6 +1,7 @@
 import functools
 import importlib
 import inspect
+import sys
 from collections.abc import Callable, Collection
 from pathlib import Path
 from types import ModuleType
@@ -40,10 +41,23 @@ def same_definition_as_in(t: _T) -> Callable[[Callable], _T]:
     return decorator
 
 
+@functools.cache
+def get_another_version_of_cls(
+    cls_from_old_version: type[Any], new_version_dir: Path, version_dirs: frozenset[Path] | tuple[Path, ...]
+):
+    # version_dir = /home/myuser/package/companies/v2021_01_01
+    module_from_old_version = sys.modules[cls_from_old_version.__module__]
+    try:
+        module = get_another_version_of_module(module_from_old_version, new_version_dir, version_dirs)
+    except ModuleIsNotVersionedError:
+        return cls_from_old_version
+    return getattr(module, cls_from_old_version.__name__)
+
+
 def get_another_version_of_module(
     module_from_old_version: ModuleType,
     new_version_dir: Path,
-    version_dirs: frozenset[Path],
+    version_dirs: frozenset[Path] | tuple[Path, ...],
 ):
     new_model_module_python_path = get_pythonpath_to_another_version_of_module(
         module_from_old_version,
@@ -56,7 +70,7 @@ def get_another_version_of_module(
 def get_pythonpath_to_another_version_of_module(
     module_from_old_version: ModuleType,
     new_version_dir: Path,
-    version_dirs: frozenset[Path],
+    version_dirs: frozenset[Path] | tuple[Path, ...],
 ) -> str:
     # ['package', 'companies', 'latest', 'schemas']
     #                           ^^^^^^

cadwyn-3.5.0/cadwyn/main.py → cadwyn-3.6.0/cadwyn/applications.py

@@ -1,6 +1,5 @@
 from collections.abc import Callable, Coroutine, Sequence
-from types import ModuleType
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from fastapi import APIRouter, routing
 from fastapi.datastructures import Default
@@ -14,16 +13,19 @@ from starlette.types import Lifespan
 from typing_extensions import Self
 from verselect import HeaderRoutingFastAPI
 
+from cadwyn.exceptions import CadwynError
 from cadwyn.routing import generate_versioned_routers
 from cadwyn.structure import VersionBundle
 
+if TYPE_CHECKING:
+    from types import ModuleType
+
 
 class Cadwyn(HeaderRoutingFastAPI):
     def __init__(
         self,
         *,
         versions: VersionBundle,
-        latest_schemas_package: ModuleType,
         api_version_header_name: str = "x-api-version",
         debug: bool = False,
         title: str = "FastAPI",
@@ -62,6 +64,16 @@ class Cadwyn(HeaderRoutingFastAPI):
         separate_input_output_schemas: bool = True,
         **extra: Any,
     ) -> None:
+        # TODO: Remove argument entirely in any major version.
+        self.versions = versions
+        latest_schemas_package = extra.pop("latest_schemas_package", None) or self.versions.latest_schemas_package
+        if latest_schemas_package is None:
+            raise CadwynError(
+                "VersionBundle.latest_schemas_package is None but is required for Cadwyn's correct functioning."
+            )
+        self.latest_schemas_package: ModuleType = latest_schemas_package
+        self.versions.latest_schemas_package = latest_schemas_package
+
         super().__init__(
             api_version_header_name=api_version_header_name,
             api_version_var=versions.api_version_var,
@@ -100,8 +112,6 @@ class Cadwyn(HeaderRoutingFastAPI):
             separate_input_output_schemas=separate_input_output_schemas,
             **extra,
         )
-        self.versions = versions
-        self.latest_schemas_package = latest_schemas_package
 
     def generate_and_include_versioned_routers(self, *routers: APIRouter) -> None:
         root_router = APIRouter()

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/codegen/_common.py

@@ -6,7 +6,7 @@ from enum import Enum
 from functools import cache
 from pathlib import Path
 from types import ModuleType
-from typing import Any, Generic, Protocol, TypeAlias, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeAlias, TypeVar, cast
 
 from pydantic import BaseModel
 from typing_extensions import Self
@@ -14,9 +14,11 @@ from typing_extensions import Self
 from cadwyn._compat import PydanticFieldWrapper, model_fields
 from cadwyn._package_utils import IdentifierPythonPath
 from cadwyn.exceptions import CodeGenerationError
-from cadwyn.structure.versions import Version
 
-from ._asts import _ValidatorWrapper, get_validator_info_or_none
+if TYPE_CHECKING:
+    from cadwyn.structure.versions import Version
+
+from .._asts import _ValidatorWrapper, get_validator_info_or_none
 
 _FieldName: TypeAlias = str
 _CodegenPluginASTType = TypeVar("_CodegenPluginASTType", bound=ast.AST)
@@ -122,9 +124,9 @@ class _ModuleWrapper:
 
 @dataclasses.dataclass(slots=True, kw_only=True)
 class GlobalCodegenContext:
-    current_version: Version
-    latest_version: Version = dataclasses.field(init=False)
-    versions: list[Version]
+    current_version: "Version"
+    latest_version: "Version" = dataclasses.field(init=False)
+    versions: "list[Version]"
     schemas: dict[IdentifierPythonPath, PydanticModelWrapper] = dataclasses.field(repr=False)
     enums: dict[IdentifierPythonPath, _EnumWrapper] = dataclasses.field(repr=False)
     modules: dict[IdentifierPythonPath, _ModuleWrapper] = dataclasses.field(repr=False)

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/codegen/_main.py

@@ -10,9 +10,9 @@ from typing import Any
 
 import ast_comments
 
+from cadwyn._asts import get_all_names_defined_at_toplevel_of_module, read_python_module
 from cadwyn._package_utils import IdentifierPythonPath, get_package_path_from_module, get_version_dir_path
 from cadwyn._utils import get_index_of_latest_schema_dir_in_module_python_path
-from cadwyn.codegen._asts import get_all_names_defined_at_toplevel_of_module, read_python_module
 from cadwyn.codegen._common import (
     CodegenContext,
     CodegenPlugin,

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/codegen/_plugins/class_migrations.py

@@ -4,6 +4,7 @@ from typing import Annotated, Any, cast, get_args, get_origin
 
 from typing_extensions import assert_never
 
+from cadwyn._asts import add_keyword_to_call, delete_keyword_from_call, get_fancy_repr
 from cadwyn._compat import (
     PYDANTIC_V2,
     FieldInfo,
@@ -13,7 +14,6 @@ from cadwyn._compat import (
 )
 from cadwyn._package_utils import IdentifierPythonPath, get_cls_pythonpath
 from cadwyn._utils import Sentinel
-from cadwyn.codegen._asts import add_keyword_to_call, delete_keyword_from_call, get_fancy_repr
 from cadwyn.codegen._common import GlobalCodegenContext, PydanticModelWrapper, _EnumWrapper
 from cadwyn.exceptions import InvalidGenerationInstructionError
 from cadwyn.structure.enums import AlterEnumSubInstruction, EnumDidntHaveMembersInstruction, EnumHadMembersInstruction

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/codegen/_plugins/class_rebuilding.py

@@ -2,11 +2,11 @@ import ast
 import copy
 from typing import Any
 
-from cadwyn._package_utils import IdentifierPythonPath, get_absolute_python_path_of_import
-from cadwyn.codegen._asts import (
+from cadwyn._asts import (
     get_fancy_repr,
     pop_docstring_from_cls_body,
 )
+from cadwyn._package_utils import IdentifierPythonPath, get_absolute_python_path_of_import
 from cadwyn.codegen._common import CodegenContext, PydanticModelWrapper, _EnumWrapper
 
 

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/exceptions.py

@@ -1,3 +1,7 @@
+import json
+from datetime import date
+from typing import Any
+
 from fastapi.routing import APIRoute
 
 
@@ -5,6 +9,19 @@ class CadwynError(Exception):
     pass
 
 
+class CadwynLatestRequestValidationError(CadwynError):
+    def __init__(self, errors: list[Any], body: Any, version: date) -> None:
+        self.errors = errors
+        self.body = body
+        self.version = version
+        super().__init__(
+            f"We failed to migrate the request with version={self.version!s}. "
+            "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)}"
+        )
+
+
 class LintingError(CadwynError):
     pass
 

cadwyn-3.6.0/cadwyn/main.py

@@ -0,0 +1,11 @@
+from warnings import warn
+
+from .applications import Cadwyn
+
+warn(
+    "'cadwyn.main' module is deprecated. Please use 'cadwyn.applications' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = ["Cadwyn"]

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/routing.py

@@ -1,7 +1,6 @@
 import functools
 import inspect
 import re
-import sys
 import typing
 import warnings
 from collections import defaultdict
@@ -44,11 +43,10 @@ from starlette.routing import (
 from typing_extensions import Self, assert_never
 
 from cadwyn._compat import model_fields, rebuild_fastapi_body_param
-from cadwyn._package_utils import get_package_path_from_module, get_version_dir_path
-from cadwyn._utils import Sentinel, UnionType, get_another_version_of_module
+from cadwyn._package_utils import get_version_dir_path
+from cadwyn._utils import Sentinel, UnionType, get_another_version_of_cls
 from cadwyn.exceptions import (
     CadwynError,
-    ModuleIsNotVersionedError,
     RouteAlreadyExistsError,
     RouterGenerationError,
     RouterPathParamsModifiedError,
@@ -381,8 +379,8 @@ def _validate_no_repetitions_in_routes(routes: list[fastapi.routing.APIRoute]):
 @final
 class _AnnotationTransformer:
     __slots__ = (
+        "versions",
         "latest_schemas_package",
-        "version_dirs",
         "template_version_dir",
         "latest_version_dir",
         "change_versions_of_a_non_container_annotation",
@@ -398,16 +396,14 @@ class _AnnotationTransformer:
                 'The name of the latest schemas module must be "latest". '
                 f'Received "{latest_schemas_package.__name__}" instead.',
             )
+        self.versions = versions
+        self.versions.latest_schemas_package = latest_schemas_package
         self.latest_schemas_package = latest_schemas_package
-        self.version_dirs = frozenset(
-            [get_package_path_from_module(latest_schemas_package)]
-            + [get_version_dir_path(latest_schemas_package, version.value) for version in versions],
-        )
         # Okay, the naming is confusing, I know. Essentially template_version_dir is a dir of
         # latest_schemas_package while latest_version_dir is a version equivalent to latest but
         # with its own directory. Pick a better naming and make a PR, I am at your mercy.
-        self.template_version_dir = min(self.version_dirs)  # "latest" < "v0000_00_00"
-        self.latest_version_dir = max(self.version_dirs)  # "v2005_11_11" > "v2000_11_11"
+        self.template_version_dir = min(versions.versioned_directories)  # "latest" < "v0000_00_00"
+        self.latest_version_dir = max(versions.versioned_directories)  # "v2005_11_11" > "v2000_11_11"
 
         # This cache is not here for speeding things up. It's for preventing the creation of copies of the same object
         # because such copies could produce weird behaviors at runtime, especially if you/fastapi do any comparisons.
@@ -450,15 +446,6 @@ class _AnnotationTransformer:
             self.migrate_route_to_version(callback, version_dir, ignore_response_model=ignore_response_model)
         _remake_endpoint_dependencies(route)
 
-    def get_another_version_of_cls(self, cls_from_old_version: type[Any], new_version_dir: Path):
-        # version_dir = /home/myuser/package/companies/v2021_01_01
-        module_from_old_version = sys.modules[cls_from_old_version.__module__]
-        try:
-            module = get_another_version_of_module(module_from_old_version, new_version_dir, self.version_dirs)
-        except ModuleIsNotVersionedError:
-            return cls_from_old_version
-        return getattr(module, cls_from_old_version.__name__)
-
     def _change_versions_of_a_non_container_annotation(self, annotation: Any, version_dir: Path) -> Any:
         if isinstance(annotation, _BaseGenericAlias | GenericAlias):
             return get_origin(annotation)[
@@ -526,7 +513,7 @@ class _AnnotationTransformer:
                     )
                 else:
                     self._validate_source_file_is_located_in_template_dir(annotation, source_file)
-            return self.get_another_version_of_cls(annotation, version_dir)
+            return get_another_version_of_cls(annotation, version_dir, self.versions.versioned_directories)
         else:
             return annotation
 
@@ -539,7 +526,7 @@ class _AnnotationTransformer:
         if (
             source_file.startswith(dir_with_versions)
             and not source_file.startswith(template_dir)
-            and any(source_file.startswith(str(d)) for d in self.version_dirs)
+            and any(source_file.startswith(str(d)) for d in self.versions.versioned_directories)
         ):
             raise RouterGenerationError(
                 f'"{annotation}" is not defined in "{self.template_version_dir}" even though it must be. '

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/structure/schemas.py

@@ -8,9 +8,9 @@ from typing import TYPE_CHECKING, Any, Literal
 from pydantic import BaseModel, Field
 from pydantic.fields import FieldInfo
 
+from cadwyn._asts import _ValidatorWrapper, get_validator_info_or_none
 from cadwyn._compat import PYDANTIC_V2
 from cadwyn._utils import Sentinel
-from cadwyn.codegen._asts import _ValidatorWrapper, get_validator_info_or_none
 from cadwyn.exceptions import CadwynStructureError
 
 if TYPE_CHECKING:
@@ -227,7 +227,7 @@ class AlterFieldInstructionFactory:
 class ValidatorExistedInstruction:
     schema: type[BaseModel]
     validator: Callable[..., Any]
-    validator_info: _ValidatorWrapper = field(init=False)
+    validator_info: "_ValidatorWrapper" = field(init=False)
 
     def __post_init__(self):
         source = textwrap.dedent(inspect.getsource(self.validator))

{cadwyn-3.5.0 → cadwyn-3.6.0}/cadwyn/structure/versions.py

@@ -7,6 +7,7 @@ from collections.abc import Callable, Sequence
 from contextlib import AsyncExitStack
 from contextvars import ContextVar
 from enum import Enum
+from pathlib import Path
 from types import ModuleType
 from typing import Any, ClassVar, ParamSpec, TypeAlias, TypeVar, cast
 
@@ -26,9 +27,14 @@ from starlette._utils import is_async_callable
 from typing_extensions import assert_never
 
 from cadwyn._compat import PYDANTIC_V2, ModelField, PydanticUndefined, model_dump
-from cadwyn._package_utils import IdentifierPythonPath, get_cls_pythonpath
-from cadwyn._utils import classproperty
-from cadwyn.exceptions import CadwynError, CadwynStructureError
+from cadwyn._package_utils import (
+    IdentifierPythonPath,
+    get_cls_pythonpath,
+    get_package_path_from_module,
+    get_version_dir_path,
+)
+from cadwyn._utils import classproperty, get_another_version_of_cls
+from cadwyn.exceptions import CadwynError, CadwynLatestRequestValidationError, CadwynStructureError
 
 from .._utils import Sentinel
 from .common import Endpoint, VersionDate, VersionedModel
@@ -224,10 +230,13 @@ class VersionBundle:
         /,
         *other_versions: Version,
         api_version_var: APIVersionVarType | None = None,
+        latest_schemas_package: ModuleType | None = None,
     ) -> None:
         super().__init__()
 
+        self.latest_schemas_package: ModuleType | None = latest_schemas_package
         self.versions = (latest_version, *other_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.api_version_var = api_version_var
@@ -292,6 +301,47 @@ class VersionBundle:
             for instruction in version_change.alter_module_instructions
         }
 
+    @functools.cached_property
+    def versioned_directories(self) -> tuple[Path, ...]:
+        if self.latest_schemas_package is None:
+            raise CadwynError(
+                f"You cannot call 'VersionBundle.{self.migrate_response_body.__name__}' because it has no access to "
+                "'latest_schemas_package'. It likely means that it was not attached "
+                "to any Cadwyn application which attaches 'latest_schemas_package' during initialization."
+            )
+        return tuple(
+            [get_package_path_from_module(self.latest_schemas_package)]
+            + [get_version_dir_path(self.latest_schemas_package, version.value) for version in self]
+        )
+
+    def migrate_response_body(self, latest_response_model: type[BaseModel], *, latest_body: Any, version: VersionDate):
+        """Convert the data to a specific version by applying all version changes from latest until that version
+        in reverse order and wrapping the result in the correct version of latest_response_model.
+        """
+        response = ResponseInfo(FastapiResponse(status_code=200), body=latest_body)
+        migrated_response = self._migrate_response(
+            response,
+            current_version=version,
+            latest_response_model=latest_response_model,
+            path="\0\0\0",
+            method="GET",
+        )
+
+        version = self._get_closest_lesser_version(version)
+        # + 1 comes from latest also being in the versioned_directories list
+        version_dir = self.versioned_directories[self.version_dates.index(version) + 1]
+
+        versioned_response_model: type[BaseModel] = get_another_version_of_cls(
+            latest_response_model, version_dir, self.versioned_directories
+        )
+        return versioned_response_model.parse_obj(migrated_response.body)
+
+    def _get_closest_lesser_version(self, version: VersionDate):
+        for defined_version in self.version_dates:
+            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,
@@ -341,7 +391,9 @@ class VersionBundle:
                 **kwargs,
             )
             if errors:
-                raise RequestValidationError(_normalize_errors(errors), body=request_info.body)
+                raise CadwynLatestRequestValidationError(
+                    _normalize_errors(errors), body=request_info.body, version=current_version
+                )
             return dependencies
         raise NotImplementedError("This code should not be reachable. If it was reached -- it's a bug.")
 
@@ -349,7 +401,7 @@ class VersionBundle:
         self,
         response_info: ResponseInfo,
         current_version: VersionDate,
-        latest_route: APIRoute,
+        latest_response_model: type[BaseModel],
         path: str,
         method: str,
     ) -> ResponseInfo:
@@ -371,11 +423,11 @@ class VersionBundle:
                 migrations_to_apply: list[_BaseAlterResponseInstruction] = []
 
                 if (
-                    latest_route.response_model
-                    and latest_route.response_model in version_change.alter_response_by_schema_instructions
+                    latest_response_model
+                    and latest_response_model in version_change.alter_response_by_schema_instructions
                 ):
                     migrations_to_apply.append(
-                        version_change.alter_response_by_schema_instructions[latest_route.response_model]
+                        version_change.alter_response_by_schema_instructions[latest_response_model]
                     )
 
                 if path in version_change.alter_response_by_path_instructions:
@@ -485,7 +537,7 @@ class VersionBundle:
 
             response_info = ResponseInfo(response_or_response_body, body)
         else:
-            if fastapi_response_dependency.status_code is not None:
+            if fastapi_response_dependency.status_code is not None:  # pyright: ignore[reportUnnecessaryComparison]
                 status_code = fastapi_response_dependency.status_code
             elif route.status_code is not None:
                 status_code = route.status_code
@@ -507,7 +559,7 @@ class VersionBundle:
         response_info = self._migrate_response(
             response_info,
             api_version,
-            latest_route,
+            latest_route.response_model,
             route.path,
             method,
         )
@@ -574,7 +626,7 @@ class VersionBundle:
                 body = raw_body
             else:
                 body = model_dump(raw_body, by_alias=True, exclude_unset=True)
-                if not PYDANTIC_V2 and raw_body.__custom_root_type__:  # pyright: ignore[reportGeneralTypeIssues]
+                if not PYDANTIC_V2 and raw_body.__custom_root_type__:  # pyright: ignore[reportAttributeAccessIssue]
                     body = body["__root__"]
         else:
             # This is for requests without body or with complex body such as form or file

{cadwyn-3.5.0 → cadwyn-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cadwyn"
-version = "3.5.0"
+version = "3.6.0"
 description = "Production-ready community-driven modern Stripe-like API versioning in FastAPI"
 authors = ["Stanislav Zmiev <zmievsa@gmail.com>"]
 license = "MIT"
@@ -130,6 +130,7 @@ reportUnsupportedDunderAll = true
 reportUnnecessaryTypeIgnoreComment = true
 reportMissingSuperCall = true
 reportFunctionMemberAccess = false
+reportCircularImports = true
 
 
 [tool.ruff]