cadwyn 4.4.3__tar.gz → 4.4.5__tar.gz

{cadwyn-4.4.3 → cadwyn-4.4.5}/.github/workflows/ci.yaml

@@ -10,6 +10,7 @@ on:
     branches: [main, 3.x.x]
     types: [opened, synchronize]
     paths:
+      - ".github/workflows/ci.yaml"  # self
       - "**.py"
       - "**.toml"
       - "**.lock"
@@ -42,10 +43,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - run: uv run coverage run --source=. --parallel-mode -m pytest tests
       - name: Upload coverage results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: matrix.os == 'ubuntu-latest' # Cross-platform coverage combination doesn't work
         with:
-          name: main-tests-coverage-results
+          name: coverage-results-${{ matrix.python-version }}
           path: coverage/
   Tutorial-tests:
     runs-on: ubuntu-latest
@@ -60,24 +61,20 @@ jobs:
       - run: pip install pytest coverage dirty-equals
       - run: coverage run --source=. --parallel-mode -m pytest docs_src
       - name: Upload coverage results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: docs-tests-coverage-results
+          name: coverage-results-docs
           path: coverage/
   Coverage:
     needs: [Tests, Tutorial-tests]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Download main tests coverage info
-        uses: actions/download-artifact@v3
+      - name: Download coverage info
+        uses: actions/download-artifact@v4
         with:
-          name: main-tests-coverage-results
-          path: coverage/
-      - name: Download docs tests coverage info
-        uses: actions/download-artifact@v3
-        with:
-          name: docs-tests-coverage-results
+          pattern: coverage-results-*
+          merge-multiple: true
           path: coverage/
       - uses: actions/setup-python@v5
         with:
@@ -90,7 +87,7 @@ jobs:
         env:
           fail_ci_if_error: true
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-      - run: coverage report --fail-under=100
+      - run: coverage report --fail-under=100 --show-missing
 
   Lint:
     runs-on: ubuntu-latest

{cadwyn-4.4.3 → cadwyn-4.4.5}/.github/workflows/publish_docs.yaml

@@ -14,11 +14,11 @@ jobs:
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache

{cadwyn-4.4.3 → cadwyn-4.4.5}/.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_language_version:
   python: python3.10
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-yaml
@@ -18,14 +18,14 @@ repos:
       - id: python-check-blanket-noqa
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.1
+    rev: v0.8.1
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
   - repo: https://github.com/adamchainz/blacken-docs
-    rev: "1.18.0" # replace with latest tag on GitHub
+    rev: "1.19.1" # replace with latest tag on GitHub
     hooks:
       - id: blacken-docs
         additional_dependencies:
@@ -33,7 +33,7 @@ repos:
         args: ["--line-length=80", "--target-version=py310", "--skip-errors"]
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.41.0
+    rev: v0.43.0
     hooks:
       - id: markdownlint
         args: ["--disable", "MD013"]

{cadwyn-4.4.3 → cadwyn-4.4.5}/CHANGELOG.md

@@ -5,6 +5,18 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [4.4.5]
+
+### Fixed
+
+* Fix invalid migration of pydantic v1 style root validators when pydantic erases information about their "skip_on_failure" attribute
+
+## [4.4.4]
+
+### Fixed
+
+* Type hints for newest pydantic versions
+
 ## [4.4.3]
 
 ### Changed
@@ -299,7 +311,7 @@ Versions 3.x.x are still supported in terms of bug and security fixes but all th
 
 ### Fixed
 
-* When a class-based dependency from **fastapi** was used (anything security related), FastAPI had hardcoded `isinstance` checks for it which it used to enrich swagger with functionality. But when the dependencies were wrapped into our function wrappers, these checks stopped passing, thus breaking this functionality in swagger. Now we ignore all dependencies that FastAPI creates. This also introduces a hard-to-solve bug: if fastapi's class-based security dependency was subclassed and then `__call__` was overriden with new dependencies that are versioned -- we will not migrate them from version to version. I hope this is an extremely rare use case though. In fact, such use case breaks Liskov Substitution Principle and doesn't make much sense because security classes already include `request` parameter which means that no extra dependencies or parameters are necessary.
+* When a class-based dependency from **fastapi** was used (anything security related), FastAPI had hardcoded `isinstance` checks for it which it used to enrich swagger with functionality. But when the dependencies were wrapped into our function wrappers, these checks stopped passing, thus breaking this functionality in swagger. Now we ignore all dependencies that FastAPI creates. This also introduces a hard-to-solve bug: if fastapi's class-based security dependency was subclassed and then `__call__` was overridden with new dependencies that are versioned -- we will not migrate them from version to version. I hope this is an extremely rare use case though. In fact, such use case breaks Liskov Substitution Principle and doesn't make much sense because security classes already include `request` parameter which means that no extra dependencies or parameters are necessary.
 
 ## [3.6.5]
 

