fastapi-dynamic-route-registration 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+fastapi_dynamic_route_registration/__init__.py,sha256=yQnd639AlyfLywnsCg2N4zO0NZCdvT3CcO_TnVB8JLs,423
+fastapi_dynamic_route_registration/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_dynamic_route_registration/register_routers.py,sha256=p9Nb1KtZ1wlwks0p-44A1aqBQzduBr1XdmDOdYcvpBg,4055
+fastapi_dynamic_route_registration/router_decorator.py,sha256=mPRpQDLDGftH_DUvHCrZpc0LCWqv5KALaSH0QSzohwA,5340
+fastapi_dynamic_route_registration-0.1.0.dist-info/licenses/LICENSE,sha256=5LFZRGEYJM0yj60bF-rPdi3ANN0-Vb_SOx6PgXS_KLs,1069
+fastapi_dynamic_route_registration-0.1.0.dist-info/METADATA,sha256=_XN1-7efg3kuHP2WuhgjT8ckZrR67IUWqEurnZ55UcU,5419
+fastapi_dynamic_route_registration-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fastapi_dynamic_route_registration-0.1.0.dist-info/top_level.txt,sha256=SqDVD53KRr-11bHU-4JdweXVzr8XpZigin5Soa0Qct0,35
+fastapi_dynamic_route_registration-0.1.0.dist-info/RECORD,,

fastapi_dynamic_route_registration-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastapi_dynamic_route_registration-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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