Merge pull request #117 from eadwinCode/style_and_body_fixes

MyPy Liniting Fix And Embedded Body

Author: eadwinCode

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
+	ruff --clean
 
 install: ## Install dependencies
 	flit install --deps develop --symlink
@@ -22,7 +23,7 @@ lint: ## Run code linters
 	ruff check ellar tests examples
 	mypy ellar
 
-fmt format: ## Run code formatters
+fmt format:clean ## Run code formatters
 	black ellar tests examples
 	ruff check --fix ellar tests examples
 

README.md

@@ -235,7 +235,7 @@ from ellar.common import Module, exception_handler, JSONResponse, Response, IHos
 from ellar.core import ModuleBase
 
 from ellar.samples.modules import HomeModule
-from .apps.car.module import CarModule
+from .car.module import CarModule
 
 
 @Module(modules=[HomeModule, CarModule])

docs/cli/command-grouping.md

@@ -6,7 +6,7 @@ For instance, a `db` command may have sub-commands like `makemigrations`, `migra
 To achieve this use-case, let us create a file `commands.py` in the root level of the project.
 
 ```python
-from ellar.commands import EllarTyper
+from ellar.common import EllarTyper
 
 db = EllarTyper(name="db")
 

docs/cli/create-module-command.md

@@ -3,9 +3,12 @@ This command helps you create an Ellar project module, like a small app within a
 It depends on the existence of an Ellar project.
 
 ```shell
-ellar create-module my_project_module
+ellar create-module my_project_module directory
+```
+for example:
+```shell
+ellar create-module my_project_module apps/
 ```
-
 will create a folder as follows:
 ```angular2html
 john_doe/
@@ -29,3 +32,7 @@ john_doe/
 ├─ server.py
 
 ```
+
+## **New Command CLI Arguments**
+- `module-name` Set the resulting module name.
+- `directory` Path to dump the scaffolded files. `.` can be used to select current directory.

docs/cli/create-project-command.md

@@ -2,7 +2,12 @@
 This command helps you create just an Ellar project provided the `"pyproject.toml"` file exists in the working directory(`CWD`)
 
 ```shell
-ellar create-project my_new_project
+ellar create-project my_new_project directory
+```
+
+for example:
+```shell
+ellar create-project my_new_project 
 ```
 
 will create a folder as follows:
@@ -17,3 +22,8 @@ my_new_project/
 ├─ server.py
 ├─ __init__.py
 ```
+
+
+## **Create Project Command Arguments**
+- `project-name` Set the resulting project module name.
+- `directory` Path to dump the scaffolded files. `.` can be used to select current directory.

docs/cli/new-command.md

@@ -28,12 +28,12 @@ my-project/
 If you want to name your project differently than the folder, you can pass the `--project-name` option.
 
 ```shell
-ellar new my-project --project-name john-doe
+ellar new my-project path/to/scaffold-the-new-project
 ```
 will create a folder as follows:
 ```angular2html
-my-project/
-├─ john_doe/
+path/to/scaffold-the-new-project/
+├─ my_project/
 │  ├─ apps/
 │  │  ├─ __init__.py
 │  ├─ core/
@@ -49,5 +49,6 @@ my-project/
 
 ```
 
-## **New Command CLI Options**
-- `--project-name` Set the resulting project module name. Defaults to folder-name is not provided.
+## **New Command CLI Arguments**
+- `project-name` Set the resulting project module name.
+- `directory` Path to dump the scaffolded files. `.` can be used to select current directory.

docs/overview/step-one.md

@@ -24,8 +24,6 @@ Also, some boilerplate files are populated and installed in a new `project_name`
 ```shell
 project-name/
 ├─ project_name/
-│  ├─ apps/
-│  │  ├─ __init__.py
 │  ├─ core/
 │  ├─ domain/
 │  ├─ config.py
@@ -44,7 +42,6 @@ A brief overview of generated core files:
 |----------------------------|----------------------------------------------------------------------------------------------------------------|
 | `pyproject.toml`           | Python project metadata store.                                                                                 |
 | `README.md`                | Project Description and documentation.                                                                         |
-| `project_name.apps`        | Root path to all project modules.                                                                              |
 | `project_name.core`        | Core/business logic folder.                                                                                    |
 | `project_name.domain`      | Domain logic folder.                                                                                           |
 | `project_name.config`      | Application configuration file                                                                                 |
@@ -124,7 +121,7 @@ One last thing, before we move to the next page, we need to create an app `modul
 
 Lets add a `car` module/app to our project:
 ```shell
-$(venv) ellar create-module car
+$(venv) ellar create-module car apps/
 ```
 The result of this CLI command is stored in `project-name/project_name/apps`
 ```

ellar/auth/__init__.py

