cadwyn 3.15.10__tar.gz → 4.0.0__tar.gz

{cadwyn-3.15.10 → cadwyn-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cadwyn
-Version: 3.15.10
+Version: 4.0.0
 Summary: Production-ready community-driven modern Stripe-like API versioning in FastAPI
 Home-page: https://github.com/zmievsa/cadwyn
 License: MIT
@@ -32,12 +32,11 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Provides-Extra: cli
-Requires-Dist: better-ast-comments (>=1.2.1,<1.3.0)
-Requires-Dist: fastapi (>=0.115.2)
+Requires-Dist: fastapi (>=0.110.0)
 Requires-Dist: issubclass (>=0.1.2,<0.2.0)
 Requires-Dist: jinja2 (>=3.1.2)
-Requires-Dist: pydantic (>=1.0.0)
-Requires-Dist: starlette (>=0.36.3)
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: starlette (>=0.30.0)
 Requires-Dist: typer (>=0.7.0) ; extra == "cli"
 Requires-Dist: typing-extensions
 Project-URL: Documentation, https://docs.cadwyn.dev

cadwyn-4.0.0/cadwyn/__init__.py

@@ -0,0 +1,39 @@
+import importlib.metadata
+
+from .applications import Cadwyn
+from .route_generation import VersionedAPIRouter, generate_versioned_routers
+from .schema_generation import migrate_response_body
+from .structure import (
+    HeadVersion,
+    RequestInfo,
+    ResponseInfo,
+    Version,
+    VersionBundle,
+    VersionChange,
+    VersionChangeWithSideEffects,
+    convert_request_to_next_version_for,
+    convert_response_to_previous_version_for,
+    endpoint,
+    enum,
+    schema,
+)
+
+__version__ = importlib.metadata.version("cadwyn")
+__all__ = [
+    "Cadwyn",
+    "VersionedAPIRouter",
+    "VersionBundle",
+    "HeadVersion",
+    "Version",
+    "migrate_response_body",
+    "generate_versioned_routers",
+    "VersionChange",
+    "VersionChangeWithSideEffects",
+    "endpoint",
+    "schema",
+    "enum",
+    "convert_response_to_previous_version_for",
+    "convert_request_to_next_version_for",
+    "RequestInfo",
+    "ResponseInfo",
+]

cadwyn-4.0.0/cadwyn/__main__.py

@@ -0,0 +1,78 @@
+from datetime import date
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+
+from cadwyn._render import render_model_by_path, render_module_by_path
+
+_CONSOLE = Console()
+_RAW_ARG = Annotated[bool, typer.Option(help="Output code without color")]
+
+app = typer.Typer(
+    name="cadwyn",
+    add_completion=False,
+    help="Modern Stripe-like API versioning in FastAPI",
+)
+
+render_subapp = typer.Typer(
+    name="render",
+    add_completion=False,
+    help="Render pydantic models and enums from a certainn version and output them to stdout",
+)
+
+app.add_typer(render_subapp)
+
+
+def version_callback(value: bool):
+    if value:
+        from . import __version__
+
+        typer.echo(f"Cadwyn {__version__}")
+        raise typer.Exit
+
+
+def output_code(code: str, raw: bool):
+    if raw:
+        typer.echo(code)
+    else:
+        _CONSOLE.print(Syntax(code, "python", line_numbers=True))
+
+
+@render_subapp.command(
+    name="model",
+    help="Render a concrete pydantic model or enum from a certain version and output it to stdout",
+    short_help="Render a single model or enum",
+)
+def render(
+    model: Annotated[str, typer.Argument(metavar="<module>:<attribute>", help="Python path to the model to render")],
+    app: Annotated[str, typer.Option(metavar="<module>:<attribute>", help="Python path to the main Cadwyn app")],
+    version: Annotated[str, typer.Option(parser=lambda s: str(date.fromisoformat(s)), metavar="ISO-VERSION")],
+    raw: _RAW_ARG = False,
+) -> None:
+    output_code(render_model_by_path(model, app, version), raw)
+
+
+@render_subapp.command(
+    name="module",
+    help="Render all versioned models and enums within a module from a certain version and output them to stdout",
+    short_help="Render all models and enums from an entire module",
+)
+def render_module(
+    module: Annotated[str, typer.Argument(metavar="<module>", help="Python path to the module to render")],
+    app: Annotated[str, typer.Option(metavar="<module>:<attribute>", help="Python path to the main Cadwyn app")],
+    version: Annotated[str, typer.Option(parser=lambda s: str(date.fromisoformat(s)), metavar="ISO-VERSION")],
+    raw: _RAW_ARG = False,
+) -> None:
+    output_code(render_module_by_path(module, app, version), raw)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(None, "-V", "--version", callback=version_callback, is_eager=True),
+): ...
+
+
+if __name__ == "__main__":
+    app()

