Merge pull request #311 from anentropic/issue-310

implement urls namespace for APIController

Author: eadwinCode

docs/api_controller/index.md

@@ -43,6 +43,8 @@ The fourth argument, `permissions`, is a list of all permissions that should be
 
 The fifth argument, `auto_import`, defaults to true, which automatically adds your controller to auto import list.
 
+The fifth argument, `urls_namespace`, defaults to `None`, or if set will nest the routes of this controller under their own namespace.
+
 for example:
 
 ```python

ninja_extra/controllers/base.py

@@ -27,7 +27,7 @@
 
 from django.db.models import Model, QuerySet
 from django.http import HttpResponse
-from django.urls import URLPattern
+from django.urls import URLPattern, URLResolver, include
 from django.urls import path as django_path
 from injector import inject, is_decorated_with_inject
 from ninja import NinjaAPI, Router
@@ -403,8 +403,11 @@ def __init__(
         tags: Union[Optional[List[str]], str] = None,
         permissions: Optional[List[BasePermissionType]] = None,
         auto_import: bool = True,
+        urls_namespace: Optional[str] = None,
     ) -> None:
         self.prefix = prefix
+        # Optional controller-level URL namespace. Applied to all route paths.
+        self.urls_namespace = urls_namespace or None
         # `auth` primarily defines APIController route function global authentication method.
         self.auth: Optional[AuthBase] = auth
 
@@ -553,16 +556,34 @@ def add_controller_route_function(self, route_function: RouteFunction) -> None:
             get_function_name(route_function.route.view_func)
         ] = route_function
 
-    def urls_paths(self, prefix: str) -> Iterator[URLPattern]:
+    def urls_paths(self, prefix: str) -> Iterator[Union[URLPattern, URLResolver]]:
+        namespaced_patterns: List[URLPattern] = []
+
         for path, path_view in self.path_operations.items():
             path = path.replace("{", "<").replace("}", ">")
             route = "/".join([i for i in (prefix, path) if i])
             # to skip lot of checks we simply treat double slash as a mistake:
             route = normalize_path(route)
             route = route.lstrip("/")
+
             for op in path_view.operations:
                 op = cast(Operation, op)
-                yield django_path(route, path_view.get_view(), name=op.url_name)
+                view = path_view.get_view()
+                if op.url_name:
+                    pattern = django_path(route, view, name=op.url_name)
+                else:
+                    pattern = django_path(route, view)
+
+                if self.urls_namespace:
+                    namespaced_patterns.append(pattern)
+                else:
+                    yield pattern
+
+        if self.urls_namespace and namespaced_patterns:
+            yield django_path(
+                "",
+                include((namespaced_patterns, self.urls_namespace), namespace=self.urls_namespace),
+            )
 
     def __repr__(self) -> str:  # pragma: no cover
         return f"<controller - {self.controller_class.__name__}>"
@@ -590,6 +611,8 @@ def _add_operation_from_route_function(self, route_function: RouteFunction) -> N
                 f"endpoint={get_function_name(route_function.route.view_func)}"
             )
         data = route_function.route.route_params.dict()
+        if not data.get("url_name"):
+            data["url_name"] = get_function_name(route_function.route.view_func)
         route_function.operation = self.add_api_operation(
             view_func=route_function.as_view, **data
         )
@@ -663,19 +686,21 @@ def api_controller(
     tags: Union[Optional[List[str]], str] = None,
     permissions: Optional[List[BasePermissionType]] = None,
     auto_import: bool = True,
+    urls_namespace: Optional[str] = None,
 ) -> Callable[
     [Union[Type, Type[T]]], Union[Type[ControllerBase], Type[T]]
 ]:  # pragma: no cover
     ...
 
 
 def api_controller(
-    prefix_or_class: Union[str, Union[ControllerClassType, Type]] = "",
+    prefix_or_class: Union[str, ControllerClassType] = "",
     auth: Any = NOT_SET,
     throttle: Union[BaseThrottle, List[BaseThrottle], NOT_SET_TYPE] = NOT_SET,
     tags: Union[Optional[List[str]], str] = None,
     permissions: Optional[List[BasePermissionType]] = None,
     auto_import: bool = True,
+    urls_namespace: Optional[str] = None,
 ) -> Union[ControllerClassType, Callable[[ControllerClassType], ControllerClassType]]:
     if isinstance(prefix_or_class, type):
         return APIController(
@@ -685,6 +710,7 @@ def api_controller(
             permissions=permissions,
             auto_import=auto_import,
             throttle=throttle,
+            urls_namespace=urls_namespace,
         )(prefix_or_class)
 
     def _decorator(cls: ControllerClassType) -> ControllerClassType:
@@ -695,6 +721,7 @@ def _decorator(cls: ControllerClassType) -> ControllerClassType:
             permissions=permissions,
             auto_import=auto_import,
             throttle=throttle,
+            urls_namespace=urls_namespace,
         )(cls)
 
     return _decorator

tests/controllers.py

@@ -55,3 +55,14 @@ def get_event(self, event_id: int = Path(..., alias="id")) -> EventSchema:
     def get_event_from_orm(self, id: int) -> EventSchema:
         event = get_object_or_404(Event, id=id)
         return EventSchema.from_orm(event)
+
+
+@api_controller("inventory-items", urls_namespace="inventory")
+class NamespacedController:
+    @http_get("", url_name="inventory-item-list")
+    def list_items(self):
+        return [{"id": 1, "name": "sample"}]
+
+    @http_get("/{int:item_id}", url_name="inventory-item-detail")
+    def get_item(self, item_id: int):
+        return {"id": item_id, "name": f"sample-{item_id}"}

tests/test_controller.py

@@ -3,6 +3,7 @@
 import django
 import pytest
 from django.contrib.auth.models import Group
+from django.urls import reverse
 
 from ninja_extra import (
     NinjaExtraAPI,
@@ -308,3 +309,21 @@ async def example(self):
         example_route_function.operation.auth_callbacks[0],
         AsyncFakeAuth,
     )
+
+
+def test_namespaced_controller_list(client):
+    response = client.get("/api/inventory-items")
+    assert response.status_code == 200
+    assert response.json() == [{"id": 1, "name": "sample"}]
+    assert reverse("api-1.0.0:inventory:inventory-item-list") == "/api/inventory-items"
+
+
+def test_namespaced_controller_detail(client):
+    response = client.get("/api/inventory-items/5")
+    assert response.status_code == 200
+    assert response.json() == {"id": 5, "name": "sample-5"}
+    assert reverse("api-1.0.0:inventory:inventory-item-detail", kwargs={"item_id": 5}) == "/api/inventory-items/5"
+
+
+def test_default_url_name(client):
+    assert reverse("api-1.0.0:get_event", kwargs={"id": 5}) == "/api/events/5"

tests/urls.py

@@ -3,10 +3,10 @@
 
 from ninja_extra import NinjaExtraAPI
 
-from .controllers import EventController
+from .controllers import EventController, NamespacedController
 
 api = NinjaExtraAPI()
-api.register_controllers(EventController)
+api.register_controllers(EventController, NamespacedController)
 
 
 urlpatterns = [