{cadwyn-4.4.3 → cadwyn-4.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: cadwyn
-Version: 4.4.3
+Version: 4.4.5
 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.4.3 → cadwyn-4.4.5}/cadwyn/_asts.py

@@ -56,12 +56,13 @@ def get_fancy_repr(value: Any) -> Any:
 
 
 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)))
+    modified_fields = [
+        (key, getattr(value, key))
+        for key in value.__dataclass_fields__  # pyright: ignore[reportAttributeAccessIssue]
+        if getattr(value, key) != getattr(empty_obj, key)
+    ]
 
     return PlainRepr(
         value.__class__.__name__
@@ -120,11 +121,12 @@ def transform_other(value: Any) -> Any:
 
 
 def _get_lambda_source_from_default_factory(source: str) -> str:
-    found_lambdas: list[ast.Lambda] = []
+    found_lambdas: list[ast.Lambda] = [
+        node.value
+        for node in ast.walk(ast.parse(source))
+        if isinstance(node, ast.keyword) and node.arg == "default_factory" and isinstance(node.value, 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 :)

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/_importer.py

@@ -7,7 +7,7 @@ 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>".'
+        message = f'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)

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/_utils.py

@@ -1,5 +1,5 @@
 from collections.abc import Callable
-from typing import Any, Generic, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, Union
 
 from pydantic._internal._decorators import unwrap_wrapped_function
 
@@ -40,3 +40,17 @@ def fully_unwrap_decorator(func: Callable, is_pydantic_v1_style_validator: Any):
     if is_pydantic_v1_style_validator and func.__closure__:
         func = func.__closure__[0].cell_contents
     return unwrap_wrapped_function(func)
+
+
+T = TypeVar("T", bound=type[object])
+
+if TYPE_CHECKING:
+    lenient_issubclass = issubclass
+
+else:
+
+    def lenient_issubclass(cls: type, other: T | tuple[T, ...]) -> bool:
+        try:
+            return issubclass(cls, other)
+        except TypeError:  # pragma: no cover
+            return False

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/changelogs.py

@@ -160,7 +160,7 @@ def _get_openapi_representation_of_a_field(model: type[BaseModel], field_name: s
 
     model_name_map = get_compat_model_name_map([CadwynDummyModelForRepresentation.model_fields["my_field"]])
     schema_generator = GenerateJsonSchema(ref_template=REF_TEMPLATE)
-    field_mapping, definitions = get_definitions(
+    _, definitions = get_definitions(
         fields=[ModelField(CadwynDummyModelForRepresentation.model_fields["my_field"], "my_field")],
         schema_generator=schema_generator,
         model_name_map=model_name_map,

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/route_generation.py

@@ -179,13 +179,13 @@ class _EndpointTransformer(Generic[_R, _WR]):
                     copy_of_dependant,
                     self.versions,
                 )
-        for _, router in routers.items():
+        for router in routers.values():
             router.routes = [
                 route
                 for route in router.routes
                 if not (isinstance(route, fastapi.routing.APIRoute) and _DELETED_ROUTE_TAG in route.tags)
             ]
-        for _, webhook_router in webhook_routers.items():
+        for webhook_router in webhook_routers.values():
             webhook_router.routes = [
                 route
                 for route in webhook_router.routes
@@ -466,18 +466,18 @@ def _get_routes(
     *,
     is_deleted: bool = False,
 ) -> list[fastapi.routing.APIRoute]:
-    found_routes = []
     endpoint_path = endpoint_path.rstrip("/")
-    for route in routes:
+    return [
+        route
+        for route in routes
         if (
             isinstance(route, fastapi.routing.APIRoute)
             and route.path.rstrip("/") == endpoint_path
             and set(route.methods).issubset(endpoint_methods)
             and (endpoint_func_name is None or route.endpoint.__name__ == endpoint_func_name)
             and (_DELETED_ROUTE_TAG in route.tags) == is_deleted
-        ):
-            found_routes.append(route)
-    return found_routes
+        )
+    ]
 
 
 def _get_route_from_func(

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/routing.py

@@ -23,9 +23,9 @@ _logger = getLogger(__name__)
 
 
 class _RootHeaderAPIRouter(APIRouter):
-    """
-    this class should be a root router of the FastAPI app when using header based
-    versioning. It will be used to route the requests to the correct versioned route
+    """Root router of the FastAPI app when using header based versioning.
+
+    It will be used to route the requests to the correct versioned route
     based on the headers. It also supports waterflowing the requests to the latest
     version of the API if the request header doesn't match any of the versions.
 
@@ -88,9 +88,6 @@ class _RootHeaderAPIRouter(APIRouter):
         return self.versioned_routers[version_chosen].routes
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        """
-        The main entry point to the Router class.
-        """
         if "router" not in scope:  # pragma: no cover
             scope["router"] = self
 
@@ -131,10 +128,8 @@ class _RootHeaderAPIRouter(APIRouter):
         self.unversioned_routes.append(self.routes[-1])
 
     async def process_request(self, scope: Scope, receive: Receive, send: Send, routes: Sequence[BaseRoute]) -> None:
-        """
-        its a copy-paste from starlette.routing.Router
-        but in this version self.routes were replaced with routes from the function arguments
-        """
+        # It's a copy-paste from starlette.routing.Router
+        # but in this version self.routes were replaced with routes from the function arguments
 
         partial = None
         partial_scope = {}

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/schema_generation.py

@@ -30,7 +30,6 @@ import pydantic
 import pydantic._internal._decorators
 from fastapi import Response
 from fastapi.routing import APIRoute
-from issubclass import issubclass
 from pydantic import BaseModel, Field, RootModel
 from pydantic._internal import _decorators
 from pydantic._internal._decorators import (
@@ -44,7 +43,7 @@ from pydantic._internal._decorators import (
 from pydantic.fields import ComputedFieldInfo, FieldInfo
 from typing_extensions import Doc, Self, _AnnotatedAlias, assert_never
 
-from cadwyn._utils import Sentinel, UnionType, fully_unwrap_decorator
+from cadwyn._utils import Sentinel, UnionType, fully_unwrap_decorator, lenient_issubclass
 from cadwyn.exceptions import InvalidGenerationInstructionError
 from cadwyn.structure.common import VersionDate
 from cadwyn.structure.data import ResponseInfo
@@ -160,8 +159,10 @@ def migrate_response_body(
     latest_body: Any,
     version: VersionDate | str,
 ):
-    """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.
+    """Convert the data to a specific version
+
+    Apply all version changes from latest until the passed version in reverse order
+    and wrap the result in the correct version of latest_response_model
     """
     if isinstance(version, str):
         version = date.fromisoformat(version)
@@ -213,6 +214,10 @@ def _wrap_validator(func: Callable, is_pydantic_v1_style_validator: Any, decorat
         # There's an inconsistency in their interfaces so we gotta resort to this
         mode = kwargs.pop("mode", "after")
         kwargs["pre"] = mode != "after"
+        if (
+            isinstance(decorator_info, RootValidatorDecoratorInfo) and decorator_info.mode == "after"
+        ):  # pragma: no cover # TODO
+            kwargs["skip_on_failure"] = True
     if decorator_fields is not None:
         return _PerFieldValidatorWrapper(
             func=func, fields=list(decorator_fields), decorator=actual_decorator, kwargs=kwargs
@@ -271,7 +276,8 @@ class _PydanticModelWrapper(Generic[_T_PYDANTIC_MODEL]):
     fields: Annotated[
         dict["_FieldName", PydanticFieldWrapper],
         Doc(
-            "Fields that belong to this model, not to its parents. I.e. The ones that were either defined or overriden "
+            "Fields that belong to this model, not to its parents. "
+            "I.e. The ones that were either defined or overridden "
         ),
     ] = dataclasses.field(repr=False)
     validators: dict[str, _PerFieldValidatorWrapper | _ValidatorWrapper] = dataclasses.field(repr=False)
@@ -316,7 +322,7 @@ class _PydanticModelWrapper(Generic[_T_PYDANTIC_MODEL]):
         for base in self.cls.mro()[1:]:
             if base in schemas:
                 parents.append(schemas[base])
-            elif issubclass(base, BaseModel):
+            elif lenient_issubclass(base, BaseModel):
                 parents.append(_wrap_pydantic_model(base))
         self._parents = parents
         return parents
@@ -372,10 +378,9 @@ def is_regular_function(call: Callable):
 
 
 class _CallableWrapper:
-    """__eq__ and __hash__ are needed to make sure that dependency overrides work correctly.
-    They are based on putting dependencies (functions) as keys for the dictionary so if we want to be able to
-    override the wrapper, we need to make sure that it is equivalent to the original in __hash__ and __eq__
-    """
+    # __eq__ and __hash__ are needed to make sure that dependency overrides work correctly.
+    # They are based on putting dependencies (functions) as keys for the dictionary so if we want to be able to
+    # override the wrapper, we need to make sure that it is equivalent to the original in __hash__ and __eq__
 
     def __init__(self, original_callable: Callable) -> None:
         super().__init__()
@@ -386,11 +391,9 @@ class _CallableWrapper:
 
     @property
     def __globals__(self):
-        """FastAPI uses __globals__ to resolve forward references in type hints
-        It's supposed to be an attribute on the function but we use it as property to prevent python
-        from trying to pickle globals when we deepcopy this wrapper
-        """
-        #
+        # FastAPI uses __globals__ to resolve forward references in type hints
+        # It's supposed to be an attribute on the function but we use it as property to prevent python
+        # from trying to pickle globals when we deepcopy this wrapper
         return self._original_callable.__globals__
 
     def __call__(self, *args: Any, **kwargs: Any):
@@ -420,8 +423,7 @@ class _AnnotationTransformer:
         )
 
     def change_version_of_annotation(self, annotation: Any) -> Any:
-        """Recursively go through all annotations and change them to the
-        annotations corresponding to the version passed.
+        """Recursively go through all annotations and change them to annotations corresponding to the version passed.
 
         So if we had a annotation "UserResponse" from "head" version, and we passed version of "2022-11-16", it would
         replace "UserResponse" with the the same class but from the "2022-11-16" version.
@@ -503,7 +505,7 @@ class _AnnotationTransformer:
             return annotation
 
     def _change_version_of_type(self, annotation: type):
-        if issubclass(annotation, BaseModel | Enum):
+        if lenient_issubclass(annotation, BaseModel | Enum):
             return self.generator[annotation]
         else:
             return annotation
@@ -607,7 +609,7 @@ def _add_request_and_response_params(route: APIRoute):
 
 @final
 class SchemaGenerator:
-    __slots__ = "annotation_transformer", "model_bundle", "concrete_models"
+    __slots__ = "annotation_transformer", "concrete_models", "model_bundle"
 
     def __init__(self, model_bundle: _ModelBundle) -> None:
         self.annotation_transformer = _AnnotationTransformer(self)
@@ -619,7 +621,11 @@ class SchemaGenerator:
         }
 
     def __getitem__(self, model: type[_T_ANY_MODEL], /) -> type[_T_ANY_MODEL]:
-        if not isinstance(model, type) or not issubclass(model, BaseModel | Enum) or model in (BaseModel, RootModel):
+        if (
+            not isinstance(model, type)
+            or not lenient_issubclass(model, BaseModel | Enum)
+            or model in (BaseModel, RootModel)
+        ):
             return model
         model = _unwrap_model(model)
 
@@ -648,10 +654,10 @@ class SchemaGenerator:
         elif model in self.model_bundle.enums:
             return self.model_bundle.enums[model]
 
-        if issubclass(model, BaseModel):
+        if lenient_issubclass(model, BaseModel):
             wrapper = _wrap_pydantic_model(model)
             self.model_bundle.schemas[model] = wrapper
-        elif issubclass(model, Enum):
+        elif lenient_issubclass(model, Enum):
             wrapper = _EnumWrapper(model)
             self.model_bundle.enums[model] = wrapper
         else:

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/structure/data.py

@@ -15,7 +15,7 @@ _P = ParamSpec("_P")
 
 # TODO (https://github.com/zmievsa/cadwyn/issues/49): Add form handling
 class RequestInfo:
-    __slots__ = ("body", "headers", "_cookies", "_query_params", "_request")
+    __slots__ = ("_cookies", "_query_params", "_request", "body", "headers")
 
     def __init__(self, request: Request, body: Any):
         super().__init__()
@@ -36,7 +36,7 @@ class RequestInfo:
 
 # TODO (https://github.com/zmievsa/cadwyn/issues/111): handle _response.media_type and _response.background
 class ResponseInfo:
-    __slots__ = ("body", "_response")
+    __slots__ = ("_response", "body")
 
     def __init__(self, response: Response, body: Any):
         super().__init__()
@@ -86,9 +86,9 @@ class _AlterDataInstruction:
         return self.transformer(__request_or_response)
 
 
-###########
-## Requests
-###########
+##########
+# Requests
+##########
 
 
 @dataclass
@@ -146,9 +146,9 @@ def convert_request_to_next_version_for(
     return decorator  # pyright: ignore[reportReturnType]
 
 
-############
-## Responses
-############
+###########
+# Responses
+###########
 
 
 @dataclass

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/structure/endpoints.py

@@ -23,7 +23,7 @@ class EndpointAttributesPayload:
     #   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 enpoint:
+    # The following for the same reason as endpoint:
     # * response_model_include: SetIntStr | DictIntStrAny
     # * response_model_exclude: SetIntStr | DictIntStrAny
     # * response_model_by_alias: bool

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/structure/schemas.py

@@ -186,7 +186,7 @@ class AlterFieldInstructionFactory:
         self,
         *,
         type: Any,
-        info: FieldInfo | None = None,
+        info: FieldInfo | Any | None = None,
     ) -> FieldExistedAsInstruction:
         if info is None:
             info = cast(FieldInfo, Field())

{cadwyn-4.4.3 → cadwyn-4.4.5}/cadwyn/structure/versions.py

@@ -396,17 +396,6 @@ class VersionBundle:
         path: str,
         method: str,
     ) -> ResponseInfo:
-        """Convert the data to a specific version by applying all version changes in reverse order.
-
-        Args:
-            endpoint: the function which usually returns this data. Data migrations marked with this endpoint will
-            be applied to the passed data
-            payload: data to be migrated. Will be mutated during the call
-            version: the version to which the data should be converted
-
-        Returns:
-            Modified data
-        """
         for v in self.versions:
             if v.value <= current_version:
                 break
@@ -421,7 +410,7 @@ class VersionBundle:
                 if path in version_change.alter_response_by_path_instructions:
                     for instruction in version_change.alter_response_by_path_instructions[path]:
                         if method in instruction.methods:  # pragma: no branch # Safe branch to skip
-                            migrations_to_apply.append(instruction)
+                            migrations_to_apply.append(instruction)  # noqa: PERF401
 
                 for migration in migrations_to_apply:
                     if response_info.status_code < 300 or migration.migrate_http_errors:
@@ -447,8 +436,7 @@ class VersionBundle:
                 request_param: FastapiRequest = kwargs[request_param_name]
                 response_param: FastapiResponse = kwargs[response_param_name]
                 background_tasks: BackgroundTasks | None = kwargs.get(
-                    background_tasks_param_name,  # pyright: ignore[reportArgumentType, reportCallIssue]
-                    None,
+                    background_tasks_param_name,  # pyright: ignore[reportArgumentType]
                 )
                 method = request_param.method
                 response = Sentinel

{cadwyn-4.4.3 → cadwyn-4.4.5}/docs/concepts/index.md

@@ -2,7 +2,7 @@
 
 This section covers the entirety of features and their rationale in Cadwyn. It can also be used as a reference documentation until we have a proper one. First, let's talk about the reasons for using Cadwyn at all.
 
-Cadwyn aims to be the most accurate and sophisticated API Versioning model out there. First of all, you maintain **zero** duplicated code yourself. Usually, in API versioning you [would need to](../theory/how_we_got_here.md) duplicate and maintain at least some layer of your applicaton. It could be the database, business logic, schemas, and endpoints. Cadwyn allows you to duplicate none of that. Internally, it duplicates endpoints and schemas at runtime but none of it becomes your tech debt, none of it becomes your code to support. If you test rigorously, then only [some small subset of your tests](./testing.md) will need to be duplicated when existing functionality is changed between versions.
+Cadwyn aims to be the most accurate and sophisticated API Versioning model out there. First of all, you maintain **zero** duplicated code yourself. Usually, in API versioning you [would need to](../theory/how_we_got_here.md) duplicate and maintain at least some layer of your application. It could be the database, business logic, schemas, and endpoints. Cadwyn allows you to duplicate none of that. Internally, it duplicates endpoints and schemas at runtime but none of it becomes your tech debt, none of it becomes your code to support. If you test rigorously, then only [some small subset of your tests](./testing.md) will need to be duplicated when existing functionality is changed between versions.
 
 You define your database, business logic, routes, and schemas only once. Then, whenever you release a new API version, you use Cadwyn's [version change DSL](./version_changes.md#version-changes) to describe how to convert your app to the previous version. So your business logic and database stay intact and always represent the latest version while the version changes make sure that your clients can continue using the previous versions without ever needing to update their code.
 

{cadwyn-4.4.3 → cadwyn-4.4.5}/docs/concepts/main_app.md

@@ -33,7 +33,7 @@ That's it! `generate_and_include_versioned_routers` will generate all versions o
 
 ## Routing
 
-Cadwyn is built on header-based routing. First, we route requests to the appropriate API version based on the version header (`x-api-version` by default). Then we route by the appropriate url path and method. Currerntly, Cadwyn only works with ISO date-based versions (such as `2022-11-16`). If the user sends an incorrect API version, Cadwyn picks up the closest lower applicable version. For example, `2022-11-16` in request can be matched by `2022-11-15` and `2000-01-01` but cannot be matched by `2022-11-17`.
+Cadwyn is built on header-based routing. First, we route requests to the appropriate API version based on the version header (`x-api-version` by default). Then we route by the appropriate url path and method. Currently, Cadwyn only works with ISO date-based versions (such as `2022-11-16`). If the user sends an incorrect API version, Cadwyn picks up the closest lower applicable version. For example, `2022-11-16` in request can be matched by `2022-11-15` and `2000-01-01` but cannot be matched by `2022-11-17`.
 
 However, header-based routing is only the standard way to use Cadwyn. If you want to use any other sort of routing, you can use Cadwyn directly through `cadwyn.generate_versioned_routers` or subclass `cadwyn.Cadwyn` to use a different router and middleware. Just remember to update the `VersionBundle.api_version_var` variable each time you route some request to a version. This variable allows Cadwyn to do [side effects](./version_changes.md#version-changes-with-side-effects) and [data migrations](./version_changes.md#data-migrations).
 

{cadwyn-4.4.3 → cadwyn-4.4.5}/docs/concepts/methodology.md

@@ -3,7 +3,7 @@
 Cadwyn implements a methodology that is based on the following set of principles:
 
 * Each version is made up of "version changes" or "compatibility gates" which describe **independent atomic** differences between it and previous version
-* We make a new version if an only if we have breaking changes
+* We make a new version if and only if we have breaking changes
 * Versions must have little to no effect on the business logic
 * Versions **must always** be compatible in terms of data
 * Creating new versions is avoided at all costs

{cadwyn-4.4.3 → cadwyn-4.4.5}/docs/concepts/version_changes.md

@@ -110,7 +110,7 @@ versions = VersionBundle(
 
 ### VersionChange.description
 
-The description field of your version change must be even more detailed. In fact, it is intended to be the **name** and the **summary** of the version change for your clients. It must clearly state to you clients **what happened** and **why**. So you need to make it grammatically correct, detailed, concrete, and written for humans. Note that you do not have to use a strict machine-readable format -- it is a portion of documentation, not a set of intructions. Let's take [Stripe's description](https://stripe.com/blog/api-versioning) to one of their version changes as an example:
+The description field of your version change must be even more detailed. In fact, it is intended to be the **name** and the **summary** of the version change for your clients. It must clearly state to you clients **what happened** and **why**. So you need to make it grammatically correct, detailed, concrete, and written for humans. Note that you do not have to use a strict machine-readable format -- it is a portion of documentation, not a set of instructions. Let's take [Stripe's description](https://stripe.com/blog/api-versioning) to one of their version changes as an example:
 
 ```md
 Event objects (and webhooks) will now render `request` subobject that contains a request ID and idempotency key instead of just a string request ID.
@@ -126,7 +126,7 @@ Changes:
 
 * Its first line, `Migration from first version (2022-11-16) to 2023-09-01 version.`, duplicates the already-known information -- your developers will know which version `VersionChange` migrates to and from by its location in [VersionBundle](#versionbundle) and most likely by its file name. Your clients will also know that because you can automatically infer this information from  So it is simply standing in the way of actually useful parts of the documentation
 * Its second line, `Changes:`, does not make any sense as well because description of a `VersionChange` cannot describe anything but changes. So again, it's stating the obvious and making it harder for our readers to understand the crux of the change
-* Its third line, `Changed schema for 'POST /v1/tax_ids' endpoint`, gives both too much and too little information. First of all, it talks about changing schema but it never mentions what exactly changed. Remember: we are doing this to make it easy for our clients to migrate from one version to another. Insteaad, it is much better to mention the openapi model name that you changed, the fields you changed, and why you changed them
+* Its third line, `Changed schema for 'POST /v1/tax_ids' endpoint`, gives both too much and too little information. First of all, it talks about changing schema but it never mentions what exactly changed. Remember: we are doing this to make it easy for our clients to migrate from one version to another. Instead, it is much better to mention the openapi model name that you changed, the fields you changed, and why you changed them
 
 ### VersionChange.instructions_to_migrate_to_previous_version
 
@@ -413,16 +413,13 @@ or to specify migrations using [endpoint path](#path-based-migration-specificati
 Sometimes you will use API versioning to handle a breaking change in your **business logic**, not in the schemas themselves. In such cases, it is tempting to add a version check and just follow the new business logic such as:
 
 ```python
+# This is wrong. Please, do not do this.
 if api_version_var.get() >= date(2022, 11, 11):
     # do new logic here
     ...
 ```
 
-In cadwyn, this approach is **highly** discouraged. It is recommended that you avoid side effects like this at any cost because each one makes your core logic harder to understand. But if you cannot, then I urge you to at least abstract away versions and versioning from your business logic which will make your code much easier to read.
-
-**WARNING**: Side effects are the wrong way to do API Versioning. In 99% of time, you will **not** need them. Please, think twice before using them. API Versioning is about having the same underlying app and data while just changing the schemas and api endpoints to interact with it. By introducing side effects, you leak versioning into your business logic and possibly even your data which makes your code much harder to support in the long term. If each side effect adds a single `if` to your logic, than after 100 versions with side effects, you will have 100 more `if`s. If used correctly, Cadwyn can help you support decades worth of API versions at the same time with minimal costs but side effects make it much harder to do. Changes in the underlying source, structure, or logic of your data should not affect your API or public-facing business logic.
-
-To simplify this, cadwyn has a special `VersionChangeWithSideEffects` class. It makes finding dangerous versions that have side effects much easier and provides a nice abstraction for checking whether we are on a version where these side effects have been applied.
+Instead, Cadwyn provides a special `VersionChangeWithSideEffects` class for handling such cases. It makes finding dangerous versions that have side effects much easier and provides a nice abstraction for checking whether we are on a version where these side effects have been applied.
 
 As an example, let's use the tutorial section's case with the user and their address. Let's say that we use an external service to check whether user's address is listed in it and return 400 response if it is not. Let's also say that we only added this check in the newest version.
 
@@ -432,7 +429,7 @@ from cadwyn import VersionChangeWithSideEffects
 
 class UserAddressIsCheckedInExternalService(VersionChangeWithSideEffects):
     description = (
-        "User's address is now checked for existense in an external service. "
+        "User's address is now checked for existence in an external service. "
         "If it doesn't exist there, a 400 code is returned."
     )
 ```
@@ -450,3 +447,9 @@ async def create_user(payload):
 ```
 
 So this change can be contained in any version -- your business logic doesn't know which version it has and shouldn't.
+
+### Warning against side effects
+
+Side effects are a very powerful tool but they must be used with great caution. Are you sure you MUST change your business logic? Are you sure whatever you are trying to do cannot just be done by a migration? 90% of time, you will **not** need them. Please, think twice before using them. API Versioning is about having the same underlying app and data while just changing the schemas and api endpoints to interact with it. By introducing side effects, you leak versioning into your business logic and possibly even your data which makes your code much harder to support in the long term. If each side effect adds a single `if` to your logic, than after 100 versions with side effects, you will have 100 more `if`s. If used correctly, Cadwyn can help you support decades worth of API versions at the same time with minimal costs, and side effects make it much harder to do. Changes in the underlying source, structure, or logic of your data should not affect your API or public-facing business logic.
+
+However, the [following use cases](../how_to/change_business_logic/index.md) often necessitate side effects.