cadwyn-4.0.0/cadwyn/_asts.py

@@ -0,0 +1,150 @@
+import ast
+import inspect
+from collections.abc import Callable
+from enum import Enum, auto
+from types import GenericAlias, LambdaType, NoneType
+from typing import (  # noqa: UP035
+    Any,
+    List,
+    cast,
+    get_args,
+    get_origin,
+)
+
+import annotated_types
+
+from cadwyn._utils import PlainRepr, UnionType
+from cadwyn.exceptions import InvalidGenerationInstructionError
+
+_LambdaFunctionName = (lambda: None).__name__  # pragma: no branch
+
+
+# A parent type of typing._GenericAlias
+_BaseGenericAlias = cast(type, type(List[int])).mro()[1]  # noqa: UP006
+
+# type(list[int]) and type(List[int]) are different which is why we have to do this.
+# Please note that this problem is much wider than just lists which is why we use typing._BaseGenericAlias
+# instead of typing._GenericAlias.
+GenericAliasUnion = GenericAlias | _BaseGenericAlias
+
+
+def get_fancy_repr(value: Any):
+    if isinstance(value, annotated_types.GroupedMetadata) and hasattr(type(value), "__dataclass_fields__"):
+        return transform_grouped_metadata(value)
+    if isinstance(value, list | tuple | set | frozenset):
+        return transform_collection(value)
+    if isinstance(value, dict):
+        return transform_dict(value)
+    if isinstance(value, GenericAliasUnion):
+        return transform_generic_alias(value)
+    if value is None or value is NoneType:
+        return transform_none(value)
+    if isinstance(value, type):
+        return transform_type(value)
+    if isinstance(value, Enum):
+        return transform_enum(value)
+    if isinstance(value, auto):  # pragma: no cover # it works but we no longer use auto
+        return transform_auto(value)
+    if isinstance(value, UnionType):
+        return transform_union(value)
+    if isinstance(value, LambdaType) and _LambdaFunctionName == value.__name__:
+        return transform_lambda(value)
+    if inspect.isfunction(value):
+        return transform_function(value)
+    else:
+        return transform_other(value)
+
+
+def transform_grouped_metadata(value: "annotated_types.GroupedMetadata"):
+    modified_fields = []
+    empty_obj = type(value)
+
+    for key in empty_obj.__dataclass_fields__:  # pyright: ignore[reportAttributeAccessIssue]
+        if getattr(value, key) != getattr(empty_obj, key):
+            modified_fields.append((key, getattr(value, key)))
+
+    return PlainRepr(
+        value.__class__.__name__
+        + "("
+        + ", ".join(f"{PlainRepr(key)}={get_fancy_repr(v)}" for key, v in modified_fields)
+        + ")",
+    )
+
+
+def transform_collection(value: list | tuple | set | frozenset) -> Any:
+    return PlainRepr(value.__class__(map(get_fancy_repr, value)))
+
+
+def transform_dict(value: dict) -> Any:
+    return PlainRepr(
+        value.__class__((get_fancy_repr(k), get_fancy_repr(v)) for k, v in value.items()),
+    )
+
+
+def transform_generic_alias(value: GenericAliasUnion) -> Any:
+    return f"{get_fancy_repr(get_origin(value))}[{', '.join(get_fancy_repr(a) for a in get_args(value))}]"
+
+
+def transform_none(_: NoneType) -> Any:
+    return "None"
+
+
+def transform_type(value: type) -> Any:
+    return value.__name__
+
+
+def transform_enum(value: Enum) -> Any:
+    return PlainRepr(f"{value.__class__.__name__}.{value.name}")
+
+
+def transform_auto(_: auto) -> Any:  # pragma: no cover # it works but we no longer use auto
+    return PlainRepr("auto()")
+
+
+def transform_union(value: UnionType) -> Any:
+    return "typing.Union[" + (", ".join(get_fancy_repr(a) for a in get_args(value))) + "]"
+
+
+def transform_lambda(value: LambdaType) -> Any:
+    # We clean source because getsource() can return only a part of the expression which
+    # on its own is not a valid expression such as: "\n  .had(default_factory=lambda: 91)"
+    return _get_lambda_source_from_default_factory(inspect.getsource(value).strip(" \n\t."))
+
+
+def transform_function(value: Callable) -> Any:
+    return PlainRepr(value.__name__)
+
+
+def transform_other(value: Any) -> Any:
+    return PlainRepr(repr(value))
+
+
+def _get_lambda_source_from_default_factory(source: str) -> str:
+    found_lambdas: list[ast.Lambda] = []
+
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.keyword) and node.arg == "default_factory" and isinstance(node.value, ast.Lambda):
+            found_lambdas.append(node.value)
+    if len(found_lambdas) == 1:
+        return ast.unparse(found_lambdas[0])
+    # These two errors are really hard to cover. Not sure if even possible, honestly :)
+    elif len(found_lambdas) == 0:  # pragma: no cover
+        raise InvalidGenerationInstructionError(
+            f"No lambda found in default_factory even though one was passed: {source}",
+        )
+    else:  # pragma: no cover
+        raise InvalidGenerationInstructionError(
+            "More than one lambda found in default_factory. This is not supported.",
+        )
+
+
+def pop_docstring_from_cls_body(cls_body: list[ast.stmt]) -> list[ast.stmt]:
+    if (
+        len(cls_body) > 0
+        and isinstance(cls_body[0], ast.Expr)
+        and isinstance(cls_body[0].value, ast.Constant)
+        and isinstance(cls_body[0].value.value, str)
+    ):
+        return [cls_body.pop(0)]
+    else:
+        return []

