Merge pull request #7 from eadwinCode/example_fix

ellar example and renamed route operations

Author: eadwinCode

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Ezeudoh Tochukwu
+
+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.

README.md

@@ -33,5 +33,79 @@
 pip install ellar
 ```
 
+## Usage
+
+Create a file `controller.py`:
+
+```Python
+from ellar.common import ModuleRouter, Controller, get
+
+router = ModuleRouter('', tag='Math')
+
+
+@router.get("/add")
+def add(request, a: int, b: int):
+    return {"result": a + b}
+
+
+@Controller("", tag='Math')
+class MathAPI:
+
+    @get('/subtract', )
+    def subtract(self, a: int, b: int):
+        """Subtracts a from b"""
+        return {"result": a - b}
+
+    @get('/divide', )
+    def divide(self, a: int, b: int):
+        """Divides a by b"""
+        return {"result": a / b}
+
+    @get('/multiple', )
+    def multiple(self, a: int, b: int):
+        """Multiples a with b"""
+        return {"result": a * b}
+
+```
+
+Create another file `server.py`:
+
+```Python
+from ellar.core import AppFactory
+from ellar.openapi.builder import OpenAPIDocumentBuilder
+from ellar.openapi.module import OpenAPIDocumentModule
+from .controller import router, MathAPI
+
+
+app = AppFactory.create_app(routers=(router, ), controllers=(MathAPI, ))
+
+document_builder = OpenAPIDocumentBuilder()
+document_builder.set_title('Your Title')\
+    .set_version('1.0.2')\
+    .set_contact(name='Eadwin', url='https://www.yahoo.com', email='eadwin@gmail.com')\
+    .set_license('MIT Licence', url='https://www.google.com')
+
+document = document_builder.build_document(app)
+module = app.install_module(OpenAPIDocumentModule, document=document)
+module.setup_swagger_doc()
+```
+
+### Interactive API docs
+
+Now go to <a href="http://localhost:8000/docs/" target="_blank">http://localhost:8000/docs/</a>
+
+You will see the automatic interactive API documentation (provided by <a href="https://github.com/swagger-api/swagger-ui" target="_blank">Swagger UI</a>):
+
+![Swagger UI](docs/img/ellar_demo.gif)
+
 ## Status
 Project is still in development
+- Remaining testing modules:
+    - common
+    - configuration
+    - guard
+    - openapi
+- Project CLI scaffolding
+- Database Plugin with [Encode/ORM](https://github.com/encode/orm)
+- Caching 
+- API Throttling

docs/img/ellar_demo.gif

@@ -5,24 +5,24 @@
 from .decorators.controller import Controller
 from .decorators.exception import exception_handler
 from .decorators.guards import guards
-from .decorators.html import Render, template_filter, template_global
+from .decorators.html import render, template_filter, template_global
 from .decorators.middleware import middleware
 from .decorators.modules import Module
 from .decorators.openapi import openapi
 from .decorators.request import on_shutdown, on_startup
 from .decorators.serializer import serializer_filter
 from .decorators.versioning import version
 from .routing import (
-    Delete,
-    Get,
-    Head,
-    HttpRoute,
-    Options,
-    Patch,
-    Post,
-    Put,
-    Trace,
-    WsRoute,
+    delete,
+    get,
+    head,
+    http_route,
+    options,
+    patch,
+    post,
+    put,
+    trace,
+    ws_route,
 )
 from .routing.params import (
     Body,
@@ -41,7 +41,7 @@
 
 __all__ = [
     "ModuleRouter",
-    "Render",
+    "render",
     "Module",
     "guards",
     "Param",
@@ -50,16 +50,16 @@
     "Controller",
     "openapi",
     "version",
-    "Delete",
-    "Get",
-    "Head",
-    "HttpRoute",
-    "Options",
-    "Patch",
-    "Post",
-    "Put",
-    "Trace",
-    "WsRoute",
+    "delete",
+    "get",
+    "head",
+    "http_route",
+    "options",
+    "patch",
+    "post",
+    "put",
+    "trace",
+    "ws_route",
     "Body",
     "Cookie",
     "File",

ellar/common/__init__.py

@@ -2,7 +2,7 @@
 from .controller import Controller  # noqa
 from .exception import exception_handler  # noqa
 from .guards import guards  # noqa
-from .html import Render, template_filter, template_global  # noqa
+from .html import render, template_filter, template_global  # noqa
 from .middleware import middleware  # noqa
 from .modules import Module  # noqa
 from .openapi import openapi  # noqa

ellar/common/decorators/__init__.py

@@ -82,7 +82,7 @@ def Controller(
     ] = None,
     include_in_schema: bool = True,
 ) -> t.Union[t.Type[ControllerBase], t.Callable[..., t.Any], t.Any]:
-    _prefix: t.Optional[t.Any] = prefix or NOT_SET
+    _prefix: t.Optional[t.Any] = prefix if prefix is not None else NOT_SET
     if prefix and isinstance(prefix, type):
         _prefix = NOT_SET
 
@@ -118,7 +118,7 @@ def _decorator(cls: t.Type) -> t.Type[ControllerBase]:
         _tag = _controller_type.controller_class_name()
 
         if not kwargs.openapi.tag:  # type: ignore
-            kwargs.openapi.tag = _tag  # type: ignore
+            kwargs["openapi"]["tag"] = _tag  # type: ignore
 
         if kwargs["path"] is NOT_SET:
             kwargs["path"] = f"/{_tag}"

ellar/common/decorators/controller.py

@@ -24,18 +24,17 @@ class RenderDecoratorException(Exception):
     pass
 
 
-class Render:
-    def __init__(self, template_name: t.Optional[str] = NOT_SET) -> None:
-        if template_name is not NOT_SET:
-            assert isinstance(
-                template_name, str
-            ), "Render Operation must invoked eg. @Render()"
-        self.template_name = None if template_name is NOT_SET else template_name
-        self.class_base_function_regex = re.compile(
-            "<\\w+ (\\w+)\\.(\\w+) at \\w+>", re.IGNORECASE
-        )
-
-    def __call__(self, func: t.Union[t.Callable, t.Any]) -> t.Union[t.Callable, t.Any]:
+def render(template_name: t.Optional[str] = NOT_SET) -> t.Callable:
+    if template_name is not NOT_SET:
+        assert isinstance(
+            template_name, str
+        ), "Render Operation must invoked eg. @Render()"
+    template_name = None if template_name is NOT_SET else template_name
+    class_base_function_regex = re.compile(
+        "<\\w+ (\\w+)\\.(\\w+) at \\w+>", re.IGNORECASE
+    )
+
+    def _decorator(func: t.Union[t.Callable, t.Any]) -> t.Union[t.Callable, t.Any]:
         if not callable(func) or isinstance(func, RouteOperationBase):
             warnings.warn_explicit(
                 UserWarning(
@@ -52,23 +51,25 @@ def __call__(self, func: t.Union[t.Callable, t.Any]) -> t.Union[t.Callable, t.An
         endpoint_name = get_name(func)
         is_class_base_function = use_mvc = False
 
-        if self.class_base_function_regex.match(repr(func)):
+        if class_base_function_regex.match(repr(func)):
             is_class_base_function = True
 
-        if not self.template_name and is_class_base_function:
+        if not template_name and is_class_base_function:
             use_mvc = True
 
-        if not self.template_name and not is_class_base_function:
+        if not template_name and not is_class_base_function:
             raise RenderDecoratorException(
                 f"template_name is required for function endpoints. {func}"
             )
 
         response = HTMLResponseModel(
-            template_name=self.template_name or endpoint_name, use_mvc=use_mvc
+            template_name=template_name or endpoint_name, use_mvc=use_mvc
         )
         target_decorator = set_meta(RESPONSE_OVERRIDE_KEY, {200: response})
         return target_decorator(func)
 
+    return _decorator
+
 
 def _validate_template_function(f: t.Any) -> None:
     if asyncio.iscoroutinefunction(f):

ellar/common/decorators/html.py

@@ -18,20 +18,20 @@
 
 _route_definitions = OperationDefinitions()
 
-Get = _route_definitions.get
-Post = _route_definitions.post
+get = _route_definitions.get
+post = _route_definitions.post
 
-Delete = _route_definitions.delete
-Patch = _route_definitions.patch
+delete = _route_definitions.delete
+patch = _route_definitions.patch
 
-Put = _route_definitions.put
-Options = _route_definitions.options
+put = _route_definitions.put
+options = _route_definitions.options
 
-Trace = _route_definitions.trace
-Head = _route_definitions.head
+trace = _route_definitions.trace
+head = _route_definitions.head
 
-HttpRoute = _route_definitions.http_route
-WsRoute = _route_definitions.ws_route
+http_route = _route_definitions.http_route
+ws_route = _route_definitions.ws_route
 
 __all__ = [
     "Ctx",
@@ -48,14 +48,14 @@
     "Query",
     "Param",
     "ParamTypes",
-    "Get",
-    "Post",
-    "Delete",
-    "Patch",
-    "Put",
-    "Options",
-    "Trace",
-    "Head",
-    "HttpRoute",
-    "WsRoute",
+    "get",
+    "post",
+    "delete",
+    "patch",
+    "put",
+    "options",
+    "trace",
+    "head",
+    "http_route",
+    "ws_route",
 ]

ellar/common/routing/__init__.py

@@ -1,6 +1,6 @@
 import sys
 
 if sys.version_info >= (3, 7):  # pragma: no cover
-    from contextlib import asynccontextmanager as asynccontextmanager
+    from contextlib import asynccontextmanager as asynccontextmanager  # noqa
 else:
     from contextlib2 import asynccontextmanager as asynccontextmanager  # noqa

ellar/compatible/contextmanager.py

@@ -191,17 +191,17 @@ def __init__(
         )
         _route_definitions = self.operation_definition_class(t.cast(list, self.routes))
 
-        self.Get = _route_definitions.get
-        self.Post = _route_definitions.post
+        self.get = _route_definitions.get
+        self.post = _route_definitions.post
 
-        self.Delete = _route_definitions.delete
-        self.Patch = _route_definitions.patch
+        self.delete = _route_definitions.delete
+        self.patch = _route_definitions.patch
 
-        self.Put = _route_definitions.put
-        self.Options = _route_definitions.options
+        self.put = _route_definitions.put
+        self.options = _route_definitions.options
 
-        self.Trace = _route_definitions.trace
-        self.Head = _route_definitions.head
+        self.trace = _route_definitions.trace
+        self.head = _route_definitions.head
 
-        self.HttpRoute = _route_definitions.http_route
-        self.WsRoute = _route_definitions.ws_route
+        self.http_route = _route_definitions.http_route
+        self.ws_route = _route_definitions.ws_route

ellar/core/routing/router/module.py

@@ -1,6 +1,6 @@
 import typing as t
 
-from ellar.common import Get, Module, Render, guards as guards_decorator
+from ellar.common import Module, get, guards as guards_decorator, render
 from ellar.core.guard import GuardCanActivate
 from ellar.core.main import App
 from ellar.core.modules import ModuleBase
@@ -26,7 +26,7 @@ def __init__(
         if not openapi_url and document:
             self._openapi_url = "/openapi.json"
 
-            @Get(self._openapi_url, include_in_schema=False)
+            @get(self._openapi_url, include_in_schema=False)
             @guards_decorator(*self._guards)
             def openapi_schema() -> t.Any:
                 assert document and isinstance(document, OpenAPI), "Invalid Document"
@@ -39,8 +39,8 @@ def _setup_docs(
     ) -> None:
         _path = path.lstrip("/").rstrip("/")
 
-        @Get(f"/{_path}", include_in_schema=False)
-        @Render(template_name)
+        @get(f"/{_path}", include_in_schema=False)
+        @render(template_name)
         @guards_decorator(*self._guards)
         def _doc() -> t.Any:
             return template_context