cadwyn 4.4.5__tar.gz → 4.5.0__tar.gz

{cadwyn-4.4.5 → cadwyn-4.5.0}/.github/actions/setup-python-uv/action.yaml

@@ -8,7 +8,7 @@ inputs:
   uv-version:
     description: "The uv version to set up"
     required: true
-    default: "0.4.18"
+    default: "0.5.8"
 
 runs:
   using: "composite"
@@ -16,12 +16,12 @@ runs:
     - uses: actions/setup-python@v5
       with:
         python-version: ${{ inputs.python-version }}
-    - uses: astral-sh/setup-uv@v3
+    - uses: astral-sh/setup-uv@v5
       with:
         version: ${{ inputs.uv-version }}
         enable-cache: true
         cache-dependency-glob: "uv.lock"
     - run: |
         uv sync --frozen --all-extras --dev
-        echo "$(pwd)/.venv/bin" >> $GITHUB_PATH
+        uv pip install --system tox tox-uv
       shell: bash

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

@@ -10,7 +10,7 @@ on:
     branches: [main, 3.x.x]
     types: [opened, synchronize]
     paths:
-      - ".github/workflows/ci.yaml"  # self
+      - ".github/workflows/ci.yaml" # self
       - "**.py"
       - "**.toml"
       - "**.lock"
@@ -41,13 +41,13 @@ jobs:
       - uses: ./.github/actions/setup-python-uv
         with:
           python-version: ${{ matrix.python-version }}
-      - run: uv run coverage run --source=. --parallel-mode -m pytest tests
+      - run: tox run -e py
       - name: Upload coverage results
         uses: actions/upload-artifact@v4
         if: matrix.os == 'ubuntu-latest' # Cross-platform coverage combination doesn't work
         with:
           name: coverage-results-${{ matrix.python-version }}
-          path: coverage/
+          path: .coverage*
   Tutorial-tests:
     runs-on: ubuntu-latest
     name: Tutorial tests
@@ -58,13 +58,15 @@ jobs:
           python-version: "3.10"
       - name: Install cadwyn with instructions from docs
         run: sh docs_src/quickstart/setup/block001.sh
-      - run: pip install pytest coverage dirty-equals
-      - run: coverage run --source=. --parallel-mode -m pytest docs_src
+      - run: |
+          pip install uv
+          uv pip install --system pytest coverage dirty-equals
+          coverage run -m pytest docs_src
       - name: Upload coverage results
         uses: actions/upload-artifact@v4
         with:
           name: coverage-results-docs
-          path: coverage/
+          path: .coverage*
   Coverage:
     needs: [Tests, Tutorial-tests]
     runs-on: ubuntu-latest
@@ -75,32 +77,46 @@ jobs:
         with:
           pattern: coverage-results-*
           merge-multiple: true
-          path: coverage/
+          path: .
       - uses: actions/setup-python@v5
         with:
           python-version: "3.10"
-      - run: pip install 'coverage[toml]'
-      - run: coverage combine
-      - run: coverage xml
+      - run: |
+          pip install uv
+          uv pip install --system tox tox-uv
+          tox run -e coverage_report-ci
       - name: Upload to Codecov
         uses: codecov/codecov-action@v4
         env:
           fail_ci_if_error: true
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-      - run: coverage report --fail-under=100 --show-missing
 
   Lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: pre-commit/action@v3.0.0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: |
+          python -m pip install uv
+          uv pip install --system pre-commit pre-commit-uv
+          pre-commit run --all-files
+      - run: tox run -e docs
+      - name: Validate links
+        uses: umbrelladocs/action-linkspector@v1
+        with:
+          reporter: github-pr-review
+          filter_mode: diff_context
+          fail_level: any
 
   Typecheck:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup-python-uv
-
-      - uses: jakebailey/pyright-action@v1
         with:
-          pylance-version: latest-release
+          # When this version is updated,
+          # update the pyright `base_python` version in `tox.ini`, too.
+          python-version: "3.10"
+      - run: tox run -e pyright

{cadwyn-4.4.5 → cadwyn-4.5.0}/.github/workflows/daily_tests.yaml

@@ -21,10 +21,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --refresh --all-extras --dev --upgrade
-      - run: pytest .
-      - uses: jakebailey/pyright-action@v1
-        with:
-          pylance-version: latest-release
+      - run: uv run pytest . # We intentionally don't use tox here to run tests "as is"
+      - run: uv run pyright --version && uv run pyright .
 
   notify-on-failure:
     name: Notify on failure

