cadwyn 5.4.4__tar.gz → 5.4.5__tar.gz

{cadwyn-5.4.4 → cadwyn-5.4.5}/CHANGELOG.md

@@ -92,17 +92,17 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 * `__doc__` attribute is now copied from the original enum to the generated enum
 * Python 3.12 type aliases and their typing_extensions backports are now supported (including `pydantic.JsonValue` and other `typing_extensions.TypeAliasType` instances)
 * The bug when solve_dependencies error on the migration of a request to the latest version responds with a non-json serializable error and cadwyn showed a failed to serialize error instead of the actual error
-* Updated minimum fastapi version to 0.112.4 because embed_body_fields was added in 0.112.4
+* Updated minimum FastAPI version to 0.112.4 because embed_body_fields was added in 0.112.4
 
 ## [5.1.2]
 
 ### Fixed
 
-* Generators not being called when fastapi validates the initial request
+* Generators not being called when FastAPI validates the initial request
 
 ### Added
 
-* `cadwyn.current_dependency_solver` function to check whether cadwyn or fastapi is currently solving dependencies. It can be used as a dependency for versioned endpoints like so: `current_dependency_solver: Annotated[Literal["fastapi", "cadwyn"], Depends(current_dependency_solver)]`. If your dependency has side effects, you would likely want to only run it once per request. If you want to run it once we migrated the request to the latest version, you should only run it when `current_dependency_solver` is `"cadwyn"`. If you want your dependency to run at the very beginning of handling the request, you should only run it when `current_dependency_solver` is `"fastapi"`.
+* `cadwyn.current_dependency_solver` function to check whether cadwyn or FastAPI is currently solving dependencies. It can be used as a dependency for versioned endpoints like so: `current_dependency_solver: Annotated[Literal["fastapi", "cadwyn"], Depends(current_dependency_solver)]`. If your dependency has side effects, you would likely want to only run it once per request. If you want to run it once we migrated the request to the latest version, you should only run it when `current_dependency_solver` is `"cadwyn"`. If you want your dependency to run at the very beginning of handling the request, you should only run it when `current_dependency_solver` is `"fastapi"`.
 
 ## [5.1.1]
 
@@ -309,7 +309,7 @@ Versions 3.x.x are still supported in terms of bug and security fixes but all th
 
 ### Changed
 
-* `Cadwyn.enrich_swagger` is now completely unnecessary: openapi is now generated at runtime. It also now does not do anything, is deprecated, and will be removed in a future version
+* `Cadwyn.enrich_swagger` is now completely unnecessary: OpenAPI is now generated at runtime. It also now does not do anything, is deprecated, and will be removed in a future version
 
 ### Fixed
 
@@ -330,7 +330,7 @@ Versions 3.x.x are still supported in terms of bug and security fixes but all th
 
 ### Fixed
 
-* Openapi not being generated when lifespan was used
+* OpenAPI not being generated when lifespan was used
 
 ## [3.15.1]
 
@@ -455,7 +455,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 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.
+* 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]
 
@@ -713,13 +713,13 @@ Versions 3.x.x are still supported in terms of bug and security fixes but all th
 
 ### Fixed
 
-* Custom body fields created by fastapi caused an exception. Now they are ignored
+* Custom body fields created by FastAPI caused an exception. Now they are ignored
 
 ## [2.0.2]
 
 ### Added
 
-* A link to openapi discussion on enum expansion into docs/recipes
+* A link to OpenAPI discussion on enum expansion into docs/recipes
 * A link to intercom's API versioning article into docs/theory
 
 ## [2.0.1]

