fastapi-router-versioning 0.2.3__tar.gz → 0.2.5__tar.gz

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/.github/workflows/pre-commit.yml

@@ -32,6 +32,8 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
+          # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
+          # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
           version: "0.11.18"
           cache-dependency-glob: |
             pyproject.toml
@@ -44,8 +46,8 @@ jobs:
         # Only lint files changed in this PR, not the entire repo
         run: uv run prek run --from-ref origin/${GITHUB_BASE_REF} --to-ref HEAD --show-diff-on-failure
 
-  # Required by GitHub branch protection rules
-  pre-commit-alls-green:
+  # https://github.com/marketplace/actions/alls-green#why
+  pre-commit-alls-green:  # This job does nothing and is only used for the branch protection
     if: always()
     needs:
       - pre-commit

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/.github/workflows/test-redistribute.yml

@@ -12,6 +12,7 @@ jobs:
   changes:
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       pull-requests: read
     timeout-minutes: 5
     outputs:
@@ -74,7 +75,7 @@ jobs:
           pip wheel --no-deps fastapi_router_versioning*.tar.gz
 
   # https://github.com/marketplace/actions/alls-green#why
-  test-redistribute-alls-green:
+  test-redistribute-alls-green:  # This job does nothing and is only used for the branch protection
     if: always()
     needs:
       - test-redistribute

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/.github/workflows/test.yml

@@ -6,6 +6,7 @@ on:
       - main
   pull_request:
   schedule:
+    # cron every week on monday
     - cron: "0 0 * * 1"
 
 permissions: {}
@@ -16,15 +17,19 @@ env:
 jobs:
   changes:
     runs-on: ubuntu-latest
+    # Required permissions
     permissions:
+      contents: read
       pull-requests: read
     timeout-minutes: 5
+    # Set job outputs to values from filter step
     outputs:
       src: ${{ steps.filter.outputs.src }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
+      # For pull requests it's not necessary to checkout the code but for the main branch it is
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
         id: filter
         with:
@@ -79,14 +84,16 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
+          # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
+          # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
           version: "0.11.18"
           enable-cache: true
-          cache-suffix: ${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.uv-resolution }}-fa${{ matrix.fastapi-version }}
+          cache-suffix: ${{ matrix.python-version }}-fa${{ matrix.fastapi-version }}
           cache-dependency-glob: |
             pyproject.toml
             uv.lock
 
-      - name: Install dependencies
+      - name: Install Dependencies
         run: uv sync
 
       - name: Override FastAPI version
@@ -97,17 +104,16 @@ jobs:
         run: mkdir coverage
 
       - name: Test
-        # GitHub Windows runners ship bash natively
         run: uv run --no-sync bash scripts/test-cov.sh
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-fa${{ matrix.fastapi-version }}
-          CONTEXT: ${{ runner.os }}-py${{ matrix.python-version }}-fa${{ matrix.fastapi-version }}
+          COVERAGE_FILE: coverage/.coverage.py${{ matrix.python-version }}-fa${{ matrix.fastapi-version }}
+          CONTEXT: py${{ matrix.python-version }}-fa${{ matrix.fastapi-version }}
 
       - name: Store coverage files
         if: matrix.coverage == 'coverage'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: coverage-${{ runner.os }}-${{ matrix.python-version }}-${{ matrix.fastapi-version }}
+          name: coverage-${{ matrix.python-version }}-${{ matrix.fastapi-version }}
           path: coverage
           include-hidden-files: true
 
@@ -119,6 +125,11 @@ jobs:
     permissions:
       contents: read
     steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
@@ -126,6 +137,8 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
+          # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
+          # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
           version: "0.11.18"
           enable-cache: true
           cache-dependency-glob: |
@@ -145,6 +158,7 @@ jobs:
       - run: ls -la coverage
       - run: uv run coverage combine coverage
       - run: uv run coverage html --title "Coverage for ${{ github.sha }}"
+      - run: uv run coverage xml
 
       - name: Store coverage HTML
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -153,18 +167,28 @@ jobs:
           path: htmlcov
           include-hidden-files: true
 
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: true
+
       - run: uv run coverage report --fail-under=100
 
   # https://github.com/marketplace/actions/alls-green#why
