Merge pull request #54 from eadwinCode/document_updates_jan_2023

Document updates Jan 2023

Author: eadwinCode

docs/basics/execution-context.md

@@ -7,7 +7,7 @@ This allows different components of the application like **exception handlers**,
 There are two class `HostContext` and `ExecutionContext` which provides set of methods and properties for accessing and manipulating the current context of execution.
 
 
-## HostContext
+## **HostContext**
 The `HostContext` class provides a wrapper around `ASGI` app parameters (`scope`, `receive` and `send`) and provides some methods that allows you choosing the appropriate context(e.g., HTTP or WebSockets).
 
 For example, the `catch()` method of an **exception handlers** is called with an IHostContext.
@@ -44,7 +44,7 @@ class MyCustomExceptionHandler(IExceptionHandler):
 
 ```
 
-## Switching to other Contexts
+## **Switching to other Contexts**
 
 Currently, in Ellar you can only switch between `http` and `websocket` context. And each context has `get_client` method that returns context session.
 
@@ -141,7 +141,7 @@ class IWebSocketConnectionHost(ABC):
         """Returns WebSocket instance"""
 ```
 
-## ExecutionContext Class
+## **ExecutionContext Class**
 `ExecutionContext` extends `HostContext` and provides extra information like `Controller` class and controller `function` 
 that will handler the current request.
 
@@ -189,7 +189,7 @@ In this example, the `get_user` method is decorated with the `@get` decorator to
 
 Once you have access to the `ExecutionContext` object, you can use its methods and properties to access information about the current request.
 
-## Reflector and Metadata
+## **Reflector and Metadata**
 Ellar provides the ability to attach **custom metadata** to route handlers through the `@set_metadata()` decorator. 
 We can then access this metadata from within our class to make certain decisions.
 
@@ -239,3 +239,73 @@ class DogsController(ControllerBase):
 
 !!! info
     It's important to note that `ExecutionContext` becomes available when there is route handler found to handle the current request.
+
+To access the route's role(s) (custom metadata), we'll use the `Reflector` helper class, which is provided out of the box by the framework. 
+`Reflector` can be injected into a class in the normal way:
+
+```python
+# project_name/apps/dogs/guards.py
+from ellar.di import injectable
+from ellar.core import GuardCanActivate, IExecutionContext
+from ellar.services import Reflector
+
+
+@injectable()
+class RoleGuard(GuardCanActivate):
+    def __init__(self, reflector: Reflector):
+        self.reflector = reflector
+
+    async def can_activate(self, context: IExecutionContext) -> bool:
+        roles = self.reflector.get('roles', context.get_handler())
+        # request = context.switch_to_http_connection().get_request()
+        # check if user in request object has role
+        return 'user' in roles
+```
+
+Next, we apply the `RoleGuard` to `DogsController`
+
+```python
+# project_name/apps/dogs/controllers.py
+import typing
+from ellar.common import Body, Controller, post, set_metadata
+from ellar.core import ControllerBase
+from .schemas import CreateDogSerializer, DogListFilter
+from .guards import RoleGuard
+
+def roles(*_roles: str) -> typing.Callable:
+    return set_metadata('roles', list(_roles))
+
+
+@Controller('/dogs', guards=[RoleGuard, ])
+class DogsController(ControllerBase):
+    @post()
+    @roles('admin', 'is_staff')
+    async def create(self, payload: CreateDogSerializer = Body()):
+        result = payload.dict()
+        result.update(message='This action adds a new dog')
+        return result
+```
+
+Also, since `RoleGuard` depends on `Reflector`, it has to be registered as a provider. And we do that in `DogsModule`:
+
+```python
+# project_name/apps/dogs/module.py
+
+from ellar.common import Module
+from ellar.core import ModuleBase
+from ellar.di import Container
+
+from .controllers import DogsController
+from .guards import RoleGuard
+
+
+@Module(
+    controllers=[DogsController],
+    providers=[RoleGuard],
+)
+class DogsModule(ModuleBase):
+    def register_providers(self, container: Container) -> None:
+        # for more complicated provider registrations
+        # container.register_instance(...)
+        pass
+```

docs/img/math_router.png