cadwyn-4.5.0/.github/workflows/validate_links.yaml

@@ -0,0 +1,25 @@
+name: Check Markdown links
+
+on:
+  schedule:
+    # Run everyday at 9:00 AM
+    - cron: "0 9 * * *"
+  workflow_dispatch: # Allows manual triggering of the workflow
+
+jobs:
+  build-docs-to-validate-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-python-uv
+      - run: tox run -e docs
+
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: umbrelladocs/action-linkspector@v1
+        with:
+          reporter: github-check
+          filter_mode: nofilter
+          fail_level: any

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

@@ -5,6 +5,12 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [4.5.0]
+
+### Added
+
+* `check_usage` argument to request/response by schema converters. Cadwyn always checks whether a schema mentioned in a converter applies to one or more endpoints to guarantee that the converter will apply to at least one endpoint. Sometimes, however, you do not need this validation. For example, when you use these converters for converting webhook bodies. Setting `check_usage=False` makes it possible to skip the validation
+
 ## [4.4.5]
 
 ### Fixed

cadwyn-4.5.0/Makefile

@@ -0,0 +1,11 @@
+SHELL := /bin/bash
+py_warn = PYTHONDEVMODE=1
+
+install:
+	uv sync --all-extras --dev
+
+lint:
+	pre-commit run --all-files
+
+test:
+	uv run --with tox --with tox-uv tox

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cadwyn
-Version: 4.4.5
+Version: 4.5.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-4.4.5 → cadwyn-4.5.0}/cadwyn/route_generation.py

@@ -221,6 +221,8 @@ class _EndpointTransformer(Generic[_R, _WR]):
 
             for by_schema_converters in version_change.alter_request_by_schema_instructions.values():
                 for by_schema_converter in by_schema_converters:
+                    if not by_schema_converter.check_usage:  # pragma: no cover
+                        continue
                     missing_models = set(by_schema_converter.schemas) - head_request_bodies
                     if missing_models:
                         raise RouteRequestBySchemaConverterDoesNotApplyToAnythingError(
@@ -232,6 +234,8 @@ class _EndpointTransformer(Generic[_R, _WR]):
                         )
             for by_schema_converters in version_change.alter_response_by_schema_instructions.values():
                 for by_schema_converter in by_schema_converters:
+                    if not by_schema_converter.check_usage:  # pragma: no cover
+                        continue
                     missing_models = set(by_schema_converter.schemas) - head_response_models
                     if missing_models:
                         raise RouteResponseBySchemaConverterDoesNotApplyToAnythingError(
@@ -240,6 +244,9 @@ class _EndpointTransformer(Generic[_R, _WR]):
                             f"failed to find routes with the following response models: "
                             f"{[m.__name__ for m in missing_models]}. "
                             f"This means that you are trying to apply this converter to non-existing endpoint(s). "
+                            "If this is intentional and this converter really does not apply to any endpoints, then "
+                            "pass check_usage=False argument to "
+                            f"{version_change.__name__}.{by_schema_converter.transformer.__name__}"
                         )
 
     def _extract_all_routes_identifiers(

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

@@ -158,7 +158,7 @@ def migrate_response_body(
     *,
     latest_body: Any,
     version: VersionDate | str,
-):
+) -> Any:
     """Convert the data to a specific version
 
     Apply all version changes from latest until the passed version in reverse order

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

@@ -86,6 +86,12 @@ class _AlterDataInstruction:
         return self.transformer(__request_or_response)
 
 
+@dataclass
+class _BaseAlterBySchemaInstruction:
+    schemas: tuple[Any, ...]
+    check_usage: bool = True
+
+
 ##########
 # Requests
 ##########
@@ -97,8 +103,7 @@ class _BaseAlterRequestInstruction(_AlterDataInstruction):
 
 
 @dataclass
-class _AlterRequestBySchemaInstruction(_BaseAlterRequestInstruction):
-    schemas: tuple[Any, ...]
+class _AlterRequestBySchemaInstruction(_BaseAlterBySchemaInstruction, _BaseAlterRequestInstruction): ...
 
 
 @dataclass
@@ -110,7 +115,10 @@ class _AlterRequestByPathInstruction(_BaseAlterRequestInstruction):
 
 @overload
 def convert_request_to_next_version_for(
-    first_schema: type, /, *additional_schemas: type
+    first_schema: type,
+    /,
+    *additional_schemas: type,
+    check_usage: bool = True,
 ) -> "type[staticmethod[_P, None]]": ...
 
 
@@ -123,6 +131,7 @@ def convert_request_to_next_version_for(
     methods_or_second_schema: 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)
 
@@ -141,6 +150,7 @@ def convert_request_to_next_version_for(
             return _AlterRequestBySchemaInstruction(
                 schemas=schemas,
                 transformer=transformer,
+                check_usage=check_usage,
             )
 
     return decorator  # pyright: ignore[reportReturnType]
@@ -158,8 +168,7 @@ class _BaseAlterResponseInstruction(_AlterDataInstruction):
 
 
 @dataclass
-class _AlterResponseBySchemaInstruction(_BaseAlterResponseInstruction):
-    schemas: tuple[Any, ...]
+class _AlterResponseBySchemaInstruction(_BaseAlterBySchemaInstruction, _BaseAlterResponseInstruction): ...
 
 
 @dataclass
@@ -175,6 +184,7 @@ def convert_response_to_previous_version_for(
     /,
     *schemas: type,
     migrate_http_errors: bool = False,
+    check_usage: bool = True,
 ) -> "type[staticmethod[_P, None]]": ...
 
 
@@ -194,6 +204,7 @@ def convert_response_to_previous_version_for(
     /,
     *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)
 
@@ -215,6 +226,7 @@ def convert_response_to_previous_version_for(
                 schemas=schemas,
                 transformer=transformer,
                 migrate_http_errors=migrate_http_errors,
+                check_usage=check_usage,
             )
 
     return decorator  # pyright: ignore[reportReturnType]

{cadwyn-4.4.5 → cadwyn-4.5.0}/docs/how_to/change_openapi_schemas/change_field_type.md

@@ -58,7 +58,6 @@ Additional resources:
 * <https://github.com/OAI/OpenAPI-Specification/issues/1552>
 * <https://users.rust-lang.org/t/solved-is-adding-an-enum-variant-a-breaking-change/26721/5>
 * <https://github.com/graphql/graphql-js/issues/968>
-* <https://medium.com/@jakob.fiegerl/java-jackson-enum-de-serialization-with-rest-backward-compatibility-9c3ec85ac13d>
 
 In these sections, we'll be working with our user's response model: `users.UserResource`. Note that the main theme here is "Will I be able to serialize this change to any of my versions?" as any change to responses can make them incompatible with the data in your database.
 

cadwyn-4.5.0/docs/how_to/change_openapi_schemas/change_schema_without_endpoint.md

@@ -0,0 +1,17 @@
+# Change a schema that is not used in any endpoint
+
+In some situations, we may want to use versioning not just for our openapi schemas and endpoints but also within our code such as when we want to send versioned webhooks to our clients.
+
+For example, let's say we want to change the type of an "id" field from integer to string:
+
+```python
+{!> ../docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/block001.py !}
+```
+
+Unless there is an endpoint that has `User` as its response_model, this code will end up causing an error when we run our Cadwyn app. This is because Cadwyn tries to make sure that all of your converters apply to at least one endpoint. Otherwise, it would be too easy for you to make a mistake when writing converters for the wrong schemas.
+
+To avoid it, set `check_usage=False`:
+
+```python hl_lines="21"
+{!> ../docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/block002.py !}
+```

cadwyn-4.5.0/docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/block001.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+from cadwyn import ResponseInfo, VersionChange, convert_response_to_previous_version_for, schema
+
+
+# User from latest version
+class User(BaseModel):
+    id: str
+
+
+class ChangeUserIDToString(VersionChange):
+    description = (
+        "Change users' ID field to a string to support any kind of ID. "
+        "Be careful: if you use a non-integer ID in a new version and "
+        "try to get it from the old version, the ID will be zero in response"
+    )
+    instructions_to_migrate_to_previous_version = [
+        schema(User).field("id").had(type=int),
+    ]
+
+    @convert_response_to_previous_version_for(User)
+    def change_id_to_int(response: ResponseInfo): ...

cadwyn-4.5.0/docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/block002.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+from cadwyn import ResponseInfo, VersionChange, convert_response_to_previous_version_for, schema
+
+
+# User from latest version
+class User(BaseModel):
+    id: str
+
+
+class ChangeUserIDToString(VersionChange):
+    description = (
+        "Change users' ID field to a string to support any kind of ID. "
+        "Be careful: if you use a non-integer ID in a new version and "
+        "try to get it from the old version, the ID will be zero in response"
+    )
+    instructions_to_migrate_to_previous_version = [
+        schema(User).field("id").had(type=int),
+    ]
+
+    @convert_response_to_previous_version_for(User, check_usage=False)
+    def change_id_to_int(response: ResponseInfo): ...

cadwyn-4.5.0/docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/tests/test_block001.py

@@ -0,0 +1,15 @@
+import pytest
+
+from cadwyn import Cadwyn, Version, VersionBundle
+from cadwyn.exceptions import RouteResponseBySchemaConverterDoesNotApplyToAnythingError
+from docs_src.how_to.change_openapi_schemas.change_schema_without_endpoint.block001 import (
+    ChangeUserIDToString,
+)
+
+versions = VersionBundle(Version("2023-04-12", ChangeUserIDToString), Version("2022-11-16"))
+app = Cadwyn(versions=versions)
+
+
+def test__migrate_to_previous_version__without_check_usage_argument__should_raise_error():
+    with pytest.raises(RouteResponseBySchemaConverterDoesNotApplyToAnythingError):
+        app._cadwyn_initialize()

cadwyn-4.5.0/docs_src/how_to/change_openapi_schemas/change_schema_without_endpoint/tests/test_block002.py

@@ -0,0 +1,14 @@
+from fastapi.testclient import TestClient
+
+from cadwyn import Cadwyn, Version, VersionBundle
+from docs_src.how_to.change_openapi_schemas.change_schema_without_endpoint.block002 import (
+    ChangeUserIDToString,
+)
+
+versions = VersionBundle(Version("2023-04-12", ChangeUserIDToString), Version("2022-11-16"))
+app = Cadwyn(versions=versions)
+
+
+def test__migrate_to_previous_version__with_check_usage_set_to_false__should_not_raise_error():
+    with TestClient(app):
+        ...

cadwyn-4.5.0/docs_src/quickstart/tutorial/tests/test_block003.py

@@ -0,0 +1,36 @@
+import pytest
+from dirty_equals import IsUUID
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture
+def client():
+    from docs_src.quickstart.tutorial.block003 import app
+
+    return TestClient(app)
+
+
+def test__basic_post__with_version_2000(client: TestClient):
+    response = client.post("/users", json={"address": "123 Example St"}, headers={"x-api-version": "2000-01-01"})
+    assert response.status_code == 200, response.json()
+    assert response.json() == {"id": IsUUID(4), "address": "123 Example St"}
+
+    user_id = response.json()["id"]
+
+    response = client.get(f"/users/{user_id}", headers={"x-api-version": "2000-01-01"})
+    assert response.status_code == 200, response.json()
+    assert response.json() == {"id": user_id, "address": "123 Example St"}
+
+
+def test__basic_post__with_version_2001(client: TestClient):
+    response = client.post(
+        "/users", json={"addresses": ["123 John St", "456 Smith St"]}, headers={"x-api-version": "2001-01-01"}
+    )
+    assert response.status_code == 200, response.json()
+    assert response.json() == {"id": IsUUID(4), "addresses": ["123 John St", "456 Smith St"]}
+
+    user_id = response.json()["id"]
+
+    response = client.get(f"/users/{user_id}", headers={"x-api-version": "2001-01-01"})
+    assert response.status_code == 200, response.json()
+    assert response.json() == {"id": user_id, "addresses": ["123 John St", "456 Smith St"]}

{cadwyn-4.4.5 → cadwyn-4.5.0}/mkdocs.yml

@@ -97,6 +97,7 @@ nav:
           - "Rename a field": "how_to/change_openapi_schemas/rename_a_field_in_schema.md"
           - "Change field type": "how_to/change_openapi_schemas/change_field_type.md"
           - "Change field constraints or validators": "how_to/change_openapi_schemas/changing_constraints.md"
+          - "Change a schema that is not used in any endpoint": "how_to/change_openapi_schemas/change_schema_without_endpoint.md"
       - "Change business logic": "how_to/change_business_logic/index.md"
       - "Change endpoints": "how_to/change_endpoints/index.md"
 

{cadwyn-4.4.5 → cadwyn-4.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cadwyn"
-version = "4.4.5"
+version = "4.5.0"
 description = "Production-ready community-driven modern Stripe-like API versioning in FastAPI"
 authors = [{ name = "Stanislav Zmiev", email = "zmievsa@gmail.com" }]
 license = "MIT"
@@ -64,7 +64,6 @@ standard = ["fastapi[standard]>=0.112.3", "typer>=0.7.0"]
 
 [tool.uv]
 dev-dependencies = [
-    "pdbpp ~=0.10.3",
     "python-multipart >=0.0.6",
     "better-devtools ~=0.13.3",
     "pytest-sugar ~=1.0.0",
@@ -76,12 +75,15 @@ dev-dependencies = [
     "pytest-cov >=4.0.0",
     "dirty-equals >=0.6.0",
     "uvicorn ~=0.23.0",
+    # type checking
+    "pyright>=1.1.390",
     # docs
     "mkdocs >=1.5.2",
     "mkdocs-material >=9.3.1",
     "mkdocs-simple-hooks >=0.1.5",
     "mdx-include ~=1.4.2",
     "mike >=2.1.2, <3",
+    "pdbpp>=0.10.3",
 ]
 
 [project.urls]
@@ -99,6 +101,7 @@ parallel = true
 branch = true
 
 [tool.coverage.report]
+fail_under = 100
 skip_covered = true
 skip_empty = true
 # Taken from https://coverage.readthedocs.io/en/7.1.0/excluding.html#advanced-exclusion
@@ -119,6 +122,7 @@ exclude_lines = [
     "@(typing\\.)?overload",
     "__rich_repr__",
     "__repr__",
+    "def .+: \\.\\.\\.",
 ]
 omit = ["./docs/plugin.py", "./site/plugin.py", "scripts/*.py"]
 

{cadwyn-4.4.5 → cadwyn-4.5.0}/ruff.toml

@@ -127,6 +127,9 @@ ignore = [
     "PGH003", # Use specific rule codes when ignoring type issues
     "B008",   # Do not perform function call in argument defaults
 ]
+"docs_src/**/*" = [
+    "RUF012", # Mutable class attributes should be annotated with `typing.ClassVar`
+]
 "cadwyn/_utils.py" = [
     "ERA001", # Found commented-out code (it's not actually commented out. It's just comments)
 ]

{cadwyn-4.4.5 → cadwyn-4.5.0}/tests/test_cli.py

@@ -1,4 +1,3 @@
-import sys
 import textwrap
 
 import pytest
@@ -9,7 +8,7 @@ from cadwyn.__main__ import app
 
 
 def code(c: str) -> str:
-    return textwrap.dedent(c.strip())
+    return "\n".join(line.rstrip() for line in textwrap.dedent(c.strip()).splitlines())
 
 
 def test__render_module():
@@ -70,14 +69,7 @@ def test__render_model__with_syntax_highlighting():  # pragma: no cover
         ],
     )
     assert result.exit_code == 0
-
-    if sys.platform.startswith("win32"):
-        # Windows rendering is weird
-        return
-
-    assert code(result.stdout) == (
-        "1 class A(BaseModel):                                                         \n  2     pass"
-    )
+    assert code(result.stdout) == "1 class A(BaseModel):\n  2     pass"
 
 
 @pytest.mark.parametrize("arg", ["-V", "--version"])

cadwyn-4.5.0/tox.ini

@@ -0,0 +1,61 @@
+[tox]
+envlist =
+    coverage_erase
+    # When updating Python versions, use search-and-replace
+    # against the entire list of of versions
+    # to ensure consistency throughout this file.
+    py{3.13, 3.12, 3.11, 3.10}
+    coverage_report
+    docs
+    pyright
+
+
+[testenv]
+runner = uv-venv-lock-runner
+with_dev = true
+extras =
+    standard
+package = wheel
+wheel_build_env = build_wheel
+depends =
+    py{3.13, 3.12, 3.11, 3.10}: coverage_erase
+commands = coverage run -m pytest {posargs}
+
+
+[testenv:coverage_erase]
+skip_install = true
+commands = coverage erase
+
+
+[testenv:coverage_report]
+skip_install = true
+depends =
+    py{3.13, 3.12, 3.11, 3.10}
+commands_pre =
+    # Ignore the exit code of `coverage combine`
+    # (in case the reports are already combined).
+    - coverage combine
+commands =
+    coverage report --show-missing
+
+
+[testenv:coverage_report-ci]
+# Inherit everything from the `coverage_report` environment,
+# but generate an XML report and ignore exit codes.
+base = coverage_report
+commands =
+    - coverage xml --fail-under=0
+    - coverage report --show-missing
+
+
+[testenv:docs]
+base_python = py3.10
+skip_install = true
+commands = mkdocs build --strict
+
+
+[testenv:pyright]
+# When the Python version is updated here,
+# update the version used in the CI `Typecheck` job, too.
+base_python = py3.10
+commands = pyright