cadwyn 5.2.2__tar.gz → 5.3.0__tar.gz

{cadwyn-5.2.2 → cadwyn-5.3.0}/CHANGELOG.md

@@ -5,6 +5,12 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [5.3.0]
+
+### Added
+
+* `api_version_title` and `api_version_description` arguments to `Cadwyn` to allow customizing the API version parameter in the OpenAPI schema
+
 ## [5.2.2]
 
 ### Fixed

{cadwyn-5.2.2 → cadwyn-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 5.2.2
+Version: 5.3.0
 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-5.2.2 → cadwyn-5.3.0}/cadwyn/applications.py

@@ -4,7 +4,7 @@ from collections.abc import Awaitable, Callable, Coroutine, Sequence
 from datetime import date
 from logging import getLogger
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Union, cast
+from typing import TYPE_CHECKING, Annotated, Any, Optional, Union, cast
 
 import fastapi
 from fastapi import APIRouter, FastAPI, HTTPException, routing
@@ -71,6 +71,8 @@ class Cadwyn(FastAPI):
         api_version_format: APIVersionFormat = "date",
         api_version_parameter_name: str = "x-api-version",
         api_version_default_value: Union[str, None, Callable[[Request], Awaitable[str]]] = None,
+        api_version_title: Optional[str] = None,
+        api_version_description: Optional[str] = None,
         versioning_middleware_class: type[VersionPickingMiddleware] = VersionPickingMiddleware,
         changelog_url: Union[str, None] = "/changelog",
         include_changelog_url_in_schema: bool = True,
@@ -207,6 +209,8 @@ class Cadwyn(FastAPI):
         self.api_version_format = api_version_format
         self.api_version_parameter_name = api_version_parameter_name
         self.api_version_pythonic_parameter_name = api_version_parameter_name.replace("-", "_")
+        self.api_version_title = api_version_title
+        self.api_version_description = api_version_description
         if api_version_location == "custom_header":
             self._api_version_manager = HeaderVersionManager(api_version_parameter_name=api_version_parameter_name)
             self._api_version_fastapi_depends_class = fastapi.Header
@@ -465,6 +469,8 @@ class Cadwyn(FastAPI):
                             default_value=version,
                             fastapi_depends_class=self._api_version_fastapi_depends_class,
                             validation_data_type=self.api_version_validation_data_type,
+                            title=self.api_version_title,
+                            description=self.api_version_description,
                         )
                     )
                 ],

{cadwyn-5.2.2 → cadwyn-5.3.0}/cadwyn/middleware.py

@@ -5,7 +5,7 @@ import inspect
 import re
 from collections.abc import Awaitable, Callable
 from contextvars import ContextVar
-from typing import Annotated, Any, Literal, Protocol, Union
+from typing import Annotated, Any, Literal, Optional, Protocol, Union
 
 import fastapi
 from fastapi import Request
@@ -58,6 +58,8 @@ def _generate_api_version_dependency(
     default_value: str,
     fastapi_depends_class: Callable[..., Any],
     validation_data_type: Any,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
 ):
     def api_version_dependency(**kwargs: Any):
         # TODO: What do I return?