{cadwyn-5.4.4 → cadwyn-5.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 5.4.4
+Version: 5.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
@@ -88,26 +88,3 @@ The [documentation](https://docs.cadwyn.dev) has everything you need to succeed.
 ## Sponsors
 
 These are our gorgeous sponsors. They are using Cadwyn and are sponsoring it through various means. Contact [me](https://github.com/zmievsa) if you would like to become one, too!
-
-## Contributors
-
-<details>
-
-<summary>Thanks goes to these wonderful people:</summary>
-<a href="https://allcontributors.org/docs/en/emoji-key">Emoji Key </a>
-
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
-Contributions are welcome!
-
-</details>
-
-<!-- contributors-end -->

{cadwyn-5.4.4 → cadwyn-5.4.5}/README.md

@@ -40,26 +40,3 @@ The [documentation](https://docs.cadwyn.dev) has everything you need to succeed.
 ## Sponsors
 
 These are our gorgeous sponsors. They are using Cadwyn and are sponsoring it through various means. Contact [me](https://github.com/zmievsa) if you would like to become one, too!
-
-## Contributors
-
-<details>
-
-<summary>Thanks goes to these wonderful people:</summary>
-<a href="https://allcontributors.org/docs/en/emoji-key">Emoji Key </a>
-
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
-Contributions are welcome!
-
-</details>
-
-<!-- contributors-end -->

{cadwyn-5.4.4 → cadwyn-5.4.5}/cadwyn/changelogs.py

@@ -2,14 +2,8 @@ import copy
 import sys
 from enum import auto
 from logging import getLogger
-from typing import Any, Literal, TypeVar, Union, cast, get_args
+from typing import TYPE_CHECKING, Any, Literal, TypeVar, Union, cast, get_args
 
-from fastapi._compat import (
-    GenerateJsonSchema,
-    ModelField,
-    get_compat_model_name_map,
-    get_definitions,
-)
 from fastapi.openapi.constants import REF_TEMPLATE
 from fastapi.openapi.utils import (
     get_fields_from_routes,
@@ -41,6 +35,9 @@ from .structure.schemas import (
     ValidatorExistedInstruction,
 )
 
+if TYPE_CHECKING:
+    from fastapi._compat import ModelField
+
 if sys.version_info >= (3, 11):  # pragma: no cover
     from enum import StrEnum
 else:  # pragma: no cover
@@ -120,7 +117,7 @@ def _get_affected_model_names(
         FieldDidntHaveInstruction,
     ],
     generator_from_newer_version: SchemaGenerator,
-    schemas_from_last_version: list[ModelField],
+    schemas_from_last_version: "list[ModelField]",
 ):
     changed_model = generator_from_newer_version._get_wrapper_for_model(instruction.schema)
     annotations = [model.field_info.annotation for model in schemas_from_last_version]
@@ -156,6 +153,13 @@ def _get_all_pydantic_models_from_generic(annotation: Any) -> list[type[BaseMode
 
 
 def _get_openapi_representation_of_a_field(model: type[BaseModel], field_name: str) -> dict:
+    from fastapi._compat import (
+        GenerateJsonSchema,
+        ModelField,
+        get_compat_model_name_map,
+        get_definitions,
+    )
+
     class CadwynDummyModelForRepresentation(BaseModel):
         my_field: model
 
@@ -315,7 +319,7 @@ def _convert_version_change_instruction_to_changelog_entry(  # noqa: C901
     version_change: type[VersionChange],
     generator_from_newer_version: SchemaGenerator,
     generator_from_older_version: SchemaGenerator,
-    schemas_from_older_version: list[ModelField],
+    schemas_from_older_version: "list[ModelField]",
     routes_from_newer_version: list[APIRoute],
 ):
     if isinstance(instruction, EndpointDidntExistInstruction):

{cadwyn-5.4.4 → cadwyn-5.4.5}/cadwyn/schema_generation.py

@@ -541,7 +541,7 @@ class _AsyncGeneratorCallableWrapper(_CallableWrapper):
 class _AnnotationTransformer:
     def __init__(self, generator: "SchemaGenerator") -> None:
         # 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.
+        # because such copies could produce weird behaviors at runtime, especially if you/FastAPI do any comparisons.
         # It's defined here and not on the method because of this: https://youtu.be/sVjtp6tGo0g
         self.generator = generator
         # TODO: Rewrite this to memoize

{cadwyn-5.4.4 → cadwyn-5.4.5}/cadwyn/structure/endpoints.py

@@ -18,7 +18,7 @@ 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.
+    # 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

{cadwyn-5.4.4 → cadwyn-5.4.5}/cadwyn/structure/versions.py

@@ -694,7 +694,7 @@ class VersionBundle:
 # We use this instead of `.body()` to automatically guess body type and load the correct body, even if it's a form
 async def _get_body(
     request: FastapiRequest, body_field: Union[ModelField, None], exit_stack: AsyncExitStack
-):  # pragma: no cover # This is from fastapi
+):  # pragma: no cover # This is from FastAPI
     is_body_form = body_field and isinstance(body_field.field_info, params.Form)
     try:
         body: Any = None

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/api_version_parameter.md

@@ -63,7 +63,7 @@ app = Cadwyn(
 )
 ```
 
-In which case only dates will be accepted as valid versions.
+In the example above only dates will be accepted as valid versions.
 
 You can also use an arbitrary string:
 
@@ -80,21 +80,21 @@ app = Cadwyn(
 )
 ```
 
-In which case any string will be accepted as a valid version. Notice how they do not have to be sortable or even ordered. Cadwyn will assume that their actual order is the same as the order of the versions in the `VersionBundle`.
+In the example above any string will be accepted as a valid version. Arbitrary strings can be used, Cadwyn will not sort them. Cadwyn will assume their actual order matches the order of the versions in the `VersionBundle`.
 
 ### API Version waterfalling
 
 For historical reasons, date-based routing also supports waterfalling the requests to the closest earlier version of the API if the request date parameter doesn't match any of the versions exactly.
 
-If the app has two versions: 2022-01-02 and 2022-01-05, and the request date parameter is 2022-01-03, then the request will be routed to 2022-01-02 version as it the closest version, but lower than the request date parameter.
+If the app has two versions: 2022-01-02 and 2022-01-05, and the request date parameter is 2022-01-03, then the request will be routed to the 2022-01-02 version, as it is the closest version, but lower than the request date parameter.
 
-Exact match is always preferred over partial match and a request will never be matched to the higher versioned route.
+An exact match is always preferred to a partial match and a request will never be matched to the higher-versioned route.
 
-We implement routing like this because Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. For example, imagine that you have two Cadwyn services: Payables and Receivables, each defining its own API versions. Payables service might contain 10 versions while receivables service might contain only 2 versions because it didn't need as many breaking changes. If a client requests a version that does not exist in receivables -- we will just waterfall to some earlier version, making receivables behavior consistent even if API keeps getting new versions.
+We implement routing like this because Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. For example, imagine that you have two Cadwyn services: Payables and Receivables, each defining its own API versions. Payables service might contain 10 versions while Receivables service might contain only 2 versions because it didn't need as many breaking changes. If a client requests a version that does not exist in Receivables, we will just waterfall to some earlier version, making Receivables behavior consistent even if API keeps getting new versions.
 
 ## API Version Parameter Title and Description
 
-You can pass a title and/or a description to `Cadwyn` constructor. They are equivalent to passing `title` and `description` to `fastapi.Path` or `fastapi.Header` constructors.
+You can pass a title and/or a description to the `Cadwyn` constructor. It is equivalent to passing `title` and `description` to `fastapi.Path` or `fastapi.Header` constructors.
 
 ```python
 app = Cadwyn(

cadwyn-5.4.5/docs/concepts/beware_of_data_versioning.md

@@ -0,0 +1,9 @@
+# Beware of data versioning
+
+Oftentimes you will want to introduce a breaking change where one of the following is true:
+
+* Old data cannot be automatically converted to the structure of the new response
+* New response cannot be automatically migrated to an older response
+* Old request cannot be automatically converted to the HEAD request
+
+This means that you are not versioning your API, you are versioning your **data**. This cannot be solved by an API versioning framework. It also makes it incredibly hard to version as you now cannot guarantee compatibility between versions. Avoid this at all costs -- all your API versions must be compatible between each other. Data versioning is not a result of a complicated use case, it is a result of **errors** when divising a new version. I am yet to meet a single case where data versioning is the right way to solve an API versioning problem.

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/changelogs.md

@@ -27,11 +27,11 @@ class CompletelyHiddenVersionChange(VersionChange):
 
 ## Customizing changelog endpoint
 
-Just pass the `changelog_url` argument to `Cadwyn` and a `GET` to this url will start returning the changelog for all versions based on the contents of your `VersionBundle`.
+The changelog endpoint name can be customized by specifying a new name via the `changelog_url` argument to the `Cadwyn()` constructor. Accessing this url via the `GET` request will return the changelog for all versions based on the content of your `VersionBundle`.
 
-If you want to hide the changelog endpoint, pass `include_changelog_url_in_schema=False` to `Cadwyn`.
+If you want to hide the changelog endpoint, pass `include_changelog_url_in_schema=False` to `Cadwyn()`.
 
-If you want to delete the changelog endpoint, pass `changelog_url=None` to `Cadwyn`.
+If you want to delete the changelog endpoint, pass `changelog_url=None` to `Cadwyn()`.
 
 ## Changelog structure and entry types
 

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/cli.md

@@ -1,7 +1,7 @@
 # CLI
 
-Cadwyn has an optional CLI interface that can be installed with `pip install 'cadwyn[standard]'`.
-You can run `cadwyn --version` to check current version of Cadwyn.
+Cadwyn has an optional CLI that can be installed with `pip install 'cadwyn[standard]'`.
+You can run `cadwyn --version` to check the current version of Cadwyn.
 
 Its main purpose is [rendering generated schemas](./schema_generation.md#rendering-schemas).
 

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/endpoint_migrations.md

@@ -1,8 +1,8 @@
 # Endpoint migrations
 
-Note that the `endpoint(...)` constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- both of them are going to be changed as you would expect.
+Note that the `endpoint(...)` constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- as expected, both of them will be changed.
 
-## Defining endpoints that didn't exist in new versions
+## Defining endpoints that didn't exist for new versions
 
 If you had an endpoint in an old version **but want to delete it in a new version**, you must still define it as usual with all your other endpoints but mark it as deleted.
 
@@ -43,7 +43,7 @@ class MyChange(VersionChange):
 
 ## Changing endpoint attributes
 
-If you want to change any attribute of your endpoint in a new version, you can return the attribute's value in all older versions like so:
+If you want to change any attribute of your endpoint in a new version, you can return the attribute's value in all older versions like this:
 
 ```python
 from cadwyn import VersionChange, endpoint
@@ -64,11 +64,11 @@ However, you only need to have a migration if it is a breaking change for your u
 
 Note that changing endpoint `dependencies` is only going to affect the initial validation. So Cadwyn will take your altered dependencies and run them on each request to the endpoint but ultimately your endpoint code is always going to use the HEAD version of your dependencies. So be careful.
 
-Note also that if some of your dependencies were added at app/router level -- they **are** going to be overwritten by this instruction. Most of the time it is rather safe, however, as all the necessary dependencies will still run on HEAD version.
+Also note that if some of your dependencies were added at app/router level, they **are** going to be overwritten by this instruction. Most of the time it is rather safe, however, as all the necessary dependencies will still run on HEAD version.
 
 ## Dealing with endpoint duplicates
 
-Sometimes, when you're doing some advanced changes in between versions, you will need to rewrite your endpoint function entirely. So essentially you'd have the following structure:
+Sometimes, when you're doing some advanced changes in between versions, you need to rewrite your endpoint function entirely. So essentially you'd have the following structure:
 
 ```python
 from fastapi.params import Param
@@ -92,7 +92,7 @@ def get_users_by_name(user_name: Annotated[str, Param()]):
     """Do some logic with user_name"""
 ```
 
-As you see, these two functions have the same methods and paths. And when you have many versions, you can have even more functions like these two. So how do we ask cadwyn to restore only one of them and delete the other one?
+As you see, these two functions have the same parameters and path decorators. And when you have many versions, you can have even more functions like these two. So how do we ask cadwyn to restore only one of them and delete the other one?
 
 ```python
 from cadwyn import VersionChange, endpoint
@@ -104,8 +104,8 @@ class UseParamsInsteadOfHeadersForUserNameFiltering(VersionChange):
         "because using headers is a bad API practice in such scenarios."
     )
     instructions_to_migrate_to_previous_version = (
-        # We need to specify the name, otherwise, we will encounter an exception due to having two identical endpoints
-        # with the same path and method
+        # We need to specify the name, otherwise, we will encounter an exception due to
+        # having two identical endpoints with the same parameters and path decorators
         endpoint(
             "/users",
             ["GET"],
@@ -117,4 +117,4 @@ class UseParamsInsteadOfHeadersForUserNameFiltering(VersionChange):
     )
 ```
 
-So by using a more concrete `func_name`, we are capable to distinguish between different functions that affect the same routes.
+So by using a more concrete `func_name`, we are able to distinguish between different functions that affect the same routes.

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/enum_migrations.md

@@ -1,10 +1,10 @@
 # Enum migrations
 
-All of the following instructions affect only openapi schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
+All of the following instructions affect only OpenAPI schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
 
 ## Adding enum members
 
-Note that adding enum members **can** be a breaking change unlike adding optional fields to a schema. For example, if I return a list of entities, each of which has some type, and I add a new type -- then my client's code is likely to break.
+Note that adding enum members **can** be a breaking change unlike adding optional fields to a schema. For example, if I return a list of entities, each of which has some type, and I add a new type, then my client's code is likely to break.
 
 So I suggest adding enum members in new versions as well.
 

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/index.md

@@ -1,8 +1,8 @@
 # Concepts
 
-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.
+This section covers the entirety of features and their rationale in Cadwyn. It can also be used as 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 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.
+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. With Cadwyn you avoid duplicating any 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-5.4.4 → cadwyn-5.4.5}/docs/concepts/main_app.md

@@ -1,11 +1,11 @@
 # Main App
 
-Cadwyn's standard usage is done with a single customized FastAPI app: `cadwyn.Cadwyn`. It accepts all the same arguments as `FastAPI` three more keyword-only arguments:
+Cadwyn's standard usage involves a single customized FastAPI app: `cadwyn.Cadwyn`. It accepts all the same arguments as `FastAPI` does and two more keyword-only arguments:
 
 * Required `versions: VersionBundle` describes [all versions](./version_changes.md#versionbundle) within your application
 * Optional `api_version_parameter_name: str = "x_api_version"` is the parameter that Cadwyn will use for [routing](#routing) to different API versions of your app
 
-After you have defined a main app, you can add versioned API routers to it using `Cadwyn.generate_and_include_versioned_routers(*routers)`
+After you have defined the main app, you can add versioned API routers to it using `Cadwyn.generate_and_include_versioned_routers(*routers)`
 
 ```python
 from cadwyn import VersionedAPIRouter, Cadwyn
@@ -33,9 +33,9 @@ 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. 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`.
+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 a date that does not have an exact match, 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).
+However, header-based routing is the default way to use Cadwyn. If you want to use any other form 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).
 
 ### VersionedAPIRouter
 

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/methodology.md

@@ -2,12 +2,12 @@
 
 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
+* Each version consists of "version changes" or "compatibility gates" which describe **independent, atomic** differences from the previous version
 * 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
-* Any backwards compatible features must be backported to all compatible versions
+* Any backward-compatible features must be backported to all compatible versions
 
 These rules give us an ability to have a large number of self-documenting versions while encapsulating their complexity in small version change classes, providing a consistent and stable experience to our users.
 

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/schema_generation.md

@@ -4,13 +4,13 @@ Cadwyn automatically generates versioned schemas and everything related to them
 
 ## Rendering schemas
 
-When you have many versions and many schemas, it is quite hard to know what validators, fields, and other attributes are defined on each schema in any concrete version. To combat this problem, we have a way to **render** the generated pydantic models and enums to code using the command-line interface.
+When you have many versions and schemas, it is quite challenging to know what validators, fields, and other attributes are defined on each schema in any specific version. To address this issue, there is a way to **render** the generated pydantic models and enums as code using the command-line interface.
 
-**NOTICE** that `cadwyn render` does not promise to render correct schemas. It is going to be a very close approximation which should be enough for the cases where humans check the schemas by hand. However, it is not yet ready to be used for full blown code generation. For example, it doesn't handle schema renamings in class `__bases__` yet.
+**NOTICE** that `cadwyn render` does not guarantee rendering correct schemas. It is going to be a close enough approximation for manual validation. However, it is not yet ready to be used for production code generation. For example, it doesn't handle schema renamings in class `__bases__` yet.
 
 ### Rendering a module
 
-Here's how you would render the entire module with your schemas:
+Here's a way to render the entire module with the schemas:
 
 ```bash
 cadwyn render module data.schemas --app=main:app --version=2024-05-26
@@ -20,7 +20,7 @@ This command will print to stdout what the schemas would look like in version 20
 
 ### Rendering a single model
 
-Here's how you would render a single pydantic model or enum with your schemas:
+Here's a way to render a single pydantic model or enum with the schemas:
 
 ```bash
 cadwyn render model data.schemas:UserCreateRequest --app=main:app --version=2024-05-26
@@ -34,6 +34,7 @@ Cadwyn is capable of generating versioned schemas from its version changes even
 
 ```python
 import cadwyn
+from cadwyn.schema_generation import generate_versioned_models
 from my_versions import version_bundle, MyVersionedSchema
 
 schema_generators = generate_versioned_models(version_bundle)

{cadwyn-5.4.4 → cadwyn-5.4.5}/docs/concepts/schema_migrations.md

@@ -1,14 +1,14 @@
 # Schema migrations
 
-All of the following instructions affect only openapi schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
+All of the following instructions affect only OpenAPI schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
 
-Please note that you only need to have a migration if it is a breaking change for your users. The scenarios below only describe "what you can do" but not "what you should do". For the "should", please refer to the [how-to docs](../how_to/change_openapi_schemas/add_field.md).
+Please note that you only need to have a migration if it is a breaking change for your users. The scenarios below only describe "what you can do" but not "what you should do". For the "should" part, please refer to the [how-to docs](../how_to/change_openapi_schemas/add_field.md).
 
 ## Add a field to the older version
 
 ```python
-from pydantic import Field
 from cadwyn import VersionChange, schema
+from pydantic import Field
 
 
 class MyChange(VersionChange):
@@ -35,7 +35,7 @@ class MyChange(VersionChange):
 
 ## Change a field in the older version
 
-If you would like to set a description or any other attribute of a field, you would do:
+The following code allows to set an attribute of a field, such as a description:
 
 ```python
 from cadwyn import VersionChange, schema
@@ -48,7 +48,7 @@ class MyChange(VersionChange):
     )
 ```
 
-and if you would like to unset any attribute of a field as if it was never passed, you would do:
+The following code allows to un-set an attribute of a field, as if it never existed:
 
 ```python
 from cadwyn import VersionChange, schema
@@ -65,23 +65,23 @@ class MyChange(VersionChange):
 
 If you add `default` or `default_factory` into the old version of a schema -- it will not manifest in code automatically. Instead, you should add both the `default` or `default_factory`, and then also add the default value using a request migration.
 
-This happens because of how Cadwyn works with pydantic and sadly cannot be changed:
+The reason for such behaviour is the way how Cadwyn works with pydantic and unfortunately this cannot be changed:
 
 Cadwyn:
 
-1. Receives the request of some version `V`
+1. Receives a request for API version `V`
 2. Validates the request using the schemas from `V`
 3. Marshalls the unmarshalled request body into a raw data structure using `BaseModel.dict` (`BaseModel.model_dump` in Pydantic v2) using **exclude_unset=True**
 4. Passes the request through all request migrations from `V` to `latest`
 5. Validates the request using `latest` schemas
 
-The part that causes the aforementioned problem is our usage of `exclude_unset=True`. Sadly, when we use it, all default fields do not get set so `latest` does not receive them. And if `latest` does not have the same defaults (for example, if the field has no default and is required in `latest`), then an error will occur. If we used `exclude_unset=False`, then `exclude_unset` would lose all its purpose for the users of our library so we cannot abandon it. Instead, you should set all extra on step 4 in your request migrations.
+The part that causes the aforementioned problem is cadwyn's usage of `exclude_unset=True`. Unfortunately, when we use it, all default fields do not get set, so `latest` does not receive them. And if `latest` does not have the same defaults (for example, if the field has no default and is required in `latest`), then an error will occur. If we used `exclude_unset=False`, then `exclude_unset` would lose all its purpose for the users of our library so we cannot give it up. Instead, you should set all extras on step 4 in your request migrations.
 
 ## Add a validator to the older version
 
 ```python
-from pydantic import Field, field_validator
 from cadwyn import VersionChange, schema
+from pydantic import Field, field_validator
 
 
 @field_validator("foo")
@@ -101,8 +101,8 @@ class MyChange(VersionChange):
 ## Remove a validator from the older version
 
 ```python
-from pydantic import Field, validator
 from cadwyn import VersionChange, schema
+from pydantic import Field, validator
 
 
 class MyChange(VersionChange):
@@ -114,7 +114,8 @@ class MyChange(VersionChange):
 
 ## Rename a schema in the older version
 
-If you wish to rename your schema to make sure that its name is different in openapi.json:
+The following code allows to replace all schema name occurrences with the new one to make sure that the name is different in openapi.json:
+
 
 ```python
 from cadwyn import VersionChange, schema
@@ -126,5 +127,3 @@ class MyChange(VersionChange):
         schema(MySchema).had(name="OtherSchema"),
     )
 ```
-
-which will replace all references to this schema with the new name.

cadwyn-5.4.5/docs/concepts/testing.md

@@ -0,0 +1,35 @@
+# Testing
+
+As Cadwyn allows to keep the same business logic, database schemas, etc -- you should have a single set of **common** tests that test the current latest version. These tests are going to work like the regular tests that you would have if you did not have any API versioning.
+
+Here's a possible structure for test files:
+
+```tree
+└── tests
+    ├── __init__.py
+    ├── conftest.py
+    ├── head
+    │   ├── __init__.py
+    │   ├── conftest.py
+    │   ├── test_users.py
+    │   ├── test_admins.py
+    │   └── test_invoices.py
+    ├── v2022_11_16
+    │   ├── __init__.py
+    │   ├── conftest.py
+    │   └── test_invoices.py
+    └── v2023_03_11
+        ├── __init__.py
+        ├── conftest.py
+        └── test_users.py
+
+```
+
+The following process is recommended when creating a new version:
+
+1. Before creating a new version, apply the changes you want to your logic and schemas in the latest version (i.e., make the desired breaking changes), and then run the tests in the head directory. The tests that fail indicate the broken contracts
+1. Create a new sub-directory in `tests`, name it after the previous version (e.g., v2024_05_04), and copy only the failing tests into it. Ensure these tests invoke the old version of the API
+1. Write a `VersionChange` that fixes the tests in this outdated version through converters. In the new version, these same tests should still fail
+1. Modify the tests in the head directory so that they test the new API contract and pass successfully
+
+This approach helps to keep the old versions covered by tests and to keep the test code duplication minimal.