fastapi-dynamic-route-registration 0.1.0__tar.gz

fastapi_dynamic_route_registration-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DIAZ Jérôme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_dynamic_route_registration-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: fastapi-dynamic-route-registration
+Version: 0.1.0
+Summary: A library to help dynamically register routes in FastAPI applications.
+Author-email: Jérôme DIAZ <jerome_diaz@me.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeromediaz/fastapi-dynamic-route-registration
+Project-URL: Bug Tracker, https://github.com/jeromediaz/fastapi-dynamic-route-registration/issues
+Keywords: fastapi,route,dynamic
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# FastAPI dynamic route registration
+
+[![PyPI - License](https://img.shields.io/pypi/l/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+
+A library to help dynamically register routes in FastAPI applications.
+
+It is the FastAPI successor to [flask-dynamic-route-registration](https://github.com/jeromediaz/flask-dynamic-route-registration): endpoint modules decorate their functions with `@register_route`, and the application mounts whole modules from a configuration map — with per-router prefixes and shared values injected as parameter defaults.
+
+```bash
+pip install fastapi-dynamic-route-registration
+```
+
+## How to Use
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_router
+
+app = FastAPI()
+
+register_router(app, "healthcheck", "", {})
+```
+
+Inside the `healthcheck/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/health")
+def health() -> dict:
+    return {"status": "OK"}
+```
+
+### Reusing a module with different parameters, conditional routes
+
+```python
+api_versions = [
+    {"router_kwargs": {"prefix": "/api/1"}, "params": {"version": 1}},
+    {"router_kwargs": {"prefix": "/api/2"}, "params": {"version": 2}},
+]
+
+register_router(app, "api", api_versions, {})
+```
+
+Inside the `api/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/status")
+def status(*, version: int = 1) -> dict:
+    return {"status": "OK", "version": version}
+
+
+@register_route("/foo", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_a() -> dict:
+    return {"hello": "world"}
+
+
+@register_route("/foo/{subject}", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_b(subject: str) -> dict:
+    return {"hello": subject}
+```
+
+This registers four routes:
+
+| URL                  | Return value                   | Function |
+|----------------------|--------------------------------|----------|
+| /api/1/status        | {"status": "OK", "version": 1} | status   |
+| /api/2/status        | {"status": "OK", "version": 2} | status   |
+| /api/2/foo           | {"hello": "world"}             | foo_a    |
+| /api/2/foo/{subject} | {"hello": subject}             | foo_b    |
+
+Values from `params` (and from the `route_kwargs` passed to `register_router`) become the **default value** of the parameter with the same name. FastAPI still sees that parameter: a plain `version: int = 1` stays a query parameter, whose default is now the injected value. Keys a function does not declare are dropped — unless it accepts `**kwargs`, in which case they are passed on every call while `**kwargs` itself stays hidden from FastAPI. One shared mapping (e.g. an application context object) can therefore be broadcast to every route.
+
+### Other route options
+
+`register_route` forwards extra keyword arguments to `APIRouter.add_api_route`:
+
+```python
+@register_route("/items", methods=["POST"], status_code=201, tags=["items"])
+def create_item(item: Item) -> Item:
+    return item
+```
+
+### Registering multiple modules at once
+
+`register_routers` (plural) registers several modules under a shared parent router:
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_routers
+
+app = FastAPI()
+
+register_routers(
+    app,
+    "myapp.api",
+    {
+        "healthcheck": "",
+        "users": {"router_kwargs": {"prefix": "/users"}},
+    },
+    route_kwargs={},
+    prefix="/v1",
+)
+```
+
+Each value accepts the same shapes as `register_router`: a prefix string, a dict with `router_kwargs` (passed to `APIRouter`) and `params`, or a list of those. A configuration map like this is easy to keep in a JSON file per application.
+
+### Differences from the Flask version
+
+- Path parameters use FastAPI syntax: `{param}`, not `<param>`.
+- `router_kwargs` replaces `blueprint_kwargs`; a Flask-style `url_prefix` key is still accepted and mapped to `prefix`.
+- One function registers one route.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/jeromediaz/fastapi-dynamic-route-registration/blob/main/LICENSE) file for details.

fastapi_dynamic_route_registration-0.1.0/README.md

@@ -0,0 +1,122 @@
+# FastAPI dynamic route registration
+
+[![PyPI - License](https://img.shields.io/pypi/l/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+
+A library to help dynamically register routes in FastAPI applications.
+
+It is the FastAPI successor to [flask-dynamic-route-registration](https://github.com/jeromediaz/flask-dynamic-route-registration): endpoint modules decorate their functions with `@register_route`, and the application mounts whole modules from a configuration map — with per-router prefixes and shared values injected as parameter defaults.
+
+```bash
+pip install fastapi-dynamic-route-registration
+```
+
+## How to Use
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_router
+
+app = FastAPI()
+
+register_router(app, "healthcheck", "", {})
+```
+
+Inside the `healthcheck/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/health")
+def health() -> dict:
+    return {"status": "OK"}
+```
+
+### Reusing a module with different parameters, conditional routes
+
+```python
+api_versions = [
+    {"router_kwargs": {"prefix": "/api/1"}, "params": {"version": 1}},
+    {"router_kwargs": {"prefix": "/api/2"}, "params": {"version": 2}},
+]
+
+register_router(app, "api", api_versions, {})
+```
+
+Inside the `api/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/status")
+def status(*, version: int = 1) -> dict:
+    return {"status": "OK", "version": version}
+
+
+@register_route("/foo", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_a() -> dict:
+    return {"hello": "world"}
+
+
+@register_route("/foo/{subject}", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_b(subject: str) -> dict:
+    return {"hello": subject}
+```
+
+This registers four routes:
+
+| URL                  | Return value                   | Function |
+|----------------------|--------------------------------|----------|
+| /api/1/status        | {"status": "OK", "version": 1} | status   |
+| /api/2/status        | {"status": "OK", "version": 2} | status   |
+| /api/2/foo           | {"hello": "world"}             | foo_a    |
+| /api/2/foo/{subject} | {"hello": subject}             | foo_b    |
+
+Values from `params` (and from the `route_kwargs` passed to `register_router`) become the **default value** of the parameter with the same name. FastAPI still sees that parameter: a plain `version: int = 1` stays a query parameter, whose default is now the injected value. Keys a function does not declare are dropped — unless it accepts `**kwargs`, in which case they are passed on every call while `**kwargs` itself stays hidden from FastAPI. One shared mapping (e.g. an application context object) can therefore be broadcast to every route.
+
+### Other route options
+
+`register_route` forwards extra keyword arguments to `APIRouter.add_api_route`:
+
+```python
+@register_route("/items", methods=["POST"], status_code=201, tags=["items"])
+def create_item(item: Item) -> Item:
+    return item
+```
+
+### Registering multiple modules at once
+
+`register_routers` (plural) registers several modules under a shared parent router:
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_routers
+
+app = FastAPI()
+
+register_routers(
+    app,
+    "myapp.api",
+    {
+        "healthcheck": "",
+        "users": {"router_kwargs": {"prefix": "/users"}},
+    },
+    route_kwargs={},
+    prefix="/v1",
+)
+```
+
+Each value accepts the same shapes as `register_router`: a prefix string, a dict with `router_kwargs` (passed to `APIRouter`) and `params`, or a list of those. A configuration map like this is easy to keep in a JSON file per application.
+
+### Differences from the Flask version
+
+- Path parameters use FastAPI syntax: `{param}`, not `<param>`.
+- `router_kwargs` replaces `blueprint_kwargs`; a Flask-style `url_prefix` key is still accepted and mapped to `prefix`.
+- One function registers one route.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/jeromediaz/fastapi-dynamic-route-registration/blob/main/LICENSE) file for details.

fastapi_dynamic_route_registration-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+"fastapi_dynamic_route_registration" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project]
+name = "fastapi-dynamic-route-registration"
+version = "0.1.0"
+authors = [
+  { name="Jérôme DIAZ", email="jerome_diaz@me.com" },
+]
+description = "A library to help dynamically register routes in FastAPI applications."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+keywords = ["fastapi", "route", "dynamic"]
+dependencies = [
+    "fastapi>=0.100.0",
+    "typing-extensions>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["black", "pytest", "ruff", "mypy", "httpx"]
+
+[project.urls]
+"Homepage" = "https://github.com/jeromediaz/fastapi-dynamic-route-registration"
+"Bug Tracker" = "https://github.com/jeromediaz/fastapi-dynamic-route-registration/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]

fastapi_dynamic_route_registration-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration/__init__.py

@@ -0,0 +1,14 @@
+"""
+FastAPI Dynamic Route Registration
+------------------------------------
+A library to help dynamically register routes in FastAPI applications.
+
+Drop-in spiritual successor to ``flask-dynamic-route-registration``.
+"""
+
+from .register_routers import register_router, register_routers
+from .router_decorator import register_route
+
+__version__ = "0.1.0"
+
+__all__ = ["register_route", "register_router", "register_routers"]

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration/register_routers.py

@@ -0,0 +1,109 @@
+from collections.abc import Mapping
+from inspect import getmembers
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+
+from .router_decorator import is_register_route
+
+
+def register_router(
+    container: FastAPI | APIRouter,
+    module_name: str,
+    routers_data: str | Any | list[str | Any],
+    route_kwargs: Mapping[str, Any],
+) -> list[APIRouter]:
+    """Register a single module's routes into *container*.
+
+    Args:
+        container: A ``FastAPI`` app or parent ``APIRouter`` to mount the new
+            router(s) into.
+        module_name: Dotted import path of the module that contains
+            ``@register_route``-decorated functions.
+        routers_data: Configuration data.
+
+            - ``str`` — treated as the URL prefix for a single router.
+            - ``dict`` — may have keys ``router_name``, ``router_kwargs``
+              (passed to ``APIRouter()``) and ``params`` (injected into every
+              route as default values, same semantics as the Flask version).
+            - ``list`` — list of the above; mounts the module multiple times
+              at different prefixes or with different params.
+
+        route_kwargs: Extra key/value pairs merged into every router's
+            ``params`` dict and bound as default parameter values in decorated
+            route functions.  Use this to inject shared dependencies such as
+            an application context object.
+
+    Returns:
+        List of the newly created ``APIRouter`` instances (empty list if the
+        module contains no ``@register_route``-decorated functions).
+    """
+    module_object = __import__(module_name, fromlist=[""])
+    functions = getmembers(module_object, is_register_route)
+
+    if not functions:
+        return []
+
+    if not isinstance(routers_data, list):
+        routers_data = [routers_data]
+
+    new_routers: list[APIRouter] = []
+
+    for router_data in routers_data:
+        if isinstance(router_data, str):
+            router_data = {"router_kwargs": {"prefix": router_data}}
+
+        router_kwargs: dict[str, Any] = router_data.get("router_kwargs", {})
+        params: dict[str, Any] = {**router_data.get("params", {}), **route_kwargs}
+
+        # Normalise Flask-style url_prefix key in router_kwargs
+        if "url_prefix" in router_kwargs and "prefix" not in router_kwargs:
+            router_kwargs["prefix"] = router_kwargs.pop("url_prefix")
+
+        new_router = APIRouter(**router_kwargs)
+
+        for _name, register_fn in functions:
+            register_fn(new_router, **params)
+
+        container.include_router(new_router)
+        new_routers.append(new_router)
+
+    return new_routers
+
+
+def register_routers(
+    container: FastAPI | APIRouter,
+    module_prefix: str,
+    routers: Mapping[str, Any],
+    route_kwargs: Mapping[str, Any],
+    **kwargs: Any,
+) -> APIRouter:
+    """Register multiple modules' routes into *container*.
+
+    Mirrors ``register_blueprints`` from the Flask version.  Each key in
+    *routers* is a module suffix (appended to *module_prefix* with a ``.``
+    separator) and its value is the *routers_data* accepted by
+    :func:`register_router`.
+
+    Args:
+        container: A ``FastAPI`` app or parent ``APIRouter``.
+        module_prefix: Common dotted prefix for all modules (e.g.
+            ``"myapp.api"``).
+        routers: Mapping of ``{module_suffix: routers_data}``.
+        route_kwargs: Extra key/value pairs merged into every route's params
+            and bound as default parameter values (e.g.
+            ``{"app_context": ctx}``).
+        **kwargs: Extra kwargs forwarded to the top-level ``APIRouter``
+            constructor (e.g. ``tags``, ``dependencies``).
+
+    Returns:
+        The top-level ``APIRouter`` that wraps all sub-routers.
+    """
+    parent_router = APIRouter(**kwargs)
+
+    for module_suffix, routers_data in routers.items():
+        module_name = f"{module_prefix}.{module_suffix}"
+        register_router(parent_router, module_name, routers_data, route_kwargs)
+
+    container.include_router(parent_router)
+    return parent_router

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration/router_decorator.py

@@ -0,0 +1,139 @@
+import functools
+import inspect
+import types
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class EndpointEnabledCallback(Protocol):
+    def __call__(self, **params: Any) -> bool: ...
+
+
+def _bind_params_as_defaults(
+    func: Callable[..., Any], params: dict[str, Any]
+) -> Callable[..., Any]:
+    """Return a new callable with *params* injected as parameter defaults.
+
+    FastAPI introspects ``__signature__`` to build request validation and
+    dependency injection.  We replace the signature so that any key in
+    *params* that matches a parameter name becomes its default value,
+    overriding any pre-existing default.  This mirrors the
+    ``defaults=params`` mechanism of Flask blueprints.
+
+    Only params whose keys appear in the function signature (or the function
+    accepts ``**kwargs``) are injected; unrecognized keys are silently dropped
+    so that one ``route_kwargs`` dict can be broadcast to all routes without
+    causing ``TypeError`` for routes that don't declare every key.
+
+    ``**kwargs`` (VAR_KEYWORD) parameters are stripped from the
+    FastAPI-visible signature because FastAPI cannot handle them and would
+    attempt to treat them as query parameters.
+    """
+    sig = inspect.signature(func)
+    accepts_var_keyword = any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+    )
+    # Params to actually inject: only those accepted by the function.
+    injectable = {
+        k: v for k, v in params.items() if k in sig.parameters or accepts_var_keyword
+    }
+
+    new_params = []
+    for name, param in sig.parameters.items():
+        # Drop **kwargs from the FastAPI-visible signature: FastAPI cannot
+        # handle VAR_KEYWORD parameters and would try to make them query params.
+        if param.kind is inspect.Parameter.VAR_KEYWORD:
+            continue
+        if name in injectable:
+            # Always override the existing default so that injected values
+            # from per-router params take precedence over function-level defaults.
+            new_params.append(param.replace(default=injectable[name]))
+        else:
+            new_params.append(param)
+
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_bound(*args: Any, **kwargs: Any) -> Any:
+            for k, v in injectable.items():
+                kwargs.setdefault(k, v)
+            return await func(*args, **kwargs)
+
+        async_bound.__signature__ = sig.replace(parameters=new_params)  # type: ignore[attr-defined]
+        return async_bound
+    else:
+
+        @functools.wraps(func)
+        def sync_bound(*args: Any, **kwargs: Any) -> Any:
+            for k, v in injectable.items():
+                kwargs.setdefault(k, v)
+            return func(*args, **kwargs)
+
+        sync_bound.__signature__ = sig.replace(parameters=new_params)  # type: ignore[attr-defined]
+        return sync_bound
+
+
+def register_route(
+    path: str,
+    *,
+    methods: list[str] | None = None,
+    endpoint: str | None = None,
+    enabled: bool | EndpointEnabledCallback = True,
+    **route_kwargs: Any,
+) -> Callable[..., Any]:
+    """Decorator that marks a function as a FastAPI route to be registered later.
+
+    Usage is intentionally identical to the Flask ``register_route`` decorator so
+    that endpoint modules can be ported with minimal diff.
+
+    Args:
+        path: The URL path relative to the router prefix (e.g. ``""`` or
+            ``"/{dag_id}"``).  Flask ``<param>`` syntax is **not** supported;
+            use FastAPI path syntax ``{param}`` directly.
+        methods: HTTP methods (default ``["GET"]``).
+        endpoint: Override the operation name; defaults to the function name.
+        enabled: ``True``, ``False``, or a callable ``(**params) -> bool`` that
+            receives the per-router *params* at registration time.
+        **route_kwargs: Extra kwargs forwarded to ``router.add_api_route()``.
+
+    Returns:
+        A ``Callable`` wrapper tagged with ``.is_url_rule = True``.  When
+        called as ``wrapper(router, **params)``, it registers the original
+        function on the given ``APIRouter`` with *params* bound as parameter
+        defaults via :func:`_bind_params_as_defaults`.
+    """
+    _methods = methods or ["GET"]
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        _endpoint = endpoint or func.__name__
+
+        def wrapper(router: Any, **params: Any) -> None:
+            if callable(enabled):
+                endpoint_enabled: bool = enabled(**params)
+            else:
+                endpoint_enabled = enabled
+
+            if not endpoint_enabled:
+                return
+
+            # Always run through _bind_params_as_defaults so that **kwargs
+            # is stripped from the FastAPI-visible signature even when params
+            # is empty.
+            bound_func = _bind_params_as_defaults(func, params)
+
+            router.add_api_route(
+                path,
+                bound_func,
+                methods=_methods,
+                name=_endpoint,
+                **route_kwargs,
+            )
+
+        wrapper.is_url_rule = True  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator
+
+
+def is_register_route(func: Any) -> bool:
+    return isinstance(func, types.FunctionType) and getattr(func, "is_url_rule", False)

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: fastapi-dynamic-route-registration
+Version: 0.1.0
+Summary: A library to help dynamically register routes in FastAPI applications.
+Author-email: Jérôme DIAZ <jerome_diaz@me.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeromediaz/fastapi-dynamic-route-registration
+Project-URL: Bug Tracker, https://github.com/jeromediaz/fastapi-dynamic-route-registration/issues
+Keywords: fastapi,route,dynamic
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# FastAPI dynamic route registration
+
+[![PyPI - License](https://img.shields.io/pypi/l/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-dynamic-route-registration)](https://pypi.org/project/fastapi-dynamic-route-registration/)
+
+A library to help dynamically register routes in FastAPI applications.
+
+It is the FastAPI successor to [flask-dynamic-route-registration](https://github.com/jeromediaz/flask-dynamic-route-registration): endpoint modules decorate their functions with `@register_route`, and the application mounts whole modules from a configuration map — with per-router prefixes and shared values injected as parameter defaults.
+
+```bash
+pip install fastapi-dynamic-route-registration
+```
+
+## How to Use
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_router
+
+app = FastAPI()
+
+register_router(app, "healthcheck", "", {})
+```
+
+Inside the `healthcheck/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/health")
+def health() -> dict:
+    return {"status": "OK"}
+```
+
+### Reusing a module with different parameters, conditional routes
+
+```python
+api_versions = [
+    {"router_kwargs": {"prefix": "/api/1"}, "params": {"version": 1}},
+    {"router_kwargs": {"prefix": "/api/2"}, "params": {"version": 2}},
+]
+
+register_router(app, "api", api_versions, {})
+```
+
+Inside the `api/__init__.py` file
+
+```python
+from fastapi_dynamic_route_registration import register_route
+
+
+@register_route("/status")
+def status(*, version: int = 1) -> dict:
+    return {"status": "OK", "version": version}
+
+
+@register_route("/foo", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_a() -> dict:
+    return {"hello": "world"}
+
+
+@register_route("/foo/{subject}", enabled=lambda **params: params.get("version", 1) >= 2)
+def foo_b(subject: str) -> dict:
+    return {"hello": subject}
+```
+
+This registers four routes:
+
+| URL                  | Return value                   | Function |
+|----------------------|--------------------------------|----------|
+| /api/1/status        | {"status": "OK", "version": 1} | status   |
+| /api/2/status        | {"status": "OK", "version": 2} | status   |
+| /api/2/foo           | {"hello": "world"}             | foo_a    |
+| /api/2/foo/{subject} | {"hello": subject}             | foo_b    |
+
+Values from `params` (and from the `route_kwargs` passed to `register_router`) become the **default value** of the parameter with the same name. FastAPI still sees that parameter: a plain `version: int = 1` stays a query parameter, whose default is now the injected value. Keys a function does not declare are dropped — unless it accepts `**kwargs`, in which case they are passed on every call while `**kwargs` itself stays hidden from FastAPI. One shared mapping (e.g. an application context object) can therefore be broadcast to every route.
+
+### Other route options
+
+`register_route` forwards extra keyword arguments to `APIRouter.add_api_route`:
+
+```python
+@register_route("/items", methods=["POST"], status_code=201, tags=["items"])
+def create_item(item: Item) -> Item:
+    return item
+```
+
+### Registering multiple modules at once
+
+`register_routers` (plural) registers several modules under a shared parent router:
+
+```python
+from fastapi import FastAPI
+from fastapi_dynamic_route_registration import register_routers
+
+app = FastAPI()
+
+register_routers(
+    app,
+    "myapp.api",
+    {
+        "healthcheck": "",
+        "users": {"router_kwargs": {"prefix": "/users"}},
+    },
+    route_kwargs={},
+    prefix="/v1",
+)
+```
+
+Each value accepts the same shapes as `register_router`: a prefix string, a dict with `router_kwargs` (passed to `APIRouter`) and `params`, or a list of those. A configuration map like this is easy to keep in a JSON file per application.
+
+### Differences from the Flask version
+
+- Path parameters use FastAPI syntax: `{param}`, not `<param>`.
+- `router_kwargs` replaces `blueprint_kwargs`; a Flask-style `url_prefix` key is still accepted and mapped to `prefix`.
+- One function registers one route.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/jeromediaz/fastapi-dynamic-route-registration/blob/main/LICENSE) file for details.

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/fastapi_dynamic_route_registration/__init__.py
+src/fastapi_dynamic_route_registration/py.typed
+src/fastapi_dynamic_route_registration/register_routers.py
+src/fastapi_dynamic_route_registration/router_decorator.py
+src/fastapi_dynamic_route_registration.egg-info/PKG-INFO
+src/fastapi_dynamic_route_registration.egg-info/SOURCES.txt
+src/fastapi_dynamic_route_registration.egg-info/dependency_links.txt
+src/fastapi_dynamic_route_registration.egg-info/requires.txt
+src/fastapi_dynamic_route_registration.egg-info/top_level.txt
+tests/test_integration.py
+tests/test_register_route.py

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastapi>=0.100.0
+typing-extensions>=4.0.0
+
+[dev]
+black
+pytest
+ruff
+mypy
+httpx

fastapi_dynamic_route_registration-0.1.0/src/fastapi_dynamic_route_registration.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_dynamic_route_registration

fastapi_dynamic_route_registration-0.1.0/tests/test_integration.py

@@ -0,0 +1,138 @@
+"""Integration tests for the full dynamic-route-registration pipeline.
+
+These tests simulate how a host application wires endpoint modules at
+startup, without requiring
+a full host application.  They verify that:
+
+* register_router correctly wires routes from a module into a FastAPI app
+* register_routers groups multiple modules under a parent router
+* Params from a JSON-style config map are injected as defaults
+* The url_prefix / prefix normalisation works for both key names
+* Multiple mounts of the same module at different prefixes work independently
+"""
+
+import pytest
+from fastapi import FastAPI, APIRouter
+from fastapi.testclient import TestClient
+
+from fastapi_dynamic_route_registration import register_route, register_router, register_routers
+
+
+# ---------------------------------------------------------------------------
+# Inline endpoint module (simulates an endpoint package __init__.py)
+# ---------------------------------------------------------------------------
+
+@register_route("", methods=["GET"])
+def health(*, version: int = 1, **kwargs) -> dict:
+    return {"status": "OK", "version": version}
+
+
+@register_route("/items/{item_id}", methods=["GET"])
+def get_item(item_id: str) -> dict:
+    return {"id": item_id}
+
+
+@register_route("/secret", methods=["GET"], enabled=False)
+def secret_route() -> dict:  # pragma: no cover
+    return {}
+
+
+@register_route("/flag", methods=["GET"], enabled=lambda **p: p.get("enable_flag", False))
+def flag_route() -> dict:
+    return {"flag": True}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_app(routers_data, route_kwargs=None) -> TestClient:
+    app = FastAPI()
+    register_router(app, __name__, routers_data, route_kwargs or {})
+    return TestClient(app)
+
+
+# ---------------------------------------------------------------------------
+# register_router tests
+# ---------------------------------------------------------------------------
+
+class TestRegisterRouter:
+    def test_basic_prefix_as_string(self):
+        client = _make_app("/v1")
+        assert client.get("/v1").json() == {"status": "OK", "version": 1}
+
+    def test_path_param(self):
+        client = _make_app("/v1")
+        assert client.get("/v1/items/abc").json() == {"id": "abc"}
+
+    def test_disabled_route_absent(self):
+        client = _make_app("/v1")
+        assert client.get("/v1/secret").status_code == 404
+
+    def test_param_overrides_default(self):
+        client = _make_app({"router_kwargs": {"prefix": "/v2"}, "params": {"version": 2}})
+        assert client.get("/v2").json() == {"status": "OK", "version": 2}
+
+    def test_conditional_enabled(self):
+        client = _make_app({"router_kwargs": {"prefix": "/v1"}, "params": {"enable_flag": True}})
+        assert client.get("/v1/flag").status_code == 200
+
+    def test_conditional_disabled(self):
+        client = _make_app({"router_kwargs": {"prefix": "/v1"}, "params": {"enable_flag": False}})
+        assert client.get("/v1/flag").status_code == 404
+
+    def test_url_prefix_key_accepted(self):
+        """Flask-style 'url_prefix' inside router_kwargs is normalised to 'prefix'."""
+        client = _make_app({"router_kwargs": {"url_prefix": "/compat"}})
+        assert client.get("/compat").status_code == 200
+
+    def test_multiple_mounts_independent_params(self):
+        """Same module at /v1 (version=1) and /v2 (version=2) must be independent."""
+        app = FastAPI()
+        register_router(
+            app,
+            __name__,
+            [
+                {"router_kwargs": {"prefix": "/v1"}, "params": {"version": 1}},
+                {"router_kwargs": {"prefix": "/v2"}, "params": {"version": 2}},
+            ],
+            {},
+        )
+        client = TestClient(app)
+        assert client.get("/v1").json()["version"] == 1
+        assert client.get("/v2").json()["version"] == 2
+
+
+# ---------------------------------------------------------------------------
+# register_routers tests
+# ---------------------------------------------------------------------------
+
+class TestRegisterRouters:
+    def test_groups_modules_under_parent_router(self):
+        current = __name__
+        parts = current.rsplit(".", 1)
+        if len(parts) < 2:
+            pytest.skip("Module is at top level; register_routers needs a prefix")
+
+        prefix, suffix = parts
+        app = FastAPI()
+        register_routers(app, module_prefix=prefix, routers={suffix: "/grp"}, route_kwargs={})
+        client = TestClient(app)
+        assert client.get("/grp").status_code == 200
+
+    def test_route_kwargs_injected_into_all_routes(self):
+        current = __name__
+        parts = current.rsplit(".", 1)
+        if len(parts) < 2:
+            pytest.skip("Module is at top level")
+
+        prefix, suffix = parts
+        app = FastAPI()
+        register_routers(
+            app,
+            module_prefix=prefix,
+            routers={suffix: {"router_kwargs": {"prefix": "/grp2"}}},
+            route_kwargs={"version": 99},
+        )
+        client = TestClient(app)
+        assert client.get("/grp2").json()["version"] == 99

fastapi_dynamic_route_registration-0.1.0/tests/test_register_route.py

@@ -0,0 +1,221 @@
+"""Tests for register_route decorator and register_router / register_routers."""
+
+import pytest
+from fastapi import APIRouter, FastAPI
+from fastapi.testclient import TestClient
+
+from fastapi_dynamic_route_registration import register_route, register_router, register_routers
+from fastapi_dynamic_route_registration.router_decorator import is_register_route
+
+
+# ---------------------------------------------------------------------------
+# Helpers / fixture modules defined inline
+# ---------------------------------------------------------------------------
+
+@register_route("", methods=["GET"])
+def index_route():
+    return {"status": "OK"}
+
+
+# Deliberately placed AFTER more specific routes so FastAPI matches correctly.
+@register_route("/items/{item_id}", methods=["GET"])
+def item_route(item_id: str):
+    return {"item": item_id}
+
+
+@register_route("/versioned", methods=["GET"])
+def versioned_route(*, version: int = 1, **kwargs):
+    return {"version": version}
+
+
+@register_route("/disabled", methods=["GET"], enabled=False)
+def disabled_route():  # pragma: no cover
+    return {}
+
+
+@register_route("/conditional", methods=["GET"], enabled=lambda **p: p.get("flag", False))
+def conditional_route():
+    return {"ok": True}
+
+
+@register_route("/async-versioned", methods=["GET"])
+async def async_versioned_route(*, version: int = 1, **kwargs):
+    return {"version": version}
+
+
+@register_route("/star-kwargs", methods=["GET"])
+def route_with_star_kwargs(item_id: str = "default", **kwargs):
+    """**kwargs must be stripped from the FastAPI-visible signature."""
+    return {"item": item_id}
+
+
+# ---------------------------------------------------------------------------
+# Tests: decorator
+# ---------------------------------------------------------------------------
+
+class TestRegisterRouteDecorator:
+    def test_marks_is_url_rule(self):
+        assert index_route.is_url_rule is True
+
+    def test_is_register_route_predicate_true(self):
+        assert is_register_route(index_route)
+
+    def test_is_register_route_predicate_false_for_plain_func(self):
+        def plain(): ...
+        assert not is_register_route(plain)
+
+
+# ---------------------------------------------------------------------------
+# Tests: register_router with a real FastAPI app
+# ---------------------------------------------------------------------------
+
+class TestRegisterRouterDirect:
+    """register_router using functions defined in this test module."""
+
+    def _app_with_routes(self, routes_data, route_kwargs=None):
+        app = FastAPI()
+        # Pass the current module so register_router imports *this* file
+        register_router(
+            app,
+            __name__,
+            routes_data,
+            route_kwargs or {},
+        )
+        return TestClient(app)
+
+    def test_index_route(self):
+        client = self._app_with_routes("/api")
+        r = client.get("/api")
+        assert r.status_code == 200
+        assert r.json() == {"status": "OK"}
+
+    def test_path_param_route(self):
+        client = self._app_with_routes("/api")
+        r = client.get("/api/items/hello")
+        assert r.status_code == 200
+        assert r.json() == {"item": "hello"}
+
+    def test_params_injected_as_defaults(self):
+        client = self._app_with_routes(
+            {"router_kwargs": {"prefix": "/api"}, "params": {"version": 42}}
+        )
+        r = client.get("/api/versioned")
+        assert r.status_code == 200
+        assert r.json() == {"version": 42}
+
+    def test_default_version_without_params(self):
+        client = self._app_with_routes("/api")
+        r = client.get("/api/versioned")
+        assert r.status_code == 200
+        assert r.json() == {"version": 1}
+
+    def test_disabled_route_not_registered(self):
+        client = self._app_with_routes("/api")
+        r = client.get("/api/disabled")
+        assert r.status_code == 404
+
+    def test_conditional_route_enabled(self):
+        client = self._app_with_routes(
+            {"router_kwargs": {"prefix": "/api"}, "params": {"flag": True}}
+        )
+        r = client.get("/api/conditional")
+        assert r.status_code == 200
+
+    def test_conditional_route_disabled(self):
+        client = self._app_with_routes(
+            {"router_kwargs": {"prefix": "/api"}, "params": {"flag": False}}
+        )
+        r = client.get("/api/conditional")
+        assert r.status_code == 404
+
+    def test_multiple_prefixes(self):
+        """Same module mounted at two different prefixes (like api.json list form)."""
+        app = FastAPI()
+        register_router(
+            app,
+            __name__,
+            [
+                {"router_kwargs": {"prefix": "/v1"}, "params": {"version": 1}},
+                {"router_kwargs": {"prefix": "/v2"}, "params": {"version": 2}},
+            ],
+            {},
+        )
+        client = TestClient(app)
+        assert client.get("/v1/versioned").json() == {"version": 1}
+        assert client.get("/v2/versioned").json() == {"version": 2}
+
+    def test_url_prefix_key_normalised(self):
+        """Flask-style 'url_prefix' inside router_kwargs is accepted."""
+        app = FastAPI()
+        register_router(
+            app,
+            __name__,
+            {"router_kwargs": {"url_prefix": "/compat"}},
+            {},
+        )
+        client = TestClient(app)
+        r = client.get("/compat")
+        assert r.status_code == 200
+
+    def test_register_routers(self):
+        """register_routers groups multiple modules under one parent router."""
+        app = FastAPI()
+        # Use __name__ (this module) directly: register_routers builds
+        # "module_prefix.module_suffix" so we split the current module name.
+        current = __name__  # e.g. "test_register_route"
+        parts = current.rsplit(".", 1)
+        if len(parts) == 2:
+            prefix, suffix = parts
+        else:
+            # Module is at top level; use a dummy parent router via register_router
+            register_router(app, current, "/items_direct", {})
+            client = TestClient(app)
+            r = client.get("/items_direct")
+            assert r.status_code == 200
+            return
+
+        register_routers(
+            app,
+            module_prefix=prefix,
+            routers={suffix: "/items"},
+            route_kwargs={},
+        )
+        client = TestClient(app)
+        r = client.get("/items")
+        assert r.status_code == 200
+
+    def test_async_route_registered_and_callable(self):
+        """Async route functions must be registered and return correct responses."""
+        client = self._app_with_routes("/api")
+        r = client.get("/api/async-versioned")
+        assert r.status_code == 200
+        assert r.json() == {"version": 1}
+
+    def test_async_route_param_injected(self):
+        """Injected params must override async route function defaults."""
+        client = self._app_with_routes(
+            {"router_kwargs": {"prefix": "/api"}, "params": {"version": 99}}
+        )
+        r = client.get("/api/async-versioned")
+        assert r.status_code == 200
+        assert r.json() == {"version": 99}
+
+    def test_var_keyword_stripped_from_signature(self):
+        """**kwargs must be stripped so FastAPI does not treat them as query params."""
+        client = self._app_with_routes("/api")
+        # Should succeed without FastAPI complaining about unknown parameters
+        r = client.get("/api/star-kwargs")
+        assert r.status_code == 200
+        assert r.json() == {"item": "default"}
+
+    def test_empty_module_returns_empty_list(self):
+        """register_router must return [] when module has no @register_route functions."""
+        import types as _types
+        empty = _types.ModuleType("_empty_test_module")
+        import sys
+        sys.modules["_empty_test_module"] = empty
+        try:
+            result = register_router(FastAPI(), "_empty_test_module", "/prefix", {})
+            assert result == []
+        finally:
+            del sys.modules["_empty_test_module"]