@@ -69,7 +71,12 @@ def _generate_api_version_dependency(
                 api_version_pythonic_parameter_name,
                 inspect.Parameter.KEYWORD_ONLY,
                 annotation=Annotated[
-                    validation_data_type, fastapi_depends_class(openapi_examples={"default": {"value": default_value}})
+                    validation_data_type,
+                    fastapi_depends_class(
+                        openapi_examples={"default": {"value": default_value}},
+                        title=title,
+                        description=description,
+                    ),
                 ],
                 # Path-based parameters do not support a default value in FastAPI :(
                 default=default_value if fastapi_depends_class != fastapi.Path else inspect.Signature.empty,

cadwyn-5.2.2/docs/concepts/where_to_put_the_version_and_how_to_format_it.md → cadwyn-5.3.0/docs/concepts/api_version_parameter.md

@@ -1,4 +1,4 @@
-# Where to put the version and how to format it
+# API Version Parameter
 
 Cadwyn adds another routing layer to FastAPI by default: by version parameter. This means that before FastAPI tries to route us to the correct route, Cadwyn will first decide on which version of the route to use based on a version parameter. Feel free to look at the example app with URL path version prefixes and arbitrary strings as versions [here](../how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md).
 
@@ -91,3 +91,21 @@ If the app has two versions: 2022-01-02 and 2022-01-05, and the request date par
 Exact match is always preferred over 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.
+
+## 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.
+
+```python
+app = Cadwyn(
+    ...,
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
+```
+
+## API Version Context Variables
+
+Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
+
+You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.

{cadwyn-5.2.2 → cadwyn-5.3.0}/docs/concepts/endpoint_migrations.md

@@ -1,10 +1,10 @@
 # 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 -- both of them are going to be changed as you would expect.
 
 ## Defining endpoints that didn't exist in new versions
 
-If you had an endpoint in old version but do not have it in a new one, you must still define it but mark it as deleted.
+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.
 
 ```python
 @router.only_exists_in_older_versions
@@ -28,7 +28,7 @@ class MyChange(VersionChange):
 
 ## Defining endpoints that didn't exist in old versions
 
-If you have an endpoint in your new version that must not exist in older versions, you define it as usual and then mark it as "non-existing" in old versions:
+If you have an endpoint in your new version that must not exist in older versions for some reason, you define it as usual and then mark it as "non-existing" in old versions. Note that this is [not the recommended approach when adding new endpoints](../how_to/change_endpoints/index.md#add-a-new-endpoint).
 
 ```python
 from cadwyn import VersionChange, endpoint
@@ -58,6 +58,8 @@ class MyChange(VersionChange):
     )
 ```
 
+However, you only need to have a migration if it is a breaking change for your users.
+
 ### Dependency alteration warning
 
 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.

{cadwyn-5.2.2 → cadwyn-5.3.0}/docs/concepts/schema_migrations.md

@@ -2,6 +2,8 @@
 
 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).
+
 ## Add a field to the older version
 
 ```python

{cadwyn-5.2.2 → cadwyn-5.3.0}/docs/concepts/version_changes.md

@@ -93,6 +93,8 @@ HEAD is very similar to your latest version with a few key differences:
 
 `VersionChange` classes describe each atomic group of business capabilities that you have altered in a version.
 
+Note, however, that you only need to have a migration if it is a breaking change for your users. If you add a new endpoint or add a new field to your response schema, you do not need to have a migration for it because your users' code will not break. So by not having a migration you automatically add this change to all versions.
+
 ### VersionChange.\_\_name\_\_
 
 The name of the version change, `RemoveTaxIDEndpoints`, describes what breaking change has happened. It must be a verb and it is the best resource for your new developers to quickly understand what happened between the versions. Do not be shy to use really long names -- it is better to have a long name than to create a misunderstanding. Avoid generic names such as `RefactorUserFields`. Better have an ugly name such as `RenameCreationDatetimeAndUpdateDatetimeToCreatedAtAndUpdatedAt` then to have a generic name such as `RefactorFields`. Because after just a few of such version changes, your versioning structure can become completely unreadable:

{cadwyn-5.2.2 → cadwyn-5.3.0}/docs/how_to/change_openapi_schemas/add_field.md

@@ -14,7 +14,7 @@ Now you have everything you need at your disposal: field `created_at` is availab
 
 Let's say we want our users to be able to specify a middle name but it is nullable. It is not a breaking change so no new version is necessary whether it is requests or responses.
 
-You just need to add a nullable `middle_name` field into `users.BaseUser`
+You just need to add a nullable `middle_name` field into `users.BaseUser` as if you were working with a barebones FastAPI app.
 
 ### Field is required
 