@@ -1,7 +1,7 @@
-from .decorators import CheckPolicies
-from .guard import AuthorizationGuard
+from .decorators import Authorize, CheckPolicies
 from .handlers import BaseAuthenticationHandler
 from .identity import UserIdentity
+from .interceptor import AuthorizationInterceptor
 from .interfaces import IIdentitySchemes
 from .policy import (
     BasePolicyHandler,
@@ -13,7 +13,8 @@
 
 __all__ = [
     "CheckPolicies",
-    "AuthorizationGuard",
+    "AuthorizationInterceptor",
+    "Authorize",
     "BaseAuthenticationHandler",
     "CheckPolicies",
     "BasePolicyHandler",

ellar/auth/decorators.py

@@ -1,15 +1,17 @@
 import typing as t
 
 from ellar.common import set_metadata as set_meta
+from ellar.common.constants import ROUTE_INTERCEPTORS
 
 from .constants import POLICY_KEYS
+from .interceptor import AuthorizationInterceptor
 from .policy import PolicyType
 
 
 def CheckPolicies(*policies: t.Union[str, PolicyType]) -> t.Callable:
     """
     ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
-
+    Decorates a controller or a route function with specific policy requirements
     :param policies:
     :return:
     """
@@ -19,3 +21,13 @@ def _decorator(target: t.Callable) -> t.Union[t.Callable, t.Any]:
         return target
 
     return _decorator
+
+
+def Authorize() -> t.Callable:
+    """
+    ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
+    Decorates a controller class or route function with  `AuthorizationInterceptor`
+    :return:
+    """
+
+    return set_meta(ROUTE_INTERCEPTORS, [AuthorizationInterceptor])

ellar/auth/guard.py renamed to ellar/auth/interceptor.py

@@ -1,7 +1,7 @@
 import typing as t
 from functools import partial
 
-from ellar.common import APIException, GuardCanActivate, IExecutionContext
+from ellar.common import APIException, EllarInterceptor, IExecutionContext
 from ellar.di import injectable
 from starlette import status
 
@@ -10,7 +10,7 @@
 
 
 @injectable
-class AuthorizationGuard(GuardCanActivate):
+class AuthorizationInterceptor(EllarInterceptor):
     status_code = status.HTTP_403_FORBIDDEN
     exception_class = APIException
 
@@ -31,14 +31,16 @@ def _get_policy_instance(
             return context.get_service_provider().get(policy)
         return policy
 
-    async def can_activate(self, context: IExecutionContext) -> bool:
+    async def intercept(
+        self, context: IExecutionContext, next_interceptor: t.Callable[..., t.Coroutine]
+    ) -> t.Any:
         if not context.user.is_authenticated:
             raise self.exception_class(status_code=401)
 
         policies = self.get_route_handler_policy(context)
 
         if not policies:
-            return True
+            return await next_interceptor()
 
         partial_get_policy_instance = partial(self._get_policy_instance, context)
 
@@ -48,7 +50,7 @@ async def can_activate(self, context: IExecutionContext) -> bool:
             if not result:
                 self.raise_exception()
 
-        return True
+        return await next_interceptor()
 
     def raise_exception(self) -> None:
         raise self.exception_class(status_code=self.status_code)

ellar/cache/backends/redis/backend.py

@@ -5,12 +5,14 @@
 from ellar.common.helper.event_loop import get_or_create_eventloop
 
 try:
-    from redis.asyncio import Redis  # type: ignore
-    from redis.asyncio.connection import ConnectionPool  # type: ignore
+    from redis.asyncio import Redis
+    from redis.asyncio.connection import ConnectionPool
 except ImportError as e:  # pragma: no cover
     raise RuntimeError(
         "To use `RedisCacheBackend`, you have to install 'redis' package e.g. `pip install redis`"
     ) from e
+
+
 from ...interface import IBaseCacheBackendAsync
 from ...make_key_decorator import make_key_decorator, make_key_decorator_and_validate
 from ...model import BaseCacheBackend
@@ -61,7 +63,7 @@ def decr(self, key: str, delta: int = 1, version: t.Optional[str] = None) -> int
 
 
 class RedisCacheBackend(_RedisCacheBackendSync, BaseCacheBackend):
-    MEMCACHE_CLIENT: t.Any = Redis
+    MEMCACHE_CLIENT: t.Type[Redis] = Redis
     """Redis-based cache backend.
 
     Redis Server Construct example::
@@ -145,7 +147,11 @@ async def set_async(
         if ttl == 0:
             await client.delete(key)
 
-        return bool(await client.set(key, value, ex=self.get_backend_ttl(ttl)))
+        return bool(
+            await client.set(
+                key, value, ex=self.get_backend_ttl(ttl)  # type:ignore[arg-type]
+            )
+        )
 
     @make_key_decorator
     async def delete_async(self, key: str, version: t.Optional[str] = None) -> bool:
@@ -164,7 +170,10 @@ async def touch_async(
         if ttl is None:
             res = await client.persist(key)
             return bool(res)
-        res = await client.expire(key, self.get_backend_ttl(ttl))
+
+        res = await client.expire(
+            key, self.get_backend_ttl(ttl)  # type:ignore[arg-type]
+        )
         return bool(res)
 
     @make_key_decorator

ellar/common/decorators/controller.py

@@ -70,20 +70,12 @@ def reflect_all_controller_type_routes(cls: t.Type[ControllerBase]) -> None:
                 )
 
 
-@t.overload
-def Controller(
-    prefix: t.Optional[str] = None,
-) -> t.Union[t.Type[ControllerBase], t.Callable[..., t.Any], t.Any]:  # pragma: no cover
-    ...
-
-
-@t.overload
 def Controller(
     prefix: t.Optional[str] = None,
     *,
     name: t.Optional[str] = None,
     include_in_schema: bool = True,
-) -> t.Union[t.Type[ControllerBase], t.Callable[..., t.Any], t.Any]:  # pragma: no cover
+) -> t.Union[t.Type[ControllerBase], t.Callable[..., t.Any], t.Any]:
     """
     ========= CLASS DECORATOR ==============
 
@@ -93,22 +85,6 @@ def Controller(
     :param include_in_schema: include controller in OPENAPI schema
     :return: t.Type[ControllerBase]
     """
-    ...
-
-
-def Controller(
-    prefix: t.Optional[str] = None,
-    *,
-    name: t.Optional[str] = None,
-    include_in_schema: bool = True,
-) -> t.Union[t.Type[ControllerBase], t.Callable[..., t.Any], t.Any]:
-    """
-    Controller Class Decorator
-    :param prefix: Route Prefix default=[ControllerName]
-    :param name: route name prefix for url reversing, eg name:route_name default=controller_name
-    :param include_in_schema: include controller in OPENAPI schema
-    :return: t.Type[ControllerBase]
-    """
     _prefix: t.Optional[t.Any] = prefix if prefix is not None else NOT_SET
     if prefix and isinstance(prefix, type):
         _prefix = NOT_SET

ellar/common/interfaces/__init__.py

@@ -12,6 +12,7 @@
 from .exceptions import IExceptionHandler, IExceptionMiddlewareService
 from .guard_consumer import IGuardsConsumer
 from .interceptor_consumer import IInterceptorsConsumer
+from .middleware import IEllarMiddleware
 from .module import IModuleSetup
 from .response_model import IResponseModel
 from .templating import IModuleTemplateLoader
@@ -37,4 +38,5 @@
     "IApplicationStartup",
     "IAPIVersioning",
     "IAPIVersioningResolver",
+    "IEllarMiddleware",
 ]

ellar/common/interfaces/exceptions.py

@@ -7,6 +7,19 @@
 
 
 class IExceptionHandler(ABC, t.Iterable):
+    @classmethod
+    def __get_validators__(
+        cls: t.Type["IExceptionHandler"],
+    ) -> t.Iterable[t.Callable[..., t.Any]]:
+        # for Pydantic Model Validation
+        yield cls.__validate
+
+    @classmethod
+    def __validate(cls, v: t.Any) -> t.Any:
+        if not isinstance(v, cls):
+            raise ValueError(f"Expected IExceptionHandler object, received: {type(v)}")
+        return v
+
     def __eq__(self, other: t.Any) -> bool:
         if isinstance(other, IExceptionHandler):
             return other.exception_type_or_code == self.exception_type_or_code

ellar/common/interfaces/middleware.py

@@ -0,0 +1,16 @@
+import typing as t
+
+
+class IEllarMiddleware:
+    @classmethod
+    def __get_validators__(
+        cls: t.Type["IEllarMiddleware"],
+    ) -> t.Iterable[t.Callable[..., t.Any]]:
+        # for Pydantic Model Validation
+        yield cls.__validate
+
+    @classmethod
+    def __validate(cls, v: t.Any) -> t.Any:
+        if not isinstance(v, cls):
+            raise ValueError(f"Expected EllarMiddleware object, received: {type(v)}")
+        return v  # pragma: no cover

ellar/common/interfaces/versioning.py

@@ -14,3 +14,16 @@ class IAPIVersioning(ABC):
     @abstractmethod
     def get_version_resolver(self, scope: TScope) -> IAPIVersioningResolver:
         """Retrieve Version Resolver"""
+
+    @classmethod
+    def __get_validators__(
+        cls: t.Type["IAPIVersioning"],
+    ) -> t.Iterable[t.Callable[..., t.Any]]:
+        # for Pydantic Model Validation
+        yield cls.__validate
+
+    @classmethod
+    def __validate(cls, v: t.Any) -> t.Any:
+        if not isinstance(v, cls):
+            raise ValueError(f"Expected BaseAPIVersioning, received: {type(v)}")
+        return v