fastapi-router-versioning 0.2.4__tar.gz → 0.2.6__tar.gz

{fastapi_router_versioning-0.2.4 → fastapi_router_versioning-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.2.4
+Version: 0.2.6
 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,12 +32,12 @@ 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)
-[![codecov](https://codecov.io/github/mat81black/fastapi-validation-override/graph/badge.svg?token=SL4JPWAB0O)](https://codecov.io/github/mat81black/fastapi-validation-override)
-[![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)
 
-FastAPI doesn't ship a way to run multiple API versions side by side. Teams typically end up duplicating routers, hand-rolling prefixes, or branching on request paths, and every one of those gets harder to maintain as versions pile up. `RouterVersioner` takes a declarative approach instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs for you, without moving anything else in your app.
+Running multiple API versions side by side usually means duplicating routers, hand-rolling prefixes, or branching on request paths, and every one of those gets harder to maintain as versions pile up. `RouterVersioner` takes a declarative approach instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs for you, without moving anything else in your app.
 
 ---
 
@@ -183,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.4 → fastapi_router_versioning-0.2.6}/README.md

@@ -1,12 +1,12 @@
 # FastAPI Router Versioning
 
 [![Build Status](https://github.com/mat81black/fastapi-router-versioning/workflows/Test/badge.svg)](https://github.com/mat81black/fastapi-router-versioning/actions)
-[![codecov](https://codecov.io/github/mat81black/fastapi-validation-override/graph/badge.svg?token=SL4JPWAB0O)](https://codecov.io/github/mat81black/fastapi-validation-override)
-[![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)
 
-FastAPI doesn't ship a way to run multiple API versions side by side. Teams typically end up duplicating routers, hand-rolling prefixes, or branching on request paths, and every one of those gets harder to maintain as versions pile up. `RouterVersioner` takes a declarative approach instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs for you, without moving anything else in your app.
+Running multiple API versions side by side usually means duplicating routers, hand-rolling prefixes, or branching on request paths, and every one of those gets harder to maintain as versions pile up. `RouterVersioner` takes a declarative approach instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs for you, without moving anything else in your app.
 
 ---
 
@@ -152,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.4 → fastapi_router_versioning-0.2.6}/RELEASE_NOTES.md

@@ -2,6 +2,18 @@
 
 ## Latest Changes
 
+## 0.2.6 (2026-07-11)
+
+### Refactors
+
+* ♻️ Use fastapi-native imports instead of importing from starlette directly. PR [#38](https://github.com/mat81black/fastapi-router-versioning/pull/38) by [@mat81black](https://github.com/mat81black).
+
+## 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

{fastapi_router_versioning-0.2.4 → fastapi_router_versioning-0.2.6}/fastapi_router_versioning/__init__.py

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

{fastapi_router_versioning-0.2.4 → fastapi_router_versioning-0.2.6}/fastapi_router_versioning/versioner.py

@@ -1,4 +1,5 @@
 import inspect
+import itertools
 
 from collections import defaultdict
 from collections.abc import Callable, Iterator
@@ -8,7 +9,7 @@ from typing import Any, TypeAlias, TypeVar
 import fastapi.openapi.utils
 import fastapi.routing
 
-from fastapi import APIRouter, FastAPI
+from fastapi import APIRouter, FastAPI, Request
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
 from fastapi.openapi.docs import (
@@ -18,7 +19,6 @@ from fastapi.openapi.docs import (
 )
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.routing import APIRoute, APIWebSocketRoute
-from starlette.requests import Request
 
 # iter_route_contexts was introduced in FastAPI 0.137.2. On older versions the
 # attribute does not exist and getattr returns None, activating the fallback path.
@@ -33,6 +33,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 +200,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 +353,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 +476,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.4 → fastapi_router_versioning-0.2.6}/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()