Merge pull request #138 from python-ellar/openapi_document_renderer_refactor

eadwinCode · web-flow · commit 596b37d7143d · 2023-11-04T09:40:49.000+01:00
OpenAPI module Refactor
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -14,14 +14,14 @@ repos:
       name: Code Formatting
       entry: "make fmt"
       types: [python]
-      language_version: python3.10
+      language_version: python3
       language: python
     - id: code_linting
       args: [ ]
       name: Code Linting
       entry: "make lint"
       types: [ python ]
-      language_version: python3.10
+      language_version: python3
       language: python
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v2.3.0
diff --git a/Makefile b/Makefile
@@ -9,6 +9,7 @@ clean: ## Removing cached python compiled files
 	find . -name \*pyo | xargs  rm -fv
 	find . -name \*~  | xargs  rm -fv
 	find . -name __pycache__  | xargs  rm -rfv
+	find . -name .ruff_cache  | xargs  rm -rfv
 
 install: ## Install dependencies
 	flit install --deps develop --symlink
diff --git a/README.md b/README.md
@@ -50,10 +50,10 @@ $(venv) pip install ellar
 ## **Try This**
 ```python
 import uvicorn
-from ellar.common import Body, Controller, ControllerBase, delete, get, post, put, Serializer, Provide
+from ellar.common import Body, Controller, ControllerBase, delete, get, post, put, Serializer, Inject
 from ellar.core import AppFactory
 from ellar.di import injectable, request_scope
-from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerUI
 from pydantic import Field
 from pathlib import Path
 
@@ -76,20 +76,20 @@ class MotoController(ControllerBase):
         self._service = service
     
     @post()
-    async def create(self, payload: CreateCarSerializer = Body()):
+    async def create(self, payload:  Body[CreateCarSerializer]):
         assert self._service.detail == 'a service'
         result = payload.dict()
         result.update(message='This action adds a new car')
         return result
 
     @put('/{car_id:str}')
-    async def update(self, car_id: str, payload: CreateCarSerializer = Body()):
+    async def update(self, car_id: str, payload: Body[CreateCarSerializer]):
         result = payload.dict()
         result.update(message=f'This action updated #{car_id} car resource')
         return result
 
     @get('/{car_id:str}')
-    async def get_one(self, car_id: str, service: CarService = Provide()):
+    async def get_one(self, car_id: str, service: Inject[CarService]):
         assert self._service == service
         return f"This action returns a #{car_id} car"
 
@@ -113,7 +113,7 @@ document_builder.set_title('Ellar API') \
 
 document = document_builder.build_document(app)
 module = OpenAPIDocumentModule.setup(
-    document_generator=SwaggerDocumentGenerator(),
+    docs_ui=SwaggerUI(),
     document=document,
     guards=[]
 )
diff --git a/docs/index.md b/docs/index.md
@@ -59,7 +59,7 @@ import uvicorn
 from ellar.common import Body, Controller, ControllerBase, delete, get, post, put, Serializer, Inject
 from ellar.core import AppFactory
 from ellar.di import injectable, request_scope
-from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerUI
 from pydantic import Field
 from pathlib import Path
 
@@ -119,7 +119,7 @@ document_builder.set_title('Ellar API') \
 
 document = document_builder.build_document(app)
 module = OpenAPIDocumentModule.setup(
-    document_generator=SwaggerDocumentGenerator(),
+    docs_ui=SwaggerUI(),
     document=document,
     guards=[]
 )
diff --git a/docs/overview/step-one.md b/docs/overview/step-one.md
@@ -53,7 +53,7 @@ In `project_name.server`, we create the `application` instance using the `AppFac
 # project_name/server.py
 import os
 
-from ellar.constants import ELLAR_CONFIG_MODULE
+from ellar.common.constants import ELLAR_CONFIG_MODULE
 from ellar.core.factory import AppFactory
 from .root_module import ApplicationModule
 
@@ -178,9 +178,9 @@ then add the below.
 # project_name/server.py
 
 import os
-from ellar.constants import ELLAR_CONFIG_MODULE
+from ellar.common.constants import ELLAR_CONFIG_MODULE
 from ellar.core.factory import AppFactory
-from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerUI
 from .root_module import ApplicationModule
 
 application = AppFactory.create_from_app_module(
@@ -198,7 +198,7 @@ document_builder.set_title('Project Name API') \
 
 document = document_builder.build_document(application)
 module_config = OpenAPIDocumentModule.setup(
-    document_generator=SwaggerDocumentGenerator(),
+    docs_ui=SwaggerUI(),
     document=document,
     guards=[]
 )
diff --git a/ellar/common/exceptions/handlers.py b/ellar/common/exceptions/handlers.py
@@ -30,7 +30,7 @@ async def catch(
         if isinstance(exc.detail, (list, dict)):
             data = exc.detail
         else:
-            data = {"detail": exc.detail, "status_code": exc.status_code}  # type: ignore[assignment]
+            data = {"detail": exc.detail, "status_code": exc.status_code}
 
         return config.DEFAULT_JSON_CLASS(
             data, status_code=exc.status_code, headers=exc.headers
diff --git a/ellar/di/injector/ellar_injector.py b/ellar/di/injector/ellar_injector.py
@@ -101,7 +101,9 @@ def get_module(self, module: t.Type) -> t.Optional["ModuleRefBase"]:
     def get_templating_modules(
         self,
     ) -> t.Dict[t.Type["ModuleBase"], "ModuleTemplateRef"]:
-        return self._modules.get(MODULE_REF_TYPES.TEMPLATE, {})
+        return self._modules.get(  # type:ignore[no-any-return]
+            MODULE_REF_TYPES.TEMPLATE, {}
+        )
 
     def add_module(self, module_ref: t.Union["ModuleRefBase", "ModuleSetup"]) -> None:
         self._modules[module_ref.ref_type].update({module_ref.module: module_ref})
diff --git a/ellar/openapi/__init__.py b/ellar/openapi/__init__.py
@@ -1,9 +1,9 @@
 from .builder import OpenAPIDocumentBuilder
 from .decorators import ApiTags, openapi_info
-from .docs_generators import (
-    IDocumentationGenerator,
-    ReDocDocumentGenerator,
-    SwaggerDocumentGenerator,
+from .docs_ui import (
+    IDocumentationUIContext,
+    ReDocsUI,
+    SwaggerUI,
 )
 from .module import OpenAPIDocumentModule
 from .route_doc_models import (
@@ -13,14 +13,14 @@
 )
 
 __all__ = [
-    "IDocumentationGenerator",
+    "IDocumentationUIContext",
     "OpenAPIDocumentBuilder",
     "OpenAPIRoute",
     "OpenAPIMountDocumentation",
     "OpenAPIRouteDocumentation",
     "OpenAPIDocumentModule",
-    "ReDocDocumentGenerator",
-    "SwaggerDocumentGenerator",
+    "ReDocsUI",
+    "SwaggerUI",
     "openapi_info",
     "ApiTags",
 ]
diff --git a/ellar/openapi/docs_generators/__init__.py b/ellar/openapi/docs_generators/__init__.py
diff --git a/ellar/openapi/docs_ui/__init__.py b/ellar/openapi/docs_ui/__init__.py
@@ -0,0 +1,9 @@
+from .base import IDocumentationUIContext
+from .redocs import ReDocsUI
+from .swagger import SwaggerUI
+
+__all__ = [
+    "IDocumentationUIContext",
+    "ReDocsUI",
+    "SwaggerUI",
+]
diff --git a/ellar/openapi/docs_ui/base.py b/ellar/openapi/docs_ui/base.py
@@ -1,7 +1,11 @@
 from abc import ABC, abstractmethod
 
 
-class IDocumentationGenerator(ABC):
+class IDocumentationUIContext(ABC):
+    """
+    Provides Context that for rendering OPENAPI Docs
+    """
+
     @property
     @abstractmethod
     def title(self) -> str:
diff --git a/ellar/openapi/docs_ui/redocs.py b/ellar/openapi/docs_ui/redocs.py
@@ -1,7 +1,7 @@
-from .base import IDocumentationGenerator
+from .base import IDocumentationUIContext
 
 
-class ReDocDocumentGenerator(IDocumentationGenerator):
+class ReDocsUI(IDocumentationUIContext):
     @property
     def template_name(self) -> str:
         return "redocs.html"
diff --git a/ellar/openapi/docs_ui/swagger.py b/ellar/openapi/docs_ui/swagger.py
@@ -1,7 +1,7 @@
-from .base import IDocumentationGenerator
+from .base import IDocumentationUIContext
 
 
-class SwaggerDocumentGenerator(IDocumentationGenerator):
+class SwaggerUI(IDocumentationUIContext):
     @property
     def template_name(self) -> str:
         return "swagger.html"
diff --git a/ellar/openapi/module.py b/ellar/openapi/module.py
@@ -4,7 +4,7 @@
 from ellar.common.models import GuardCanActivate
 from ellar.core import DynamicModule, ModuleBase
 from ellar.di import injectable
-from ellar.openapi.docs_generators import IDocumentationGenerator
+from ellar.openapi.docs_ui import IDocumentationUIContext
 from ellar.openapi.openapi_v3 import OpenAPI
 
 __all__ = ["OpenAPIDocumentModule"]
@@ -21,9 +21,7 @@ class OpenAPIDocumentModule(ModuleBase, IModuleSetup):
     @classmethod
     def setup(
         cls,
-        document_generator: t.Union[
-            t.Sequence[IDocumentationGenerator], IDocumentationGenerator
-        ],
+        docs_ui: t.Union[t.Sequence[IDocumentationUIContext], IDocumentationUIContext],
         document: t.Optional[OpenAPI] = None,
         router_prefix: str = "",
         openapi_url: t.Optional[str] = None,
@@ -35,18 +33,18 @@ def setup(
         _guards = list(guards) if guards else []
         if allow_any:
             _guards = [AllowAnyGuard] + _guards
-        _document_generator: t.List[IDocumentationGenerator] = []
+        _document_renderer: t.List[IDocumentationUIContext] = []
         router = ModuleRouter(
             router_prefix,
             guards=_guards,
             name="ellar-open-api",
             include_in_schema=False,
         )
 
-        if isinstance(document_generator, (list, tuple, set)):
-            _document_generator = list(document_generator)
+        if isinstance(docs_ui, (list, tuple, set)):
+            _document_renderer = list(docs_ui)
         else:
-            _document_generator = [document_generator]  # type: ignore[list-item]
+            _document_renderer = [docs_ui]  # type: ignore[list-item]
 
         if not openapi_url and document:
             openapi_url = "/openapi.json"
@@ -56,11 +54,11 @@ def openapi_schema() -> t.Any:
                 assert document and isinstance(document, OpenAPI), "Invalid Document"
                 return document
 
-        for doc_gen in _document_generator:
-            if not isinstance(doc_gen, IDocumentationGenerator):
+        for doc_gen in _document_renderer:
+            if not isinstance(doc_gen, IDocumentationUIContext):
                 raise Exception(
                     f"{doc_gen.__class__.__name__ if not isinstance(doc_gen, type) else doc_gen.__name__} "
-                    f"must be of type `IDocumentationGenerator`"
+                    f"must be of type `IDocumentationUIContext`"
                 )
 
             template_context = dict(doc_gen.template_context)
diff --git a/tests/test_openapi/test_module.py b/tests/test_openapi/test_module.py
@@ -9,8 +9,8 @@
 from ellar.openapi import (
     OpenAPIDocumentBuilder,
     OpenAPIDocumentModule,
-    ReDocDocumentGenerator,
-    SwaggerDocumentGenerator,
+    ReDocsUI,
+    SwaggerUI,
 )
 from ellar.openapi.module import AllowAnyGuard
 from ellar.reflect import reflect
@@ -51,7 +51,7 @@ def test_openapi_module_with_openapi_url_doesnot_create_new_openapi_url():
     module_config = OpenAPIDocumentModule.setup(
         openapi_url="/openapi_url.json",
         document=document,
-        document_generator=SwaggerDocumentGenerator(),
+        docs_ui=SwaggerUI(),
     )
     app.install_module(module_config)
     res = client.get("/docs")
@@ -64,9 +64,7 @@ def test_openapi_module_creates_openapi_url():
     document = OpenAPIDocumentBuilder().build_document(app)
     client = TestClient(app)
 
-    module_config = OpenAPIDocumentModule.setup(
-        document=document, document_generator=SwaggerDocumentGenerator()
-    )
+    module_config = OpenAPIDocumentModule.setup(document=document, docs_ui=SwaggerUI())
     app.install_module(module_config)
     res = client.get("/docs")
 
@@ -121,9 +119,7 @@ def test_openapi_module_creates_swagger_endpoint():
     module_config = OpenAPIDocumentModule.setup(
         openapi_url="/openapi_url.json",
         document=document,
-        document_generator=SwaggerDocumentGenerator(
-            title="Swagger Doc Test", path="docs-swagger-test"
-        ),
+        docs_ui=SwaggerUI(title="Swagger Doc Test", path="docs-swagger-test"),
     )
     app.install_module(module_config)
     client = TestClient(app)
@@ -141,9 +137,7 @@ def test_openapi_module_creates_redocs_endpoint():
     module_config = OpenAPIDocumentModule.setup(
         openapi_url="/openapi_url.json",
         document=document,
-        document_generator=ReDocDocumentGenerator(
-            title="Redocs Doc Test", path="docs-redocs-test"
-        ),
+        docs_ui=ReDocsUI(title="Redocs Doc Test", path="docs-redocs-test"),
     )
     app.install_module(module_config)
     client = TestClient(app)
@@ -163,7 +157,7 @@ def test_openapi_module_with_route_guards():
     module_config = OpenAPIDocumentModule.setup(
         document=document,
         guards=[CustomDocsGuard],
-        document_generator=(SwaggerDocumentGenerator(), ReDocDocumentGenerator()),
+        docs_ui=(SwaggerUI(), ReDocsUI()),
     )
     app.install_module(module_config)
     client = TestClient(app)
@@ -194,17 +188,17 @@ def test_invalid_open_api_doc_setup():
         OpenAPIDocumentModule.setup(
             document=document,
             guards=[CustomDocsGuard],
-            document_generator=(CustomDocsGuard(),),
+            docs_ui=(CustomDocsGuard(),),
         )
-    assert str(ex.value) == "CustomDocsGuard must be of type `IDocumentationGenerator`"
+    assert str(ex.value) == "CustomDocsGuard must be of type `IDocumentationUIContext`"
 
     with pytest.raises(Exception) as ex:
         OpenAPIDocumentModule.setup(
             document=document,
             guards=[CustomDocsGuard],
-            document_generator=(CustomDocsGuard,),
+            docs_ui=(CustomDocsGuard,),
         )
-    assert str(ex.value) == "CustomDocsGuard must be of type `IDocumentationGenerator`"
+    assert str(ex.value) == "CustomDocsGuard must be of type `IDocumentationUIContext`"
 
 
 def test_app_global_guard_blocks_openapi_doc_page():
@@ -214,11 +208,25 @@ def test_app_global_guard_blocks_openapi_doc_page():
 
     module_config = OpenAPIDocumentModule.setup(
         document=document,
-        document_generator=SwaggerDocumentGenerator(),
+        docs_ui=SwaggerUI(),
         allow_any=False,
     )
     app.install_module(module_config)
     response = client.get("/docs")
 
     assert response.status_code == 403
     assert response.json() == {"detail": "Not Allowed", "status_code": 403}
+
+    module_config = OpenAPIDocumentModule.setup(
+        document=document,
+        docs_ui=SwaggerUI(),
+        allow_any=False,
+        guards=[CustomDocsGuard],
+    )
+    app.install_module(module_config)
+
+    guards = reflect.get_metadata(
+        GUARDS_KEY, module_config.routers[0].get_control_type()
+    )
+    assert len(guards) == 1
+    assert AllowAnyGuard not in guards