@@ -0,0 +1,134 @@
+# Module Router
+
+ModuleRouter allows you to define your route handlers as standalone functions, providing an alternative to using classes. 
+This can be beneficial for python developers who prefer using functions. 
+It is important to note that using ModuleRouter does not limit your access to other features provided by Ellar.
+
+## **Usage**
+The Ellar CLI tool generates a `routers.py` file in every `create-module` scaffold command. 
+This file contains a quick guide on how to use the `ModuleRouter` class.
+
+Let's use the **routers.py** created in our previous project. And create **two** route functions, **addition** and **subtraction** 
+
+```python
+# project_name/apps/dogs/routers.py
+"""
+Define endpoints routes in python function fashion
+example:
+
+my_router = ModuleRouter("/cats", tag="Cats", description="Cats Resource description")
+
+@my_router.get('/')
+def index(request: Request):
+    return {'detail': 'Welcome to Cats Resource'}
+"""
+from ellar.common import ModuleRouter
+
+math_router = ModuleRouter('/math', tag='Math')
+
+@math_router.get('/add')
+def addition(a:int, b:int):
+    return a + b
+
+
+@math_router.get('/subtract')
+def subtraction(a:int, b:int):
+    return a - b
+```
+In the example above, we created `math_router` with a prefix `/math` and a OPENAPI tag 'math'. Then we added two routes `addition(a:int, b:int)` and `subtraction(a:int, b:int)`. 
+Each route takes two query parameters, 'a' and 'b' which are declared as int type. These functions handle the query parameters and return the result of the mathematical operation.
+
+Next, we have to make the `math_router` visible to the application
+
+## **Registering Module Router**
+Like controllers, ModuleRouters also need to be registered to their root module in order to be used in a web application. 
+In the example provided above, the `math_router` would be registered under the `project_name/apps/dogs/module.py` file.
+
+This registration process typically involves importing the `math_router` and then adding it to the list of `routers` in the `module.py` file. 
+This allows the router to be recognized by the application and its routes to be available to handle requests.
+
+```python
+
+from ellar.common import Module
+from ellar.core import ModuleBase
+from ellar.di import Container
+
+from .controllers import DogsController
+from .routers import math_router
+
+
+@Module(
+    controllers=[DogsController],
+    providers=[],
+    routers=[math_router],
+)
+class DogsModule(ModuleBase):
+    def register_providers(self, container: Container) -> None:
+        # for more complicated provider registrations
+        # container.register_instance(...)
+        pass
+```
+
+![math_router.png](../img/math_router.png)
+
+
+## **Accessing Other Request Object**
+In functional route handle, we can access request object and response object through custom decorators or type annotation as shown below.
+
+### By Type Annotation
+Let's inject request and response object in `addition` route handler function from our previous example
+
+```python
+from ellar.core import Request, Response
+from ellar.common import ModuleRouter
+
+
+math_router = ModuleRouter('/math', tag='Math')
+
+@math_router.get('/add')
+def addition(request: Request, res: Response, a:int, b:int):
+    res.headers['x-operation'] = 'Addition'
+    return dict(is_request_object=isinstance(request, Request), is_response_object=isinstance(res, Response), operation_result=a + b)
+
+```
+
+### **By Custom decorators**
+You can also achieve the same result by using custom decorator.
+
+```python
+from ellar.core import Request, Response
+from ellar.common import ModuleRouter, Req, Res
+
+
+math_router = ModuleRouter('/math', tag='Math')
+
+@math_router.get('/add')
+def addition(*, request=Req(), res=Res(), a:int, b:int):
+    res.headers['x-operation'] = 'Addition'
+    return dict(is_request_object=isinstance(request, Request), is_response_object=isinstance(res, Response), operation_result=a + b)
+
+```
+
+![math_router_with_request_object.png](../img/math_router_with_request_object.png)
+
+## **Inject Services**
+We can also inject service providers just like controller routes using the `Provide` function.
+
+```python
+from ellar.core import Request, Response, IExecutionContext
+from ellar.common import ModuleRouter, Provide
+
+
+math_router = ModuleRouter('/math', tag='Math')
+
+@math_router.get('/subtract')
+def subtraction(a:int, b:int, res=Provide(Response), req=Provide(Request), ctx=Provide(IExecutionContext)):
+    res.headers['x-operation'] = 'Subtraction'
+    return dict(
+        is_request_object=isinstance(req, Request), 
+        is_response_object=isinstance(res, Response),
+        is_context_object=isinstance(ctx, IExecutionContext),
+        operation_result=a - b
+    )
+
+```

