Merge pull request #93 from eadwinCode/guards_to_use_guard

Guards to UseGuards

Author: eadwinCode

docs/basics/execution-context.md

@@ -267,7 +267,7 @@ Next, we apply the `RoleGuard` to `CarController`
 ```python
 # project_name/apps/cars/controllers.py
 import typing
-from ellar.common import Body, Controller, post, set_metadata, Guards, ControllerBase
+from ellar.common import Body, Controller, post, set_metadata, UseGuards, ControllerBase
 from .schemas import CreateCarSerializer
 from .guards import RoleGuard
 
@@ -276,7 +276,7 @@ def roles(*_roles: str) -> typing.Callable:
 
 
 @Controller('/car')
-@Guards(RoleGuard)
+@UseGuards(RoleGuard)
 class CarController(ControllerBase):
     @post()
     @roles('admin', 'is_staff')

docs/basics/testing.md

@@ -152,12 +152,12 @@ class TestCarController:
 ```
 We this, anywhere `CarRepository` is needed, a `MockCarRepository()` instance will be applied.
 
-In same way, we can override `Guards` used in controllers during testing. For example, lets assume `CarController` has a guard `JWTGuard`
+In same way, we can override `UseGuards` used in controllers during testing. For example, lets assume `CarController` has a guard `JWTGuard`
 
 ```python
 import typing
 from ellar.common.compatible import AttributeDict
-from ellar.common import Guards, Controller, ControllerBase
+from ellar.common import UseGuards, Controller, ControllerBase
 from ellar.core.guard import HttpBearerAuth
 from ellar.di import injectable
 
@@ -169,7 +169,7 @@ class JWTGuard(HttpBearerAuth):
         return AttributeDict(is_authenticated=True, first_name='Ellar', last_name='ASGI Framework') 
 
 
-@Guards(JWTGuard)
+@UseGuards(JWTGuard)
 @Controller('/car')
 class CarController(ControllerBase):
     ...

docs/overview/custom_decorators.md

@@ -401,19 +401,19 @@ The `version` decorator takes a list of values as an argument, for example `@ver
 This indicates that the `get_item_v2_v3` route function will handle version 2 and version 3 requests of the /create endpoint. 
 This allows for multiple versions of the same endpoint to be handled by different route functions, each with their own logic and implementation.
 
-### **GUARDS**
-**@Guards()**  is a decorator that applies a protection class of type `GuardCanActivate` to a route function. 
+### **UseGuards**
+**@UseGuards()**  is a decorator that applies a protection class of type `GuardCanActivate` to a route function. 
 These protection classes have a `can_execute` function that is called to determine whether a route function should be executed. 
 
 This decorator allows you to apply certain conditions or checks before a route function is executed, such as `authentication` or `authorization` checks. 
 This can help to ensure that only authorized users can access certain resources. 
 
 More information on how to use this decorator can be found in the [Guard Documentation]()
 
-A quick example on how to use `Guards` decorator:
+A quick example on how to use `UseGuards` decorator:
 ```python
 import typing as t
-from ellar.common import get, Guards
+from ellar.common import get, UseGuards
 from ellar.core import APIKeyQuery, HTTPConnection
 
 
@@ -425,11 +425,11 @@ class MyAPIKeyQuery(APIKeyQuery):
 
 
 @get("/")
-@Guards(MyAPIKeyQuery(), )
+@UseGuards(MyAPIKeyQuery(), )
 async def get_guarded_items(self):
     return {'message': 'worked fine with `key`=`supersecret`'}
 ```
-The `Guards` decorator, like the `version` decorator, takes a list of values as an argument. 
+The `UseGuards` decorator, like the `version` decorator, takes a list of values as an argument. 
 During a request, the provided guards are called in the order in which they are provided. 
 
 This allows you to apply multiple guards to a single route function and have them executed in a specific order. 

docs/overview/guards.md

@@ -57,54 +57,54 @@ class RoleGuard(GuardCanActivate):
 
 ## **Applying guards**
 Guards can be **`controller-scoped`**, **`method-scoped`**, or **`global-scoped`**. We apply guards to controllers or route function by using `@Guards`.
-The `@Guards` takes a single argument, or a comma-separated list of arguments of `GuardCanActivate` types or instances.
+The `@UseGuards` takes a single argument, or a comma-separated list of arguments of `GuardCanActivate` types or instances.
 
 ```python
 import typing as t
 
-def Guards(
+def UseGuards(
     *_guards: t.Type["GuardCanActivate"] | "GuardCanActivate"
 ) -> t.Callable:
     ...
 ```
 
 ### **Controller-scoped**
-We set up controller scoped guards on controller by using `@Guards` decorator. For example:
+We set up controller scoped guards on controller by using `@UseGuards` decorator. For example:
 ```python
 # project_name/cars/controllers.py
-from ellar.common import Controller, Guards
+from ellar.common import Controller, UseGuards
 from .guards import RoleGuard
 
 @Controller()
-@Guards(RoleGuard)
+@UseGuards(RoleGuard)
 class CarsController:
     ...
 
 ```
 The above example attaches the guard to every handler declared by this controller. 
-If we wish the guard to apply only to a single method, we apply the `@Guards()` decorator at the method level.
+If we wish the guard to apply only to a single method, we apply the `@UseGuards()` decorator at the method level.
 
 ### **Method-scoped**
-We can also use `@Guards()` on route-function when necessary.
+We can also use `@UseGuards()` on route-function when necessary.
 ```python
 # project_name/cars/controllers.py
-from ellar.common import Controller, Guards, get
+from ellar.common import Controller, UseGuards, get
 from .guards import RoleGuard
 
 @Controller()
-@Guards(RoleGuard)
+@UseGuards(RoleGuard)
 class CarsController:
-    @Guards(RoleGuard())
+    @UseGuards(RoleGuard())
     @get('/guarded-route')
     def guarded_route(self):
         return "Passed Guard"
 
 ```
