Merge pull request #218 from python-ellar/openapi_mount_support

feat: Nested ModuleRouter support

Author: eadwinCode

ellar/common/constants.py

@@ -33,6 +33,7 @@
 
 TEMPLATE_GLOBAL_KEY = "TEMPLATE_GLOBAL_FILTERS"
 TEMPLATE_FILTER_KEY = "TEMPLATE_FILTERS"
+NESTED_ROUTERS_KEY = "NESTED_ROUTERS_KEY"
 
 MIDDLEWARE_HANDLERS_KEY = "MIDDLEWARE"
 

ellar/common/models/controller.py

@@ -1,6 +1,18 @@
+import dataclasses
 import typing as t
 
-from ..interfaces import IExecutionContext
+from ellar.common.constants import NESTED_ROUTERS_KEY
+from ellar.common.interfaces import IExecutionContext
+from ellar.reflect import reflect
+
+if t.TYPE_CHECKING:
+    from ellar.common.operations import ModuleRouter
+
+
+@dataclasses.dataclass
+class NestedRouterInfo:
+    router: t.Union["ModuleRouter", "ControllerBase"]
+    prefix: t.Optional[str] = None
 
 
 class ControllerType(type):
@@ -16,6 +28,18 @@ def full_view_name(cls, name: str) -> str:
         """ """
         return f"{cls.controller_class_name()}/{name}"
 
+    def add_router(
+        cls,
+        router: t.Union["ControllerBase", "ModuleRouter"],
+        prefix: t.Optional[str] = None,
+    ) -> None:
+        if prefix:
+            assert prefix.startswith("/"), "'prefix' must start with '/'"
+
+        reflect.define_metadata(
+            NESTED_ROUTERS_KEY, [NestedRouterInfo(prefix=prefix, router=router)], cls
+        )
+
 
 class ControllerBase(metaclass=ControllerType):
     # `context` variable will change based on the route function called on the APIController

ellar/common/operations/router.py

@@ -1,14 +1,23 @@
 import typing as t
 
-from ellar.common.constants import CONTROLLER_CLASS_KEY, GUARDS_KEY, VERSIONING_KEY
+from ellar.common.constants import (
+    CONTROLLER_CLASS_KEY,
+    GUARDS_KEY,
+    NESTED_ROUTERS_KEY,
+    VERSIONING_KEY,
+)
 from ellar.common.models import GuardCanActivate
+from ellar.common.models.controller import NestedRouterInfo
 from ellar.reflect import reflect
 from ellar.utils import get_unique_type
 from starlette.middleware import Middleware
 
 from .base import OperationDefinitions
 from .schema import RouteParameters, WsRouteParameters
 