docs/img/math_router_with_request_object.png

@@ -0,0 +1,86 @@
+A static file is a type of file that does not change often and is not generated by a server-side script. Examples of static files include images, CSS and JavaScript files, audio and video files, and other types of media.
+
+Static files in Ellar are served using the `StaticFiles` ASGI class, which is an extension of the Starlette `StaticFiles` ASGI class. 
+This class uses the static files specified in the application's **modules** and **configuration**.
+
+In addition, Ellar creates a route that mounts the static server at the `/static` path. 
+The path can be modified by providing a new value for the `STATIC_MOUNT_PATH` configuration variable.
+
+## **Configuring static files**
+
+1. In your config file, define `STATIC_MOUNT_PATH`, for example:
+    ```python
+    
+   class Config:
+        STATIC_MOUNT_PATH = '/static'
+    ```
+
+2. Store your static files in a folder called **static** in your module. For example **my_module/static/my_module/example.jpg**.
+3. In your templates, use the `url_for` with `static` and `path` parameter to build the URL for the given relative path using the configured in `STATIC_DIRECTORIES`, `STATIC_FOLDER_PACKAGES` or Module.
+   ```html
+    <img src="{{url_for('static', path='my_module/example.jpg')}}" alt="My image">
+   ```
+   OR, visit `/static/my_app/example.jpg`
+
+
+## **Static File in Modules**
+
+Managing multiple sets of static files in larger projects can be challenging, 
+but by organizing each set of static files within a specific module, 
+it becomes easier to manage and maintain. 
+This approach allows for clear organization and separation of static assets, 
+making it more manageable in a large project.
+
+In our previous project, within the `dogs` module folder, we can create a following directories, `my_static/dogs`. 
+Inside this folder `my_static/dogs`, we can create a file named `example.txt`. 
+This allows us to keep all of the static files related to the dogs module organized in one location `my_static`.
+
+Next, we tell `DogModule` about our static folder.
+
+```python
+# project_name/apps/dogs/module.py
+
+from ellar.common import Module
+from ellar.core import ModuleBase
+from ellar.di import Container
+
+from .controllers import DogsController
+
+
+@Module(
+    controllers=[DogsController], static_folder='my_static'
+)
+class DogsModule(ModuleBase):
+    def register_providers(self, container: Container) -> None:
+        # for more complicated provider registrations
+        # container.register_instance(...)
+        pass
+```
+
+## **Other Static Configurations**
+In addition to setting static directories within modules, 
+it is also possible to manually specify additional static directories that are not located within a module by using the 
+`STATIC_FOLDER_PACKAGES` and `STATIC_DIRECTORIES` variables in the application's configuration. 
+These variables allow for even more flexibility in organizing and managing static files in a project. 
+These directories will be served by the StaticFiles ASGI class along with the module-scoped static files.
+
+### `STATIC_DIRECTORIES`
+`STATIC_DIRECTORIES` variable is a list of directories within the project that contain static files. 
+These directories are not necessarily scoped to a specific module and can be used to serve static files from any location within the project. 
+These directories can be added to the `STATIC_DIRECTORIES` list in the application's configuration.
+
+```python
+STATIC_DIRECTORIES =  ['project_name/static-files', 'project_name/path/to/static/files']
+```
+
+### `STATIC_FOLDER_PACKAGES`
+`STATIC_FOLDER_PACKAGES` variable is a list of tuples that contain python packages that hold some static files. 
+These packages should have a `static` folder and the **package name** should be passed as tuple `(package_name, package_path)`, 
+**package_path** is the relative path of static folder.
+
+```python
+
+STATIC_FOLDER_PACKAGES =  [('bootstrap', 'statics'), ('package-name', 'path/to/static/directory')]
+```
+
+Static files will respond with "404 Not found" or "405 Method not allowed" responses for requests which do not match. In `HTML` mode if `404.html` file exists it will be shown as 404 response.