cadwyn-4.0.0/cadwyn/_importer.py

@@ -0,0 +1,31 @@
+import importlib
+from typing import Any
+
+from cadwyn.exceptions import ImportFromStringError
+
+
+def import_attribute_from_string(import_str: str) -> Any:
+    module_str, _, attrs_str = import_str.partition(":")
+    if not module_str or not attrs_str:
+        message = 'Import string "{import_str}" must be in format "<module>:<attribute>".'
+        raise ImportFromStringError(message.format(import_str=import_str))
+
+    module = import_module_from_string(module_str)
+
+    instance = module
+    try:
+        for attr_str in attrs_str.split("."):
+            instance = getattr(instance, attr_str)
+    except AttributeError as e:
+        raise ImportFromStringError(f'Attribute "{attrs_str}" not found in module "{module_str}".') from e
+
+    return instance
+
+
+def import_module_from_string(module_str: str):
+    try:
+        return importlib.import_module(module_str)
+    except ModuleNotFoundError as e:
+        if e.name != module_str:  # pragma: no cover
+            raise e from None
+        raise ImportFromStringError(f'Could not import module "{module_str}".') from e

cadwyn-4.0.0/cadwyn/_render.py

@@ -0,0 +1,152 @@
+import ast
+import inspect
+import textwrap
+from enum import Enum
+from typing import TYPE_CHECKING
+
+import typer
+from issubclass import issubclass as lenient_issubclass
+from pydantic import BaseModel
+
+from cadwyn._asts import get_fancy_repr, pop_docstring_from_cls_body
+from cadwyn.exceptions import CadwynRenderError
+from cadwyn.schema_generation import (
+    PydanticFieldWrapper,
+    _EnumWrapper,
+    _generate_versioned_models,
+    _PydanticRuntimeModelWrapper,
+)
+from cadwyn.structure.versions import VersionBundle, get_cls_pythonpath
+
+from ._importer import import_attribute_from_string, import_module_from_string
+
+if TYPE_CHECKING:
+    from cadwyn.applications import Cadwyn
+
+
+def render_module_by_path(module_path: str, app_path: str, version: str):
+    module = import_module_from_string(module_path)
+    app: Cadwyn = import_attribute_from_string(app_path)
+    attributes_to_alter = [
+        name
+        for name, value in module.__dict__.items()
+        if lenient_issubclass(value, Enum | BaseModel) and value.__module__ == module.__name__
+    ]
+
+    try:
+        module_ast = ast.parse(inspect.getsource(module))
+    except (OSError, SyntaxError, ValueError) as e:  # pragma: no cover
+        raise CadwynRenderError(f"Failed to find the source for module {module.__name__}") from e
+
+    return ast.unparse(
+        ast.Module(
+            body=[
+                _render_model_from_ast(node, getattr(module, node.name), app.versions, version)
+                if isinstance(node, ast.ClassDef) and node.name in attributes_to_alter
+                else node
+                for node in module_ast.body
+            ],
+            type_ignores=module_ast.type_ignores,
+        )
+    )
+
+
+def render_model_by_path(model_path: str, app_path: str, version: str) -> str:
+    # cadwyn render model schemas:MySchema --app=run:app --version=2000-01-01
+    model: type[BaseModel | Enum] = import_attribute_from_string(model_path)
+    app: Cadwyn = import_attribute_from_string(app_path)
+    return render_model(model, app.versions, version)
+
+
+def render_model(model: type[BaseModel | Enum], versions: VersionBundle, version: str) -> str:
+    try:
+        original_cls_node = ast.parse(textwrap.dedent(inspect.getsource(model))).body[0]
+    except (OSError, SyntaxError, ValueError):  # pragma: no cover
+        typer.echo(f"Failed to find the source for model {get_cls_pythonpath(model)}")
+        return f"class {model.__name__}: 'failed to find the original class source'"
+    if not isinstance(original_cls_node, ast.ClassDef):
+        raise TypeError(f"{get_cls_pythonpath(model)} is not a class")
+
+    return ast.unparse(_render_model_from_ast(original_cls_node, model, versions, version))
+
+
+def _render_model_from_ast(
+    model_ast: ast.ClassDef, model: type[BaseModel | Enum], versions: VersionBundle, version: str
+):
+    versioned_models = _generate_versioned_models(versions)
+    generator = versioned_models[version]
+    wrapper = generator._get_wrapper_for_model(model)
+
+    if isinstance(wrapper, _EnumWrapper):
+        return _render_enum_model(wrapper, model_ast)
+    else:
+        return _render_pydantic_model(wrapper, model_ast)
+
+
+def _render_enum_model(wrapper: _EnumWrapper, original_cls_node: ast.ClassDef):
+    # This is for possible schema renaming
+    original_cls_node.name = wrapper.cls.__name__
+
+    new_body = [
+        ast.Assign(
+            targets=[ast.Name(member, ctx=ast.Store())],
+            value=ast.Name(get_fancy_repr(member_value)),
+            lineno=0,
+        )
+        for member, member_value in wrapper.members.items()
+    ]
+
+    old_body = [
+        n for n in original_cls_node.body if not isinstance(n, ast.AnnAssign | ast.Assign | ast.Pass | ast.Constant)
+    ]
+    docstring = pop_docstring_from_cls_body(old_body)
+
+    original_cls_node.body = docstring + new_body + old_body
+    if not original_cls_node.body:
+        original_cls_node.body = [ast.Pass()]
+    return original_cls_node
+
+
+def _render_pydantic_model(wrapper: _PydanticRuntimeModelWrapper, original_cls_node: ast.ClassDef):
+    # This is for possible schema renaming
+    original_cls_node.name = wrapper.name
+
+    field_definitions = [
+        ast.AnnAssign(
+            target=ast.Name(name),
+            annotation=ast.Name(get_fancy_repr(field.annotation)),
+            value=_generate_field_ast(field),
+            simple=1,
+        )
+        for name, field in wrapper.fields.items()
+    ]
+    validator_definitions = [
+        ast.parse(textwrap.dedent(inspect.getsource(validator.func))).body[0]
+        for validator in wrapper.validators.values()
+        if not validator.is_deleted
+    ]
+
+    old_body = [
+        n
+        for n in original_cls_node.body
+        if not (
+            isinstance(n, ast.AnnAssign | ast.Assign | ast.Pass | ast.Constant)
+            or (isinstance(n, ast.FunctionDef) and n.name in wrapper.validators)
+        )
+    ]
+    docstring = pop_docstring_from_cls_body(old_body)
+    original_cls_node.body = docstring + field_definitions + validator_definitions + old_body
+    if not original_cls_node.body:
+        original_cls_node.body = [ast.Pass()]
+    return original_cls_node
+
+
+def _generate_field_ast(field: PydanticFieldWrapper) -> ast.Call:
+    return ast.Call(
+        func=ast.Name("Field"),
+        args=[],
+        keywords=[
+            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.0.0/cadwyn/_utils.py

@@ -0,0 +1,42 @@
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar, Union
+
+from pydantic._internal._decorators import unwrap_wrapped_function
+
+Sentinel: Any = object()
+UnionType = type(int | str) | type(Union[int, str])
+_T = TypeVar("_T", bound=Callable)
+
+
+_P_T = TypeVar("_P_T")
+_P_R = TypeVar("_P_R")
+
+
+class classproperty(Generic[_P_T, _P_R]):  # noqa: N801
+    def __init__(self, func: Callable[[_P_T], _P_R]) -> None:
+        super().__init__()
+        self.func = func
+
+    def __get__(self, obj: Any, cls: _P_T) -> _P_R:
+        return self.func(cls)
+
+
+class PlainRepr(str):
+    """String class where repr doesn't include quotes"""
+
+    def __repr__(self) -> str:
+        return str(self)
+
+
+def same_definition_as_in(t: _T) -> Callable[[Callable], _T]:
+    def decorator(f: Callable) -> _T:
+        return f  # pyright: ignore[reportReturnType]
+
+    return decorator
+
+
+def fully_unwrap_decorator(func: Callable, is_pydantic_v1_style_validator: Any):
+    func = unwrap_wrapped_function(func)
+    if is_pydantic_v1_style_validator and func.__closure__:
+        func = func.__closure__[0].cell_contents
+    return unwrap_wrapped_function(func)

{cadwyn-3.15.10 → cadwyn-4.0.0}/cadwyn/applications.py

@@ -4,7 +4,6 @@ from collections.abc import Callable, Coroutine, Sequence
 from datetime import date
 from logging import getLogger
 from pathlib import Path
-from types import ModuleType
 from typing import Any, cast
 
 from fastapi import APIRouter, FastAPI, HTTPException, routing
@@ -24,7 +23,7 @@ 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, deprecated
+from typing_extensions import Self
 
 from cadwyn.middleware import HeaderVersioningMiddleware, _get_api_version_dependency
 from cadwyn.route_generation import generate_versioned_routers
@@ -95,9 +94,6 @@ class Cadwyn(FastAPI):
     ) -> None:
         self.versions = versions
         # TODO: Remove argument entirely in any major version.
-        latest_schemas_package = extra.pop("latest_schemas_package", None) or self.versions.head_schemas_package
-        self.versions.head_schemas_package = latest_schemas_package
-        self._latest_schemas_package = cast(ModuleType, latest_schemas_package)
         self._dependency_overrides_provider = FakeDependencyOverridesProvider({})
 
         super().__init__(
@@ -175,9 +171,10 @@ class Cadwyn(FastAPI):
 
     @property
     def dependency_overrides(self) -> dict[Callable[..., Any], Callable[..., Any]]:
+        # TODO: Remove this approach as it is no longer necessary
         # This is only necessary because we cannot send self to versioned router generator
-        # because it takes a deepcopy of the router and self.versions.head_schemas_package is a module
-        # which cannot be copied.
+        # because it takes a deepcopy of the router and self.versions.head_schemas_package was a module
+        # which couldn't be copied.
         return self._dependency_overrides_provider.dependency_overrides
 
     @dependency_overrides.setter
@@ -187,16 +184,6 @@ class Cadwyn(FastAPI):
     ) -> None:
         self._dependency_overrides_provider.dependency_overrides = value
 
-    @property  # pragma: no cover
-    @deprecated("It is going to be deleted in the future. Use VersionBundle.head_schemas_package instead")
-    def latest_schemas_package(self):
-        return self._latest_schemas_package
-
-    @latest_schemas_package.setter  # pragma: no cover
-    @deprecated("It is going to be deleted in the future. Use VersionBundle.head_schemas_package instead")
-    def latest_schemas_package(self, value: ModuleType | None):
-        self._latest_schemas_package = value
-
     def _add_openapi_endpoints(self, unversioned_router: APIRouter):
         if self.openapi_url is not None:
             unversioned_router.add_route(
@@ -233,10 +220,7 @@ class Cadwyn(FastAPI):
         root_router = APIRouter(dependency_overrides_provider=self._dependency_overrides_provider)
         for router in routers:
             root_router.include_router(router)
-        router_versions = generate_versioned_routers(
-            root_router,
-            versions=self.versions,
-        )
+        router_versions = generate_versioned_routers(root_router, versions=self.versions)
         for version, router in router_versions.items():
             self.add_header_versioned_routers(router, header_value=version.isoformat())
 
@@ -358,16 +342,3 @@ class Cadwyn(FastAPI):
         self.router.routes.extend(added_routes)
 
         return added_routes
-
-    @deprecated("Use builtin FastAPI methods such as include_router instead")
-    def add_unversioned_routers(self, *routers: APIRouter):
-        for router in routers:
-            self.include_router(router)
-
-    @deprecated("Use builtin FastAPI methods such as add_api_route instead")
-    def add_unversioned_routes(self, *routes: Route):
-        router = APIRouter(routes=list(routes))
-        self.include_router(router)
-
-    @deprecated("It no longer does anything")
-    def enrich_swagger(self): ...

{cadwyn-3.15.10 → cadwyn-4.0.0}/cadwyn/exceptions.py

@@ -5,6 +5,10 @@ from typing import Any
 from fastapi.routing import APIRoute
 
 
+class CadwynRenderError(Exception):
+    pass
+
+
 class CadwynError(Exception):
     pass
 
@@ -26,15 +30,15 @@ class LintingError(CadwynError):
     pass
 
 
-class CodeGenerationError(CadwynError):
+class SchemaGenerationError(CadwynError):
     pass
 
 
-class ModuleIsNotAvailableAsTextError(CodeGenerationError):
+class ModuleIsNotAvailableAsTextError(SchemaGenerationError):
     pass
 
 
-class InvalidGenerationInstructionError(CodeGenerationError):
+class InvalidGenerationInstructionError(SchemaGenerationError):
     pass
 
 
@@ -70,3 +74,7 @@ class CadwynStructureError(CadwynError):
 
 class ModuleIsNotVersionedError(ValueError):
     pass
+
+
+class ImportFromStringError(CadwynError):
+    pass

{cadwyn-3.15.10 → cadwyn-4.0.0}/cadwyn/middleware.py

@@ -64,11 +64,11 @@ class HeaderVersioningMiddleware(BaseHTTPMiddleware):
                     request=request,
                     dependant=self.version_header_validation_dependant,
                     async_exit_stack=async_exit_stack,
-                    embed_body_fields=False,
                 )
-                if solved_result.errors:
-                    return self.default_response_class(status_code=422, content=_normalize_errors(solved_result.errors))
-                api_version = cast(date, solved_result.values[self.api_version_header_name.replace("-", "_")])
+                values, errors, *_ = solved_result
+                if errors:
+                    return self.default_response_class(status_code=422, content=_normalize_errors(errors))
+                api_version = cast(date, values[self.api_version_header_name.replace("-", "_")])
                 self.api_version_var.set(api_version)
 
         response = await call_next(request)