+if t.TYPE_CHECKING:  # pragma: no cover
+    from ellar.common import ControllerBase
+
 
 class ModuleRouter(OperationDefinitions):
     def __init__(
@@ -40,6 +49,19 @@ def __init__(
     def control_type(self) -> t.Type[t.Any]:
         return self._control_type
 
+    def add_router(
+        self,
+        router: t.Union["ModuleRouter", "ControllerBase"],
+        prefix: t.Optional[str] = None,
+    ) -> None:
+        if prefix:
+            assert prefix.startswith("/"), "'prefix' must start with '/'"
+        reflect.define_metadata(
+            NESTED_ROUTERS_KEY,
+            [NestedRouterInfo(prefix=prefix, router=router)],
+            self.control_type,
+        )
+
     def get_mount_init(self) -> t.Dict[str, t.Any]:
         return self._kwargs.copy()
 

ellar/core/router_builders/base.py

@@ -2,11 +2,9 @@
 from abc import abstractmethod
 
 from ellar.common.logging import logger
+from ellar.core.routing.mount import EllarMount
 from starlette.routing import Host, Mount
 
-if t.TYPE_CHECKING:  # pragma: no cover
-    from ellar.core.routing.mount import EllarMount
-
 _router_builder_factory: t.Dict[t.Type, t.Type["RouterBuilder"]] = {}
 
 
@@ -66,3 +64,4 @@ def build(
 
 
 _register_controller_builder(Host, _DefaultRouterBuilder)
+_register_controller_builder(EllarMount, _DefaultRouterBuilder)

ellar/core/router_builders/controller.py

@@ -1,16 +1,15 @@
-import inspect
 import typing as t
 
 from ellar.common.constants import (
     CONTROLLER_METADATA,
     CONTROLLER_OPERATION_HANDLER_KEY,
     CONTROLLER_WATERMARK,
-    OPERATION_ENDPOINT_KEY,
     ROUTE_OPERATION_PARAMETERS,
 )
 from ellar.common.logging import logger
-from ellar.common.models import ControllerBase, ControllerType
+from ellar.common.models.controller import ControllerBase, ControllerType
 from ellar.common.operations import RouteParameters, WsRouteParameters
+from ellar.common.shortcuts import normalize_path
 from ellar.core.routing import (
     ControllerRouteOperation,
     ControllerWebsocketRouteOperation,
@@ -20,72 +19,56 @@
 from starlette.routing import BaseRoute
 
 from .base import RouterBuilder
+from .utils import get_route_functions, process_nested_routes
 
 T_ = t.TypeVar("T_")
 
 
-class ControllerRouterBuilder(RouterBuilder, controller_type=type(ControllerBase)):
-    @classmethod
-    def _get_route_functions(
-        cls,
-        klass: t.Type,
-    ) -> t.Iterable[t.Callable]:
-        for _method_name, method in inspect.getmembers(
-            klass, predicate=inspect.isfunction
-        ):
-            if hasattr(method, OPERATION_ENDPOINT_KEY):
-                yield method
+def process_controller_routes(controller: t.Type[ControllerBase]) -> t.List[BaseRoute]:
+    res: t.List[BaseRoute] = []
 
-    @classmethod
-    def _process_controller_routes(
-        cls, controller: t.Type[ControllerBase]
-    ) -> t.Sequence[BaseRoute]:
-        res = []
-
-        if reflect.get_metadata(CONTROLLER_METADATA.PROCESSED, controller):
-            return (
-                reflect.get_metadata(CONTROLLER_OPERATION_HANDLER_KEY, controller) or []
-            )
+    if reflect.get_metadata(CONTROLLER_METADATA.PROCESSED, controller):
+        return reflect.get_metadata(CONTROLLER_OPERATION_HANDLER_KEY, controller) or []
 
-        for item in cls._get_route_functions(controller):
-            parameters = item.__dict__[ROUTE_OPERATION_PARAMETERS]
-            operation: t.Union[
-                ControllerRouteOperation, ControllerWebsocketRouteOperation
-            ]
-
-            if not isinstance(parameters, list):
-                parameters = [parameters]
-
-            for parameter in parameters:
-                if isinstance(parameter, RouteParameters):
-                    operation = ControllerRouteOperation(controller, **parameter.dict())
-                elif isinstance(parameter, WsRouteParameters):
-                    operation = ControllerWebsocketRouteOperation(
-                        controller, **parameter.dict()
-                    )
-                else:  # pragma: no cover
-                    logger.warning(
-                        f"Parameter type is not recognized. {type(parameter) if not isinstance(parameter, type) else parameter}"
-                    )
-                    continue
-
-                reflect.define_metadata(
-                    CONTROLLER_OPERATION_HANDLER_KEY,
-                    [operation],
-                    controller,
+    for _, item in get_route_functions(controller):
+        parameters = item.__dict__[ROUTE_OPERATION_PARAMETERS]
+        operation: t.Union[ControllerRouteOperation, ControllerWebsocketRouteOperation]
+
+        if not isinstance(parameters, list):
+            parameters = [parameters]
+
+        for parameter in parameters:
+            if isinstance(parameter, RouteParameters):
+                operation = ControllerRouteOperation(controller, **parameter.dict())
+            elif isinstance(parameter, WsRouteParameters):
+                operation = ControllerWebsocketRouteOperation(
+                    controller, **parameter.dict()
                 )
-                res.append(operation)
-        reflect.define_metadata(CONTROLLER_METADATA.PROCESSED, True, controller)
-        return res
+            else:  # pragma: no cover
+                logger.warning(
+                    f"Parameter type is not recognized. {type(parameter) if not isinstance(parameter, type) else parameter}"
+                )
+                continue
 
+            reflect.define_metadata(
+                CONTROLLER_OPERATION_HANDLER_KEY,
+                [operation],
+                controller,
+            )
+            res.append(operation)
+    return res
+
+
+class ControllerRouterBuilder(RouterBuilder, controller_type=type(ControllerBase)):
     @classmethod
     def build(
         cls,
         controller_type: t.Union[t.Type[ControllerBase], t.Any],
         base_route_type: t.Type[t.Union[EllarMount, T_]] = EllarMount,
         **kwargs: t.Any,
     ) -> t.Union[T_, EllarMount]:
-        routes = cls._process_controller_routes(controller_type)
+        routes = process_controller_routes(controller_type)
+        routes.extend(process_nested_routes(controller_type))
 
         include_in_schema = reflect.get_metadata_or_raise_exception(
             CONTROLLER_METADATA.INCLUDE_IN_SCHEMA, controller_type
@@ -96,11 +79,18 @@ def build(
         )
 
         kwargs.setdefault("middleware", middleware)
+
+        path = reflect.get_metadata_or_raise_exception(
+            CONTROLLER_METADATA.PATH, controller_type
+        )
+
+        if "prefix" in kwargs:
+            prefix = kwargs.pop("prefix")
+            path = normalize_path(f"{prefix}/{path}")
+
         router = base_route_type(  # type:ignore[call-arg]
             routes=routes,
-            path=reflect.get_metadata_or_raise_exception(
-                CONTROLLER_METADATA.PATH, controller_type
-            ),
+            path=path,
             name=reflect.get_metadata_or_raise_exception(
                 CONTROLLER_METADATA.NAME, controller_type
             ),
@@ -110,6 +100,7 @@ def build(
             control_type=controller_type,
             **kwargs,
         )
+        reflect.define_metadata(CONTROLLER_METADATA.PROCESSED, True, controller_type)
         return router
 
     @classmethod

ellar/core/router_builders/module_router.py

@@ -1,12 +1,14 @@
 import typing as t
 
 from ellar.common import ModuleRouter
-from ellar.common.constants import CONTROLLER_OPERATION_HANDLER_KEY
+from ellar.common.compatible import AttributeDict
+from ellar.common.constants import CONTROLLER_METADATA, CONTROLLER_OPERATION_HANDLER_KEY
+from ellar.common.shortcuts import normalize_path
 from ellar.core.routing import EllarMount
-from ellar.core.routing.utils import build_route_parameters
 from ellar.reflect import reflect
 
 from .base import RouterBuilder
+from .utils import build_route_parameters, process_nested_routes
 
 T_ = t.TypeVar("T_")
 
@@ -19,17 +21,31 @@ def build(
         base_route_type: t.Type[t.Union[EllarMount, T_]] = EllarMount,
         **kwargs: t.Any,
     ) -> t.Union[T_, EllarMount]:
-        if controller_type.get_pre_build_routes():
-            routes = build_route_parameters(
-                controller_type.get_pre_build_routes(), controller_type.control_type
-            )
-        else:
+        if reflect.get_metadata(
+            CONTROLLER_METADATA.PROCESSED, controller_type.control_type
+        ):
             routes = reflect.get_metadata(
                 CONTROLLER_OPERATION_HANDLER_KEY, controller_type.control_type
             )
+        else:
+            routes = build_route_parameters(
+                controller_type.get_pre_build_routes(), controller_type.control_type
+            )
+            routes.extend(process_nested_routes(controller_type.control_type))
+
+        init_kwargs = AttributeDict(controller_type.get_mount_init())
+
+        if "prefix" in kwargs:
+            prefix = kwargs.pop("prefix")
+            init_kwargs.path = normalize_path(f"{prefix}/{init_kwargs.path}")
 
         controller_type.clear_pre_build_routes()
-        return base_route_type(**controller_type.get_mount_init(), routes=routes)  # type:ignore[call-arg]
+        router = base_route_type(**init_kwargs, routes=routes)  # type:ignore[call-arg]
+
+        reflect.define_metadata(
+            CONTROLLER_METADATA.PROCESSED, True, controller_type.control_type
+        )
+        return router
 
     @classmethod
     def check_type(cls, controller_type: t.Union[t.Type, t.Any]) -> None: