Added file (@file) decorator to manage creation of FileResponseModel or StreamingResponseModel

Author: eadwinCode

ellar/common/__init__.py

@@ -5,6 +5,7 @@
 from .decorators.command import command
 from .decorators.controller import Controller
 from .decorators.exception import exception_handler
+from .decorators.file import file
 from .decorators.guards import guards
 from .decorators.html import render, template_filter, template_global
 from .decorators.middleware import middleware
@@ -89,4 +90,5 @@
     "Host",
     "Http",
     "UploadFile",
+    "file",
 ]

ellar/common/decorators/__init__.py

@@ -2,6 +2,7 @@
 from .command import command  # noqa
 from .controller import Controller  # noqa
 from .exception import exception_handler  # noqa
+from .file import file  # noqa
 from .guards import guards  # noqa
 from .html import render, template_filter, template_global  # noqa
 from .middleware import middleware  # noqa

ellar/common/decorators/file.py

@@ -0,0 +1,72 @@
+import inspect
+import typing as t
+import warnings
+
+from ellar.constants import NOT_SET, RESPONSE_OVERRIDE_KEY
+from ellar.core.response.model import (
+    FileResponseModel,
+    IResponseModel,
+    StreamingResponseModel,
+)
+from ellar.shortcuts import fail_silently
+
+from .base import set_meta
+
+
+def file(media_type: t.Optional[str] = NOT_SET, streaming: bool = False) -> t.Callable:
+    """
+    ========= ROUTE FUNCTION DECORATOR ==============
+
+    Renders route function response as FileResponse
+
+
+    :param media_type: MIME Type.
+    :param streaming: Defaults ResponseModel to use. False=FileResponseModel, True=StreamingResponseModel.
+    IF STREAMING == FALSE:
+        Decorated Function is expected to return an object of dict with values keys:
+            {
+                path: mandatory path to file,
+                media_type: optional
+                filename: optional filename
+                method: optional HTTP Method
+                content_disposition_type: `attachment` | `inline`
+                status_code: 200
+            }
+    IF STREAMING == TRUE
+        Decorated Function is expected to return:
+            typing.Iterator[Content] OR typing.AsyncIterable[Content]
+    :return: typing.Callable
+    """
+    if media_type is not NOT_SET:
+        assert isinstance(media_type, str), "File decorator must invoked eg. @file()"
+
+    if media_type is NOT_SET:
+        media_type = "text/plain"
+
+    def _decorator(func: t.Union[t.Callable, t.Any]) -> t.Union[t.Callable, t.Any]:
+        if not inspect.isfunction(func):
+            line_nos = fail_silently(
+                inspect.getsourcelines, getattr(func, "endpoint", func)
+            )
+            warnings.warn_explicit(
+                UserWarning(
+                    "\n@file should be used only as a function decorator. "
+                    "\nUse @file before @HTTPMethod decorator."
+                ),
+                category=None,
+                filename=inspect.getfile(getattr(func, "endpoint", func)),
+                lineno=line_nos[1] if line_nos and len(line_nos) > 0 else None,
+                source=None,
+            )
+            return func
+
+        response: IResponseModel
+        if streaming:
+            response = StreamingResponseModel(media_type=media_type)
+        else:
+            response = FileResponseModel(media_type=media_type)
+
+        target_decorator = set_meta(RESPONSE_OVERRIDE_KEY, {200: response})
+        return target_decorator(func)
+
+    return _decorator

ellar/common/decorators/html.py

@@ -11,9 +11,9 @@
 )
 from ellar.core.exceptions import ImproperConfiguration
 from ellar.core.response.model import HTMLResponseModel
-from ellar.core.routing import RouteOperationBase
 from ellar.core.templating import TemplateFunctionData
 from ellar.helper import class_base_function_regex, get_name
+from ellar.shortcuts import fail_silently
 from ellar.types import TemplateFilterCallable, TemplateGlobalCallable
 
 from .base import set_meta
@@ -29,9 +29,13 @@ def render(template_name: t.Optional[str] = NOT_SET) -> t.Callable:
 
     Renders route function response to HTML Response
 
-    :param template_name: template name.
-    when @render is used in a Controller Class, the function becomes the template_name and the path to the html file
+    Decorated Function is expected to return an object of dict as a context variable for the template to be rendered.
+
+    When @render is used in a Controller Class, the function becomes the template_name and the path to the html file
     becomes `templateFolder/ControllerName/functionName`. This can be overridden by providing `template_name`.
+
+    :param template_name: template name.
+
     :return:
     """
     if template_name is not NOT_SET:
@@ -41,15 +45,18 @@ def render(template_name: t.Optional[str] = NOT_SET) -> t.Callable:
     template_name = None if template_name is NOT_SET else template_name
 
     def _decorator(func: t.Union[t.Callable, t.Any]) -> t.Union[t.Callable, t.Any]:
-        if not callable(func) or isinstance(func, RouteOperationBase):
+        if not inspect.isfunction(func):
+            line_nos = fail_silently(
+                inspect.getsourcelines, getattr(func, "endpoint", func)
+            )
             warnings.warn_explicit(
                 UserWarning(
-                    "\n@Render should be used only as a function decorator. "
-                    "\nUse @Render before @Method decorator."
+                    "\n@render should be used only as a function decorator. "
+                    "\nUse @render before @HTTPMethod decorator."
                 ),
                 category=None,
                 filename=inspect.getfile(getattr(func, "endpoint", func)),
-                lineno=inspect.getsourcelines(getattr(func, "endpoint", func))[1],
+                lineno=line_nos[1] if line_nos and len(line_nos) > 0 else None,
                 source=None,
             )
             return func