Merge pull request #130 from python-ellar/route_function_parameter_annotation

Route handlers dependencies type annotation support

Author: eadwinCode

.pre-commit-config.yaml

@@ -14,14 +14,14 @@ repos:
       name: Code Formatting
       entry: "make fmt"
       types: [python]
-      language_version: python3.8
+      language_version: python3.10
       language: python
     - id: code_linting
       args: [ ]
       name: Code Linting
       entry: "make lint"
       types: [ python ]
-      language_version: python3.8
+      language_version: python3.10
       language: python
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v2.3.0

Makefile

@@ -26,7 +26,7 @@ fmt format:clean ## Run code formatters
 	black ellar tests examples
 	ruff check --fix ellar tests examples
 
-test: ## Run tests
+test:clean ## Run tests
 	pytest
 
 test-cov: ## Run tests with coverage

docs/basics/dynamic-modules.md

@@ -141,4 +141,4 @@ When `AppFactory` starts module bootstrapping, `my_module_configuration_factory`
 all the required **parameters** and returned a `DynamicModule` of `MyModule`.
 
 For more example, checkout [Ellar Throttle Module](https://github.com/eadwinCode/ellar-throttler/blob/master/ellar_throttler/module.py){target="_blank"}
-or [Ellar Cache Module](../../techniques/caching){target="_blank"}
+or [Ellar Cache Module](../techniques/caching.md){target="_blank"}

docs/basics/execution-context.md

@@ -164,18 +164,18 @@ class ExecutionContext(HostContext):
 These extra information are necessary for reading `metadata` properties set on controllers or the route handler function.
 
 ### **How to access the current execution context**
-You can access the current execution context using the `Context()` function. 
+You can access the current execution context using the `Inject[ExecutionContext]` annotation. 
 This decorator can be applied to a parameter of a controller or service method, 
 and it will inject the current `ExecutionContext` object into the method.
 
 For example, consider the following controller method:
 ```python
-from ellar.common import Context, get, Controller
+from ellar.common import get, Controller, IExecutionContext, Inject
 
 @Controller('/users')
 class UserController:
     @get('/{user_id}')
-    async def get_user(self, user_id: str, ctx=Context()):
+    async def get_user(self, user_id: str, ctx:Inject[IExecutionContext]):
         # Use the ctx object to access the current execution context
         res = ctx.switch_to_http_connection().get_response()
         res.status_code = 200
@@ -185,7 +185,8 @@ class UserController:
 
 ```
 
-In this example, the `get_user` method is decorated with the `@get` decorator to handle a GET request to the /users/:id route. The `Context()` function is applied to the second parameter of the method, which will inject the current `ExecutionContext` object into the method.
+In this example, the `get_user` method is decorated with the `@get` decorator to handle a GET request to the /users/:id route. 
+The `Inject[ExecutionContext]` annotation is applied to the second parameter of the method, which will inject the current `ExecutionContext` object into the method.
 
 Once you have access to the `ExecutionContext` object, you can use its methods and properties to access information about the current request.
 

docs/index.md

@@ -56,7 +56,7 @@ $(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
@@ -95,7 +95,7 @@ class MotoController(ControllerBase):
         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"
 

docs/overview/controllers.md

@@ -91,19 +91,19 @@ class CarController(ControllerBase):
     ...
 ```
 
-### **injection (`parameter_name=Req()`)**
+### **injection (`parameter_name=Inject[Request]`)**
 
-We can also inject request object to any handler by using `@Req` decorator in handler signature.
+We can also inject request object to any handler by using `Inject[Request]` decorator in handler signature.
 ```python
 # project_name/apps/car/controllers.py
 
-from ellar.common import Controller, ControllerBase, get, Req
+from ellar.common import Controller, ControllerBase, get, Inject
 from ellar.core import Request
 
 @Controller('/car')
 class CarController(ControllerBase):
     @get()
-    def get_all(self, req_data: Request, req_data_2=Req()):
+    def get_all(self, req_data: Request, req_data_2: Inject[Request]):
         assert isinstance(req_data, Request) # True
         assert isinstance(req_data_2, Request)
         assert req_data == req_data_2
@@ -131,21 +131,21 @@ class CarController(ControllerBase):
 
 Other request `handler` signature injectors
 
-|             |                                                                                                        |
-|-------------|--------------------------------------------------------------------------------------------------------|
-| `Req()`     | for `Request` object                                                                                   |
-| `Res()`     | for `Response` object                                                                                  |
-| `Path()`    | pydantic field - resolves path parameters                                                              |
-| `Body()`    | pydantic field - resolves required Request `body` parameters                                           |
-| `Form()`    | pydantic field - resolves required Request `body` parameters with content-type=`x-www-form-urlencoded` |
-| `Header()`  | pydantic field - resolves required Request `header` parameters                                         |
-| `Query()`   | pydantic field - resolves required Request `query` parameters                                          |
-| `File()`    | pydantic field - resolves required Request `body` parameters with content-type=`x-www-form-urlencoded` |
-| `Ctx()`     | Injects `ExecutionContext`.                                                                            |
-| `Cookie()`  | pydantic field - resolves required Request `cookie` parameters                                         |
-| `Session()` | injects Request session data                                                                           |
-| `Host()`    | injects Request clients host                                                                           |
-| `Provide()` | injects services                                                                                       |
+|                                       |                                                                                                        |
+|---------------------------------------|--------------------------------------------------------------------------------------------------------|
+| `Inject[Request]`                     | for `Request` object                                                                                   |
+| `Inject[Response]`                    | for `Response` object                                                                                  |
+| `Path()`                              | pydantic field - resolves path parameters                                                              |
+| `Body()`                              | pydantic field - resolves required Request `body` parameters                                           |
+| `Form()`                              | pydantic field - resolves required Request `body` parameters with content-type=`x-www-form-urlencoded` |
+| `Header()`                            | pydantic field - resolves required Request `header` parameters                                         |
+| `Query()`                             | pydantic field - resolves required Request `query` parameters                                          |
+| `File()`                              | pydantic field - resolves required Request `body` parameters with content-type=`x-www-form-urlencoded` |
+| `Inject[ExecutionContext]`            | Injects `ExecutionContext`.                                                                            |
+| `Cookie()`                            | pydantic field - resolves required Request `cookie` parameters                                         |
+| `Inject[dict, Inject.Key('Session')]` | injects Request session data                                                                           |
+| `Inject[str, Inject.Key('Host')]`     | injects Request clients host                                                                           |
+| `Inject[Type]`                        | injects services                                                                                       |
 
 ## **Resource**
 
@@ -244,7 +244,7 @@ from .schemas import CreateCarSerializer
 
 
 @post()
-async def create(self, payload: CreateCarSerializer = Body()):
+async def create(self, payload: Body[CreateCarSerializer]):
     return 'This action adds a new car'
 ```
 
@@ -271,13 +271,13 @@ from .schemas import CreateCarSerializer, CarListFilter
 @Controller('/car')
 class CarController(ControllerBase):
     @post()
-    async def create(self, payload: CreateCarSerializer = Body()):
+    async def create(self, payload:Body[CreateCarSerializer]):
         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
@@ -291,7 +291,7 @@ class CarController(ControllerBase):
         return f"This action removes a #{car_id} car"
 
     @get()
-    async def get_all(self, query: CarListFilter = Query()):
+    async def get_all(self, query:Query[CarListFilter]):
         assert isinstance(self.context.switch_to_http_connection().get_request(), Request)  # True
         return f'This action returns all cars at limit={query.limit}, offset={query.offset}'