-In the example, we decorated `guarded_route` with `@Guards(RoleGuard())` with an instance of `RoleGuard`. 
+In the example, we decorated `guarded_route` with `@UseGuards(RoleGuard())` with an instance of `RoleGuard`. 
 When request execution for `/guarded-route`, `guarded_route` guard definition will be precedence over `CarsController` guard definitions.
 
 ### **Global-scope**
-Global guards are used across the whole application, for every controller and every route function but individual controller or route function `@Guards` definition can override `global` scoped guards.
+Global guards are used across the whole application, for every controller and every route function but individual controller or route function `@UseGuards` definition can override `global` scoped guards.
 
 Global guards are applied at the `global_guards` parameter of the `AppFactory` creation level as shown below:
 ```python

docs/throttling.md

@@ -52,18 +52,18 @@ application = AppFactory.create_from_app_module(
 The above is also a valid configuration for `ThrottleModule` registration if you want to work with config.
 
 If you add the `ThrottlerGuard` to your application `global_guards`, then all the incoming requests will be throttled by default. 
-This can also be omitted in favor of `@Guards(ThrottlerGuard)`. The global guard check can be skipped using the `@skip_throttle()` decorator mentioned later.
+This can also be omitted in favor of `@UseGuards(ThrottlerGuard)`. The global guard check can be skipped using the `@skip_throttle()` decorator mentioned later.
 
-Example with `@Guards(ThrottlerGuard)`
+Example with `@UseGuards(ThrottlerGuard)`
 ```python
 # project_name/controller.py
-from ellar.common import Controller, Guards
+from ellar.common import Controller, UseGuards
 from ellar_throttler import throttle, ThrottlerGuard
 
 @Controller()
 class AppController:
 
-  @Guards(ThrottlerGuard)
+  @UseGuards(ThrottlerGuard)
   @throttle(limit=5, ttl=30)
   def normal(self):
       pass
@@ -95,12 +95,12 @@ a class that is skipped.
 
 ```python
 # project_name/controller.py
-from ellar.common import Controller, Guards
+from ellar.common import Controller, UseGuards
 from ellar_throttler import ThrottlerGuard, skip_throttle
 
 @skip_throttle()
 @Controller()
-@Guards(ThrottlerGuard)
+@UseGuards(ThrottlerGuard)
 class AppController:
 
     def do_skip(self):
@@ -193,7 +193,7 @@ class ThrottlerBehindProxyGuard(ThrottlerGuard):
 from .throttler_behind_proxy import ThrottlerBehindProxyGuard
 
 @Controller('')
-@Guards(ThrottlerBehindProxyGuard)
+@UseGuards(ThrottlerBehindProxyGuard)
 class AppController:
     pass
 ```

ellar/common/__init__.py

@@ -6,8 +6,8 @@
 from .datastructures import UploadFile
 from .decorators import (
     Controller,
-    Guards,
     Module,
+    UseGuards,
     Version,
     exception_handler,
     extra_args,
@@ -127,7 +127,7 @@
     "ModuleRouter",
     "render",
     "Module",
-    "Guards",
+    "UseGuards",
     "Param",
     "ParamTypes",
     "set_metadata",

ellar/common/decorators/__init__.py

@@ -5,7 +5,7 @@
 from .exception import exception_handler
 from .extra_args import extra_args
 from .file import file
-from .guards import Guards
+from .guards import UseGuards
 from .html import render, template_filter, template_global
 from .middleware import middleware
 from .modules import Module
@@ -17,7 +17,7 @@
     "serializer_filter",
     "Controller",
     "Version",
-    "Guards",
+    "UseGuards",
     "template_filter",
     "template_global",
     "file",

ellar/common/decorators/guards.py

@@ -8,14 +8,28 @@
     from ellar.common.models import GuardCanActivate
 
 
-def Guards(
+def UseGuards(
     *_guards: t.Union[t.Type["GuardCanActivate"], "GuardCanActivate"]
 ) -> t.Callable:
     """
     =========CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
 
-    Defines list of guards for a route function
-    :param _guards: Guard Type or Instance
+    Decorator that binds guards to the scope of the controller or method,
+    depending on its context.
+
+    When `@UseGuards` is used at the controller level, the guard will be
+    applied to every handler (method) in the controller.
+
+    When `@UseGuards` is used at the individual handler level, the guard
+    will apply only to that specific method.
+
+
+    Note:
+    Guards can also be set up globally for all controllers and routes
+    using `app.use_global_guards()`
+
+    :param _guards: A single guard instance or class, or a list of guard instances
+    or classes.
     :return:
     """
     return set_meta(GUARDS_KEY, list(_guards))

ellar/core/modules/builder.py

@@ -85,6 +85,6 @@ def build(self, namespace: t.Dict) -> None:
         for name, item in namespace.items():
             for k, func in self._actions.items():
                 if hasattr(item, k):
-                    value = getattr(item, k)
+                    value = item.__dict__.pop(k)
                     func(value)
                     self._cls.__MODULE_FIELDS__[name] = item

tests/test_decorators/test_controller.py

@@ -1,6 +1,6 @@
 import pytest
 
-from ellar.common import Controller, ControllerBase, Guards, Version, set_metadata
+from ellar.common import Controller, ControllerBase, UseGuards, Version, set_metadata
 from ellar.common.constants import (
     CONTROLLER_METADATA,
     GUARDS_KEY,
@@ -21,7 +21,7 @@
     name="test",
 )
 @Version("v1")
-@Guards()
+@UseGuards()
 class ControllerDecorationTest:
     pass