-  test-alls-green: # This job does nothing and is only used for the branch protection
+  test-alls-green:  # This job does nothing and is only used for the branch protection
     if: always()
     needs:
       - test
       - coverage-combine
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    permissions: {}
     steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
       - name: Decide whether the needed jobs succeeded or failed
         uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
         with:

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.2.3
+Version: 0.2.5
 Summary: Router-based API versioning for FastAPI, with per-version docs and a declarative route lifecycle.
 Project-URL: Homepage, https://github.com/mat81black/fastapi-router-versioning
 Project-URL: Repository, https://github.com/mat81black/fastapi-router-versioning
@@ -32,7 +32,8 @@ Description-Content-Type: text/markdown
 # FastAPI Router Versioning
 
 [![Build Status](https://github.com/mat81black/fastapi-router-versioning/workflows/Test/badge.svg)](https://github.com/mat81black/fastapi-router-versioning/actions)
-[![Package version](https://badge.fury.io/py/fastapi-router-versioning.svg)](https://pypi.org/project/fastapi-router-versioning/)
+[![codecov](https://codecov.io/github/mat81black/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY)](https://codecov.io/github/mat81black/fastapi-router-versioning)
+[![pypi package](https://img.shields.io/pypi/v/fastapi-router-versioning?color=%2334D058&label=pypi%20package)](https://pypi.org/project/fastapi-router-versioning/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/fastapi-router-versioning.svg?color=%2334D058)](https://pypi.org/project/fastapi-router-versioning/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
@@ -182,7 +183,9 @@ A route without `@api_version` isn't excluded, it falls back to `default_version
 | `validation_error_code` | `int` | `422` | Status code returned for request validation errors; also replaces the `422` entry everywhere it appears in the OpenAPI schema, root schema included |
 | `handle_validation_exceptions` | `bool` | `True` | Set `False` to only patch the schema and register your own `RequestValidationError` handler |
 
-`.versionize()` returns the list of versions it activated.
+`.versionize()` returns the list of versions it activated. It can only be called once per
+instance; a second call raises `RuntimeError`, since it mutates the live FastAPI app in a way
+that can't be undone.
 
 ---
 

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/README.md

@@ -1,7 +1,8 @@
 # FastAPI Router Versioning
 
 [![Build Status](https://github.com/mat81black/fastapi-router-versioning/workflows/Test/badge.svg)](https://github.com/mat81black/fastapi-router-versioning/actions)
-[![Package version](https://badge.fury.io/py/fastapi-router-versioning.svg)](https://pypi.org/project/fastapi-router-versioning/)
+[![codecov](https://codecov.io/github/mat81black/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY)](https://codecov.io/github/mat81black/fastapi-router-versioning)
+[![pypi package](https://img.shields.io/pypi/v/fastapi-router-versioning?color=%2334D058&label=pypi%20package)](https://pypi.org/project/fastapi-router-versioning/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/fastapi-router-versioning.svg?color=%2334D058)](https://pypi.org/project/fastapi-router-versioning/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
@@ -151,7 +152,9 @@ A route without `@api_version` isn't excluded, it falls back to `default_version
 | `validation_error_code` | `int` | `422` | Status code returned for request validation errors; also replaces the `422` entry everywhere it appears in the OpenAPI schema, root schema included |
 | `handle_validation_exceptions` | `bool` | `True` | Set `False` to only patch the schema and register your own `RequestValidationError` handler |
 
-`.versionize()` returns the list of versions it activated.
+`.versionize()` returns the list of versions it activated. It can only be called once per
+instance; a second call raises `RuntimeError`, since it mutates the live FastAPI app in a way
+that can't be undone.
 
 ---
 

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/RELEASE_NOTES.md

@@ -2,6 +2,18 @@
 
 ## Latest Changes
 
+## 0.2.5 (2026-07-10)
+
+### Fixes
+
+* 🐛 Fix misleading self-collision error in RouterVersioner prefix claiming. PR [#36](https://github.com/mat81black/fastapi-router-versioning/pull/36) by [@mat81black](https://github.com/mat81black).
+
+## 0.2.4 (2026-07-09)
+
+### Internal
+
+* 🔧 Integrate Codecov for coverage tracking and update README. PR [#34](https://github.com/mat81black/fastapi-router-versioning/pull/34) by [@mat81black](https://github.com/mat81black).
+
 ## 0.2.3 (2026-07-09)
 
 ### Docs

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/fastapi_router_versioning/__init__.py

@@ -1,5 +1,5 @@
 from .versioner import RouterVersioner, VersionFormat, VersionT, api_version
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 __all__ = ["RouterVersioner", "api_version", "VersionFormat", "VersionT"]

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/fastapi_router_versioning/versioner.py

@@ -1,4 +1,5 @@
 import inspect
+import itertools
 
 from collections import defaultdict
 from collections.abc import Callable, Iterator
@@ -33,6 +34,12 @@ _ATTR_API_VERSION = "_api_version"
 _ATTR_DEPRECATE_IN = "_deprecate_in_version"
 _ATTR_REMOVE_IN = "_remove_in_version"
 
+# Unique per-instance token for _claim_prefix, so it can tell apart a prefix collision
+# caused by this same RouterVersioner instance (e.g. a degenerate prefix_format) from one
+# caused by a different instance sharing the app. Not id(self): that can be reused after
+# garbage collection for the common `RouterVersioner(...).versionize()` one-liner pattern.
+_instance_counter = itertools.count()
+
 
 class VersionFormat(str, Enum):
     """
@@ -194,6 +201,8 @@ class RouterVersioner:
 
         self._validation_error_code = validation_error_code
         self._handle_validation_exceptions = handle_validation_exceptions
+        self._versionized = False
+        self._instance_token = next(_instance_counter)
 
         if self._validation_error_code != 422 and self._handle_validation_exceptions:
             self._register_validation_exception_handler()
@@ -345,6 +354,24 @@ class RouterVersioner:
         return None
 
     def versionize(self) -> list[VersionT]:
+        """
+        Reads the configured routers, groups their routes by version, and mounts one
+        versioned router per active version on the app.
+
+        May only be called once per instance: it mutates the live FastAPI app (including
+        routers, registering routes) in a way that cannot be undone, so a second call
+        would either duplicate routes or, if a version prefix was already claimed, raise.
+        Create a new RouterVersioner if you need to versionize again.
+
+        :return: The list of versions that were actually mounted.
+        """
+        if self._versionized:
+            raise RuntimeError(
+                "versionize() was already called on this RouterVersioner instance. "
+                "Create a new RouterVersioner if you need to versionize a router again."
+            )
+        self._versionized = True
+
         latest_version: VersionT | None = None
         latest_routes: dict[tuple[str, str], Any] = {}
         latest_webhooks: list[Any] = []
@@ -450,19 +477,27 @@ class RouterVersioner:
         return {version: list(routes.values()) for version, routes in self._resolve_lifecycle(all_webhooks).items()}
 
     def _claim_prefix(self, prefix: str) -> None:
-        claimed: set[str] | None = getattr(self._app.state, "_router_versioner_claimed_prefixes", None)
+        claimed: dict[str, int] | None = getattr(self._app.state, "_router_versioner_claimed_prefixes", None)
         if claimed is None:
-            claimed = set()
+            claimed = {}
             self._app.state._router_versioner_claimed_prefixes = claimed
 
-        if prefix in claimed:
+        owner = claimed.get(prefix)
+        if owner is not None:
+            if owner == self._instance_token:
+                raise RuntimeError(
+                    f"Prefix '{prefix}' was already claimed by this same RouterVersioner instance. "
+                    "This usually means prefix_format doesn't use {major}/{minor}/{version} and "
+                    "produces the same prefix for multiple versions, or latest_prefix collides "
+                    "with an already-active version prefix."
+                )
             raise RuntimeError(
                 f"Prefix '{prefix}' is already used by another RouterVersioner attached to this app. "
                 "Two RouterVersioner instances sharing the same app must use distinct "
                 "prefix_format/latest_prefix values, otherwise their docs/openapi routes silently "
                 "shadow each other."
             )
-        claimed.add(prefix)
+        claimed[prefix] = self._instance_token
 
     def _resolve_webhooks_for_version(
         self, version: VersionT, webhooks_by_version: dict[VersionT, list[Any]]

{fastapi_router_versioning-0.2.3 → fastapi_router_versioning-0.2.5}/tests/test_versioner.py

@@ -687,6 +687,29 @@ def test_default_version_mixed_with_explicitly_decorated_routes() -> None:
     assert client.get("/v3_0/explicit").status_code == 200
 
 
+def test_routers_as_list() -> None:
+    """routers accepts a list of APIRouter, not just a single one (multi-router support)."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router1.get("/a")
+    @api_version((1, 0))
+    def route_a() -> dict[str, str]:
+        return {"msg": "a"}
+
+    @router2.get("/b")
+    @api_version((1, 0))
+    def route_b() -> dict[str, str]:
+        return {"msg": "b"}
+
+    RouterVersioner(app=app, routers=[router1, router2], version_format=VersionFormat.SEMVER).versionize()
+
+    client = TestClient(app)
+    assert client.get("/v1_0/a").status_code == 200
+    assert client.get("/v1_0/b").status_code == 200
+
+
 def test_openapi_callbacks_are_propagated_to_versioned_routes() -> None:
     """OpenAPI callbacks defined on a route are propagated to every versioned copy of that route."""
     app = FastAPI()
@@ -815,6 +838,38 @@ def test_webhook_routers_none_falls_back_to_app_webhooks() -> None:
     assert "/global-event" in schema_v1.get("webhooks", {})
 
 
+def test_webhook_routers_as_list() -> None:
+    """webhook_routers accepts a list of APIRouter, not just a single one."""
+    app = FastAPI()
+    router = APIRouter()
+    webhook_router1 = APIRouter()
+    webhook_router2 = APIRouter()
+
+    @router.get("/items")
+    @api_version((1, 0))
+    def get_items() -> dict[str, str]: ...
+
+    @webhook_router1.post("/hook-a")
+    @api_version((1, 0))
+    def hook_a(body: dict[str, str]) -> None: ...
+
+    @webhook_router2.post("/hook-b")
+    @api_version((1, 0))
+    def hook_b(body: dict[str, str]) -> None: ...
+
+    RouterVersioner(
+        app=app,
+        routers=router,
+        webhook_routers=[webhook_router1, webhook_router2],
+        version_format=VersionFormat.SEMVER,
+    ).versionize()
+
+    client = TestClient(app)
+    schema = client.get("/v1_0/openapi.json").json()
+    assert "/hook-a" in schema.get("webhooks", {})
+    assert "/hook-b" in schema.get("webhooks", {})
+
+
 def test_webhook_routers_no_webhook_before_first_version() -> None:
     """When all webhook versions are higher than the current route version, returns no webhooks."""
     app = FastAPI()
@@ -1281,6 +1336,59 @@ def test_duplicate_version_prefix_across_versioners_raises() -> None:
         RouterVersioner(app=app, routers=router2, version_format=VersionFormat.SEMVER).versionize()
 
 
+def test_degenerate_prefix_format_self_collision_raises() -> None:
+    """A prefix_format without {major}/{minor}/{version} placeholders makes every version
+    resolve to the same prefix. This is a self-collision on a single instance, not a clash
+    with another RouterVersioner, so the error message must say so explicitly."""
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/items")
+    @api_version((1, 0))
+    def get_items_v1() -> dict[str, str]: ...
+
+    @router.get("/items")
+    @api_version((2, 0))
+    def get_items_v2() -> dict[str, str]: ...
+
+    with pytest.raises(RuntimeError, match="already claimed by this same RouterVersioner instance"):
+        RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER, prefix_format="/api").versionize()
+
+
+def test_latest_prefix_collides_with_own_version_prefix_raises() -> None:
+    """latest_prefix accidentally set to the same value as an actual version's own prefix is
+    a self-collision on a single instance, not a clash with another RouterVersioner."""
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/items")
+    @api_version((1, 0))
+    def get_items() -> dict[str, str]: ...
+
+    with pytest.raises(RuntimeError, match="already claimed by this same RouterVersioner instance"):
+        RouterVersioner(
+            app=app, routers=router, version_format=VersionFormat.SEMVER, latest_prefix="/v1_0"
+        ).versionize()
+
+
+def test_calling_versionize_twice_on_same_instance_raises() -> None:
+    """Calling .versionize() a second time on the same instance must raise a clear,
+    self-explanatory error instead of the misleading '...used by another RouterVersioner'
+    message that _claim_prefix would otherwise produce (it's the same instance, not another)."""
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/items")
+    @api_version((1, 0))
+    def get_items() -> dict[str, str]: ...
+
+    versioner = RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER)
+    versioner.versionize()
+
+    with pytest.raises(RuntimeError, match="versionize\\(\\) was already called on this RouterVersioner instance"):
+        versioner.versionize()
+
+
 def test_duplicate_latest_prefix_across_versioners_raises() -> None:
     """Two RouterVersioners sharing the same latest_prefix on the same app must fail fast."""
     app = FastAPI()