@@ -59,7 +59,6 @@ Let's say that our users had a field `country` that defaulted to `USA` but our p
     )
     ```
 
-
 That's it! Our old schemas will now contain a default but in HEAD country will be required. You might notice a weirdness: if we set a default in the old version, why would we also write a migration? That's because of a sad implementation detail of pydantic that [prevents us](../../concepts/schema_migrations.md#change-a-field-in-the-older-version) from using defaults from old versions.
 
 #### With incompatible default value in older versions
@@ -118,5 +117,4 @@ So we will make `phone` nullable in HEAD, then make it required in `latest`, and
     )
     ```
 
-
 See how we didn't remove the `phone` field from old versions? Instead, we allowed a nullable `phone` field to be passed into both old `UserResource` and old `UserCreateRequest`. This gives our users new functionality without needing to update their API version! It is one of the best parts of Cadwyn's approach: our users can get years worth of updates without switching their API version and without their integration getting broken.

{cadwyn-5.2.2 → cadwyn-5.3.0}/docs/how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md

@@ -3,7 +3,7 @@
 Cadwyn uses version headers with ISO dates by default for versioning. However, you can use any strings instead of ISO dates and/or you can use path version prefixes instead of version headers. Here's our quickstart tutorial example but using version numbers and path prefixes:
 
 Feel free to mix and match the API version formats and version locations as you see fit.
-But beware that Cadwyn does not support [version waterfalling](../concepts/where_to_put_the_version_and_how_to_format_it.md#api-version-waterfalling) for arbitrary strings as versions.
+But beware that Cadwyn does not support [version waterfalling](../concepts/api_version_parameter.md#api-version-waterfalling) for arbitrary strings as versions.
 
 ```python
 {! ./docs_src/how_to/version_with_path_and_numbers_instead_of_headers_and_dates/block001.py !}

{cadwyn-5.2.2 → cadwyn-5.3.0}/mkdocs.yml

@@ -119,8 +119,7 @@ nav:
       - "Endpoint migrations": "concepts/endpoint_migrations.md"
       - "Enum migrations": "concepts/enum_migrations.md"
       - "Schema migrations": "concepts/schema_migrations.md"
-      - "API Version parameter and context variables": "concepts/api_version_parameter_and_context_variables.md"
-      - "Where to put the version and how to format it": "concepts/where_to_put_the_version_and_how_to_format_it.md"
+      - "API Version parameter": "concepts/api_version_parameter.md"
       - "Changelogs": "concepts/changelogs.md"
       - "Testing": concepts/testing.md
   - "Contributing": "home/CONTRIBUTING.md"

{cadwyn-5.2.2 → cadwyn-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cadwyn"
-version = "5.2.2"
+version = "5.3.0"
 description = "Production-ready community-driven modern Stripe-like API versioning in FastAPI"
 authors = [{ name = "Stanislav Zmiev", email = "zmievsa@gmail.com" }]
 license = "MIT"

{cadwyn-5.2.2 → cadwyn-5.3.0}/tests/tutorial/main.py

@@ -123,9 +123,14 @@ async def get_user_addresses(user_id: uuid.UUID):
     return {"data": database_parody[f"addr_{user_id}"]}
 
 
-app = Cadwyn(versions=version_bundle, title="My amazing API")
+app = Cadwyn(
+    versions=version_bundle,
+    title="My amazing API",
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
 app.generate_and_include_versioned_routers(router)
 
 
 if __name__ == "__main__":
-    uvicorn.run(app)
+    uvicorn.run(app, port=8011)

{cadwyn-5.2.2 → cadwyn-5.3.0}/uv.lock

@@ -94,7 +94,7 @@ wheels = [
 
 [[package]]
 name = "cadwyn"
-version = "5.2.2"
+version = "5.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "backports-strenum", marker = "python_full_version < '3.11'" },

cadwyn-5.2.2/docs/concepts/api_version_parameter_and_context_variables.md

@@ -1,5 +0,0 @@
-# API Version parameter and context variables
-
-Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
-
-You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.