PyPI - cadwyn - Versions diffs - 5.4.6__py3-none-any.whl - Mend

cadwyn 5.4.6__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

cadwyn/__init__.py +44 -0
cadwyn/__main__.py +78 -0
cadwyn/_asts.py +155 -0
cadwyn/_importer.py +31 -0
cadwyn/_internal/__init__.py +0 -0
cadwyn/_internal/context_vars.py +9 -0
cadwyn/_render.py +155 -0
cadwyn/_utils.py +79 -0
cadwyn/applications.py +484 -0
cadwyn/changelogs.py +503 -0
cadwyn/dependencies.py +5 -0
cadwyn/exceptions.py +78 -0
cadwyn/middleware.py +131 -0
cadwyn/py.typed +0 -0
cadwyn/route_generation.py +536 -0
cadwyn/routing.py +159 -0
cadwyn/schema_generation.py +1162 -0
cadwyn/static/__init__.py +0 -0
cadwyn/static/docs.html +136 -0
cadwyn/structure/__init__.py +31 -0
cadwyn/structure/common.py +18 -0
cadwyn/structure/data.py +249 -0
cadwyn/structure/endpoints.py +170 -0
cadwyn/structure/enums.py +42 -0
cadwyn/structure/schemas.py +338 -0
cadwyn/structure/versions.py +756 -0
cadwyn-5.4.6.dist-info/METADATA +90 -0
cadwyn-5.4.6.dist-info/RECORD +31 -0
cadwyn-5.4.6.dist-info/WHEEL +4 -0
cadwyn-5.4.6.dist-info/entry_points.txt +2 -0
cadwyn-5.4.6.dist-info/licenses/LICENSE +21 -0

cadwyn/static/__init__.py ADDED Viewed

File without changes

cadwyn/static/docs.html ADDED Viewed

@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>OpenAPI Contracts</title>
+    <meta name="robots" content="noindex">
+    <!-- Favicon -->
+    <link rel="shortcut icon" type="image/x-icon"
+      href="https://cpwebassets.codepen.io/assets/favicon/favicon-aec34940fbc1a6e787974dcd360f2c6b63348d4b1f4e06c77743096d55480f33.ico">
+    <link rel="mask-icon"
+      href="https://cpwebassets.codepen.io/assets/favicon/logo-pin-8f3771b1072e3c38bd662872f6b673a722f4b3ca2421637d5596661b4e2132cc.svg"
+      color="#111">
+    <link rel="canonical" href="https://codepen.io/faaezahmd/pen/dJeRex">
+    <!-- Fonts -->
+    <link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
+    <!-- Reset CSS -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/meyer-reset/2.0/reset.min.css">
+    <!-- Custom Styles -->
+    <style>
+      body {
+        font-family: "Lato", sans-serif;
+        background-color: #f4f4f4;
+        color: #333;
+        margin: 0;
+        padding: 0;
+      }
+      .container {
+        max-width: 800px;
+        margin: 50px auto;
+        padding: 20px;
+        background-color: #fff;
+        box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
+        border-radius: 5px;
+      }
+      h2 {
+        font-size: 32px;
+        margin: 0 0 20px;
+        text-align: center;
+        color: #3498db;
+      }
+      h2 small {
+        display: block;
+        font-size: 14px;
+        color: #555;
+      }
+      .responsive-table li {
+        border-radius: 5px;
+        padding: 20px;
+        display: flex;
+        justify-content: space-between;
+        margin-bottom: 20px;
+        background-color: #ecf0f1;
+        box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
+      }
+      .responsive-table .table-header {
+        background-color: #3498db;
+        font-size: 16px;
+        text-transform: uppercase;
+        letter-spacing: 0.03em;
+        color: #fff;
+      }
+      .responsive-table .col-1,
+      .responsive-table .col-2 {
+        flex-basis: 50%;
+        text-align: left;
+      }
+      .responsive-table .col-1 {
+        font-weight: bold;
+      }
+      .responsive-table .col-2 a {
+        color: black;
+        /* Задаем цвет текста черным */
+        text-decoration: none;
+        font-weight: bold;
+      }
+      @media all and (max-width: 767px) {
+        .responsive-table .table-header {
+          display: none;
+        }
+        .responsive-table li {
+          display: block;
+        }
+        .responsive-table .col {
+          flex-basis: 100%;
+          display: flex;
+          padding: 10px 0;
+        }
+        .responsive-table .col:before {
+          color: #6C7A89;
+          padding-right: 10px;
+          content: attr(data-label);
+          flex-basis: 50%;
+          text-align: right;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <h2>OpenAPI Contracts</h2>
+      <ul class="responsive-table">
+        <li class="table-header">
+          <div class="col col-1">Version</div>
+          <div class="col col-2">URL</div>
+        </li>
+        {% for name, url in table.items() %}
+        <li class="table-row">
+          <div class="col col-1">{{ name }}</div>
+          <div class="col col-2"><a href="{{ url }}">{{ url }}</a></div>
+        </li>
+        {% endfor %}
+      </ul>
+    </div>
+  </body>
+</html>

cadwyn/structure/__init__.py ADDED Viewed

@@ -0,0 +1,31 @@
+from .data import (
+    RequestInfo,
+    ResponseInfo,
+    convert_request_to_next_version_for,
+    convert_response_to_previous_version_for,
+)
+from .endpoints import endpoint
+from .enums import enum
+from .schemas import schema
+from .versions import (
+    HeadVersion,
+    Version,
+    VersionBundle,
+    VersionChange,
+    VersionChangeWithSideEffects,
+)
+__all__ = [
+    "HeadVersion",
+    "RequestInfo",
+    "ResponseInfo",
+    "Version",
+    "VersionBundle",
+    "VersionChange",
+    "VersionChangeWithSideEffects",
+    "convert_request_to_next_version_for",
+    "convert_response_to_previous_version_for",
+    "endpoint",
+    "enum",
+    "schema",
+]

cadwyn/structure/common.py ADDED Viewed

@@ -0,0 +1,18 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from pydantic import BaseModel
+from typing_extensions import ParamSpec, TypeAlias, TypeVar
+from cadwyn._utils import DATACLASS_KW_ONLY, DATACLASS_SLOTS
+VersionedModel = BaseModel
+VersionType: TypeAlias = str
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+Endpoint: TypeAlias = Callable[_P, _R]
+@dataclass(**DATACLASS_SLOTS, **DATACLASS_KW_ONLY)
+class _HiddenAttributeMixin:
+    is_hidden_from_changelog: bool

cadwyn/structure/data.py ADDED Viewed

@@ -0,0 +1,249 @@
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import ClassVar, Union, cast
+from fastapi import Request, Response
+from starlette.datastructures import MutableHeaders
+from typing_extensions import Any, ParamSpec, overload
+from cadwyn._utils import same_definition_as_in
+from cadwyn.structure.endpoints import _validate_that_strings_are_valid_http_methods
+_P = ParamSpec("_P")
+# TODO (https://github.com/zmievsa/cadwyn/issues/49): Add form handling
+class RequestInfo:
+    __slots__ = ("_cookies", "_query_params", "_request", "body", "headers")
+    def __init__(self, request: Request, body: Any):
+        super().__init__()
+        self.body = body
+        self.headers = request.headers.mutablecopy()
+        self._cookies = request.cookies
+        self._query_params = request.query_params._dict
+        self._request = request
+    @property
+    def cookies(self) -> dict[str, str]:
+        return self._cookies
+    @property
+    def query_params(self) -> dict[str, str]:
+        return self._query_params
+# TODO (https://github.com/zmievsa/cadwyn/issues/111): handle _response.media_type and _response.background
+class ResponseInfo:
+    __slots__ = ("_response", "body")
+    def __init__(self, response: Response, body: Any):
+        super().__init__()
+        self.body = body
+        self._response = response
+    @property
+    def status_code(self) -> int:
+        return self._response.status_code
+    @status_code.setter
+    def status_code(self, value: int):
+        self._response.status_code = value
+    @property
+    def headers(self) -> MutableHeaders:
+        return self._response.headers
+    @same_definition_as_in(Response.set_cookie)
+    def set_cookie(self, *args: Any, **kwargs: Any):
+        return self._response.set_cookie(*args, **kwargs)
+    @same_definition_as_in(Response.delete_cookie)
+    def delete_cookie(self, *args: Any, **kwargs: Any):
+        return self._response.delete_cookie(*args, **kwargs)
+@dataclass
+class _AlterDataInstruction:
+    transformer: Callable[[Any], None]
+    owner: type = field(init=False)
+    _payload_arg_name: ClassVar[str]
+    def __post_init__(self):
+        signature = inspect.signature(self.transformer)
+        if list(signature.parameters) != [self._payload_arg_name]:
+            raise ValueError(
+                f"Method '{self.transformer.__name__}' must have only 1 parameter: {self._payload_arg_name}",
+            )
+        functools.update_wrapper(self, self.transformer)
+    def __set_name__(self, owner: type, name: str):
+        self.owner = owner
+    def __call__(self, __request_or_response: Union[RequestInfo, ResponseInfo], /) -> None:
+        return self.transformer(__request_or_response)
+@dataclass
+class _BaseAlterBySchemaInstruction:
+    schemas: tuple[Any, ...]
+    check_usage: bool = True
+##########
+# Requests
+##########
+@dataclass
+class _BaseAlterRequestInstruction(_AlterDataInstruction):
+    _payload_arg_name = "request"
+@dataclass
+class _AlterRequestBySchemaInstruction(_BaseAlterBySchemaInstruction, _BaseAlterRequestInstruction): ...
+@dataclass
+class _AlterRequestByPathInstruction(_BaseAlterRequestInstruction):
+    path: str
+    methods: set[str]
+    repr_name = "Request by path converter"
+@overload
+def convert_request_to_next_version_for(
+    first_schema: type,
+    /,
+    *additional_schemas: type,
+    check_usage: bool = True,
+) -> "type[staticmethod[_P, None]]": ...
+@overload
+def convert_request_to_next_version_for(path: str, methods: list[str], /) -> "type[staticmethod[_P, None]]": ...
+def convert_request_to_next_version_for(
+    schema_or_path: Union[type, str],
+    methods_or_second_schema: Union[list[str], None, type] = None,
+    /,
+    *additional_schemas: type,
+    check_usage: bool = True,
+) -> "type[staticmethod[_P, None]]":
+    _validate_decorator_args(schema_or_path, methods_or_second_schema, additional_schemas)
+    def decorator(transformer: Callable[[RequestInfo], None]) -> Any:
+        if isinstance(schema_or_path, str):
+            return _AlterRequestByPathInstruction(
+                path=schema_or_path,
+                methods=set(cast("list", methods_or_second_schema)),
+                transformer=transformer,
+            )
+        else:
+            if methods_or_second_schema is None:
+                schemas = (schema_or_path,)
+            else:
+                schemas = (schema_or_path, methods_or_second_schema, *additional_schemas)
+            return _AlterRequestBySchemaInstruction(
+                schemas=schemas,
+                transformer=transformer,
+                check_usage=check_usage,
+            )
+    return decorator  # pyright: ignore[reportReturnType]
+###########
+# Responses
+###########
+@dataclass
+class _BaseAlterResponseInstruction(_AlterDataInstruction):
+    _payload_arg_name = "response"
+    migrate_http_errors: bool
+@dataclass
+class _AlterResponseBySchemaInstruction(_BaseAlterBySchemaInstruction, _BaseAlterResponseInstruction): ...
+@dataclass
+class _AlterResponseByPathInstruction(_BaseAlterResponseInstruction):
+    path: str
+    methods: set[str]
+    repr_name = "Response by path converter"
+@overload
+def convert_response_to_previous_version_for(
+    first_schema: type,
+    /,
+    *schemas: type,
+    migrate_http_errors: bool = False,
+    check_usage: bool = True,
+) -> "type[staticmethod[_P, None]]": ...
+@overload
+def convert_response_to_previous_version_for(
+    path: str,
+    methods: list[str],
+    /,
+    *,
+    migrate_http_errors: bool = False,
+) -> "type[staticmethod[_P, None]]": ...
+def convert_response_to_previous_version_for(
+    schema_or_path: Union[type, str],
+    methods_or_second_schema: Union[list[str], type, None] = None,
+    /,
+    *additional_schemas: type,
+    migrate_http_errors: bool = False,
+    check_usage: bool = True,
+) -> "type[staticmethod[_P, None]]":
+    _validate_decorator_args(schema_or_path, methods_or_second_schema, additional_schemas)
+    def decorator(transformer: Callable[[ResponseInfo], None]) -> Any:
+        if isinstance(schema_or_path, str):
+            # The validation above checks that methods is not None
+            return _AlterResponseByPathInstruction(
+                path=schema_or_path,
+                methods=set(cast("list", methods_or_second_schema)),
+                transformer=transformer,
+                migrate_http_errors=migrate_http_errors,
+            )
+        else:
+            if methods_or_second_schema is None:
+                schemas = (schema_or_path,)
+            else:
+                schemas = (schema_or_path, methods_or_second_schema, *additional_schemas)
+            return _AlterResponseBySchemaInstruction(
+                schemas=schemas,
+                transformer=transformer,
+                migrate_http_errors=migrate_http_errors,
+                check_usage=check_usage,
+            )
+    return decorator  # pyright: ignore[reportReturnType]
+def _validate_decorator_args(
+    schema_or_path: Union[type, str],
+    methods_or_second_schema: Union[list[str], type, None],
+    additional_schemas: tuple[type, ...],
+) -> None:
+    if isinstance(schema_or_path, str):
+        if not isinstance(methods_or_second_schema, list):
+            raise TypeError("If path was provided as a first argument, methods must be provided as a second argument")
+        _validate_that_strings_are_valid_http_methods(methods_or_second_schema)
+        if additional_schemas:
+            raise TypeError("If path was provided as a first argument, then additional schemas cannot be added")
+    elif methods_or_second_schema is not None and not isinstance(methods_or_second_schema, type):
+        raise TypeError("If schema was provided as a first argument, all other arguments must also be schemas")

cadwyn/structure/endpoints.py ADDED Viewed

@@ -0,0 +1,170 @@
+from collections.abc import Callable, Collection, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Union
+from fastapi import Response
+from fastapi.params import Depends
+from fastapi.routing import APIRoute
+from starlette.routing import BaseRoute
+from cadwyn.exceptions import LintingError
+from .._utils import DATACLASS_SLOTS, Sentinel
+from .common import _HiddenAttributeMixin
+HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"}
+@dataclass(**DATACLASS_SLOTS)
+class EndpointAttributesPayload:
+    # FastAPI API routes also have "endpoint" and "dependency_overrides_provider" fields.
+    # We do not use them because:
+    #   1. "endpoint" must not change -- otherwise this versioning is doomed
+    #   2. "dependency_overrides_provider" is taken from router's attributes
+    #   3. "response_model" must not change for the same reason as endpoint
+    # The following for the same reason as endpoint:
+    # * response_model_include: SetIntStr | DictIntStrAny
+    # * response_model_exclude: SetIntStr | DictIntStrAny
+    # * response_model_by_alias: bool
+    # * response_model_exclude_unset: bool
+    # * response_model_exclude_defaults: bool
+    # * response_model_exclude_none: bool
+    path: str
+    response_model: Any
+    status_code: int
+    tags: list[Union[str, Enum]]
+    # Adding/removing dependencies between versions seems like a bad choice.
+    # It makes the system overly complex. Instead, we allow people to
+    # overwrite all dependencies of a route at once. Hence you always know exactly
+    # which dependencies have been specified, no matter how many migrations you have.
+    dependencies: Sequence[Depends]
+    summary: str
+    description: str
+    response_description: str
+    responses: dict[Union[int, str], dict[str, Any]]
+    deprecated: bool
+    methods: set[str]
+    operation_id: str
+    include_in_schema: bool
+    response_class: type[Response]
+    name: str
+    callbacks: list[BaseRoute]
+    openapi_extra: dict[str, Any]
+    generate_unique_id_function: Callable[[APIRoute], str]
+@dataclass(**DATACLASS_SLOTS)
+class EndpointHadInstruction(_HiddenAttributeMixin):
+    endpoint_path: str
+    endpoint_methods: set[str]
+    endpoint_func_name: Union[str, None]
+    attributes: EndpointAttributesPayload
+@dataclass(**DATACLASS_SLOTS)
+class EndpointExistedInstruction(_HiddenAttributeMixin):
+    endpoint_path: str
+    endpoint_methods: set[str]
+    endpoint_func_name: Union[str, None]
+@dataclass(**DATACLASS_SLOTS)
+class EndpointDidntExistInstruction(_HiddenAttributeMixin):
+    endpoint_path: str
+    endpoint_methods: set[str]
+    endpoint_func_name: Union[str, None]
+@dataclass(**DATACLASS_SLOTS)
+class EndpointInstructionFactory:
+    endpoint_path: str
+    endpoint_methods: set[str]
+    endpoint_func_name: Union[str, None]
+    @property
+    def didnt_exist(self) -> EndpointDidntExistInstruction:
+        return EndpointDidntExistInstruction(
+            is_hidden_from_changelog=False,
+            endpoint_path=self.endpoint_path,
+            endpoint_methods=self.endpoint_methods,
+            endpoint_func_name=self.endpoint_func_name,
+        )
+    @property
+    def existed(self) -> EndpointExistedInstruction:
+        return EndpointExistedInstruction(
+            is_hidden_from_changelog=False,
+            endpoint_path=self.endpoint_path,
+            endpoint_methods=self.endpoint_methods,
+            endpoint_func_name=self.endpoint_func_name,
+        )
+    def had(
+        self,
+        *,
+        path: str = Sentinel,
+        response_model: Any = Sentinel,
+        status_code: int = Sentinel,
+        tags: list[Union[str, Enum]] = Sentinel,
+        dependencies: Sequence[Depends] = Sentinel,
+        summary: str = Sentinel,
+        description: str = Sentinel,
+        response_description: str = Sentinel,
+        responses: dict[Union[int, str], dict[str, Any]] = Sentinel,
+        deprecated: bool = Sentinel,
+        methods: list[str] = Sentinel,
+        operation_id: str = Sentinel,
+        include_in_schema: bool = Sentinel,
+        response_class: type[Response] = Sentinel,
+        name: str = Sentinel,
+        callbacks: list[BaseRoute] = Sentinel,
+        openapi_extra: dict[str, Any] = Sentinel,
+        generate_unique_id_function: Callable[[APIRoute], str] = Sentinel,
+    ):
+        return EndpointHadInstruction(
+            is_hidden_from_changelog=False,
+            endpoint_path=self.endpoint_path,
+            endpoint_methods=self.endpoint_methods,
+            endpoint_func_name=self.endpoint_func_name,
+            attributes=EndpointAttributesPayload(
+                path=path,
+                response_model=response_model,
+                status_code=status_code,
+                tags=tags,
+                dependencies=dependencies,
+                summary=summary,
+                description=description,
+                response_description=response_description,
+                responses=responses,
+                deprecated=deprecated,
+                methods=set(methods) if methods is not Sentinel else Sentinel,
+                operation_id=operation_id,
+                include_in_schema=include_in_schema,
+                response_class=response_class,
+                name=name,
+                callbacks=callbacks,
+                openapi_extra=openapi_extra,
+                generate_unique_id_function=generate_unique_id_function,
+            ),
+        )
+def endpoint(path: str, methods: list[str], /, *, func_name: Union[str, None] = None) -> EndpointInstructionFactory:
+    _validate_that_strings_are_valid_http_methods(methods)
+    return EndpointInstructionFactory(path, set(methods), func_name)
+def _validate_that_strings_are_valid_http_methods(methods: Collection[str]):
+    invalid_methods = set(methods) - HTTP_METHODS
+    if invalid_methods:
+        invalid_methods = ", ".join(sorted(invalid_methods))
+        raise LintingError(
+            f"The following HTTP methods are not valid: {invalid_methods}. "
+            "Please use valid HTTP methods such as GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD.",
+        )
+AlterEndpointSubInstruction = Union[EndpointDidntExistInstruction, EndpointExistedInstruction, EndpointHadInstruction]

cadwyn/structure/enums.py ADDED Viewed

@@ -0,0 +1,42 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Union
+from cadwyn._utils import DATACLASS_SLOTS
+from .common import _HiddenAttributeMixin
+@dataclass(**DATACLASS_SLOTS)
+class EnumHadMembersInstruction(_HiddenAttributeMixin):
+    enum: type[Enum]
+    members: Mapping[str, Any]
+@dataclass(**DATACLASS_SLOTS)
+class EnumDidntHaveMembersInstruction(_HiddenAttributeMixin):
+    enum: type[Enum]
+    members: tuple[str, ...]
+@dataclass(**DATACLASS_SLOTS)
+class EnumInstructionFactory:
+    enum_class: type[Enum]
+    def had(self, **enum_member_to_value_mapping: Any) -> EnumHadMembersInstruction:
+        return EnumHadMembersInstruction(
+            is_hidden_from_changelog=False, enum=self.enum_class, members=enum_member_to_value_mapping
+        )
+    def didnt_have(self, *enum_members: str) -> EnumDidntHaveMembersInstruction:
+        return EnumDidntHaveMembersInstruction(
+            is_hidden_from_changelog=False, enum=self.enum_class, members=enum_members
+        )
+def enum(enum_class: type[Enum], /) -> EnumInstructionFactory:
+    return EnumInstructionFactory(enum_class)
+AlterEnumSubInstruction = Union[EnumHadMembersInstruction, EnumDidntHaveMembersInstruction]