Merge pull request #91 from eadwinCode/background_tasks

Background Task Feature

Author: eadwinCode

docs/background-task.md

@@ -1 +1,52 @@
-## Coming Soon
+# **Background Tasks**
+
+Background tasks are tasks attached to a response and processed after a response has been sent to the client. An example of 
+this kind of task could be email notifications sent after performing an action.
+
+## **Adding BackgroundTask**
+In Ellar, you can access the **response** object and set a `background` parameter.
+```python
+from starlette.background import BackgroundTask
+from ellar.common import ModuleRouter, get, Res
+
+router = ModuleRouter('/background-test')
+
+async def send_welcome_email(email):
+    print(f'Send Welcome Email Task Called with {email}')
+
+@router.post('/signup')
+def sign_up(username: str, password: str, email: str, res=Res()):
+    res.background = BackgroundTask(send_welcome_email, email=email)
+    return {'status': 'Signup successful'}
+```
+In above construct, we created `BackgroundTask` around `send_welcome_email` function and passed to it some `*args/**kwargs `required to invoke the wrapped function.
+After the response has been sent to the client, the background function[`send_welcome_email`] will be called and there will be a print on the server log.
+
+## **Using BackgroundTasks**
+`BackgroundTasks` is another class from Starlette useful for adding multiple background tasks to a response. 
+Unlike the previous construct, `BackgroundTasks` can be injected into your route function by type annotation.
+
+For example:
+```python
+from starlette.background import BackgroundTasks
+from ellar.common import ModuleRouter, get, Res
+
+router = ModuleRouter('/background-test')
+
+def another_background_task(parameter):
+    print(f'Another Background task called with "{parameter}"')
+    
+async def send_welcome_email(email):
+    print(f'Send Welcome Email Task Called with "{email}"')
+
+@router.post('/signup')
+def sign_up(username: str, password: str, email: str, tasks: BackgroundTasks):
+    tasks.add_task(send_welcome_email, email=email)
+    tasks.add_task(another_background_task, 'another_background_task parameter')
+    return {'status': 'Signup successful'}
+```
+
+During request response cycle, `BackgroundTasks` will be resolved made available to the route handler function.
+
+!!! hint
+    The tasks are executed in order. In case one of the tasks raises an exception, the following tasks will not get the opportunity to be executed.

docs/basics/execution-context.md

@@ -1,3 +1,4 @@
+# **Execution Context**
 Execution context refers to the current context of execution, or the environment in which a specific piece of code is running. 
 It contains information about the current request, the current response in the case of http connection, and the current state of the application.
 

docs/basics/testing.md

@@ -1,3 +1,4 @@
+# **Testing**
 Automated testing is the practice of using software tools to automatically run tests on a software application or system, 
 rather than relying on manual testing by humans. It is considered an essential part of software development as it 
 helps increase productivity, ensure quality and performance goals are met, and provide faster feedback loops to developers. 
@@ -8,7 +9,7 @@ Ellar aims to encourage the use of development best practices, including effecti
 These features include:
 
 - automatically generated default unit tests files for components testing
-- offering a util, `TestClientFactory`, that constructs an isolated module/application setup
+- offering a util, `Test` Factory class, that constructs an isolated module/application setup
 - making the Ellar dependency injection system accessible in the testing environment for convenient component mocking.
 
 Ellar is compatible with `unittest` and `pytest` testing frameworks in python but in this documentation, we will be using `pytest`.

docs/basics/versioning.md

@@ -1,3 +1,4 @@
+# **Versioning**
 Versioning allows for the existence of multiple versions of controllers or individual routes within the same application, 
 which can be useful when making changes that may break previous versions. 
 This allows developers to support older versions of the application while still making necessary updates.

docs/caching.md

@@ -1,3 +1,4 @@
+# **Caching**
 Caching refers to the process of storing frequently accessed data in a temporary storage area called a `cache`, 
 in order to speed up access to that data in the future.
 
@@ -6,7 +7,7 @@ By caching data in a faster, more local storage location, the system can quickly
 
 In Ellar, we provided several cache backends interface that interacts with different cache types to assist in cache endpoint responses or other relevant data.
 
-## Setting up the cache
+## **Setting up the cache**
 It's very simple to set up cache in Ellar but the crucial part is picking the cache type that is suitable for your application 
 because some cache type behave differently and perform better and faster than others.
 
@@ -296,7 +297,7 @@ class DevelopmentConfig(ConfigDefaultTypesMixin):
     }
 ```
 
-## Cache Arguments
+## **Cache Arguments**
 
 You can customize the behavior of each caching backend in Django by passing additional arguments when you configure the cache. The valid arguments that can be passed to each backend are as follows:
 
@@ -323,7 +324,7 @@ class DevelopmentConfig(ConfigDefaultTypesMixin):
     }
 ```
 
-## Setting up More than One Cache Backend
+## **Setting up More than One Cache Backend**
 To set up multiple cache backends in Django, you can add additional entries to the `CACHES` variable in your `config.py` file. 
 The `default` cache backend is typically defined first, followed by any additional cache backends you want to configure.
 
@@ -343,7 +344,7 @@ class DevelopmentConfig(ConfigDefaultTypesMixin):
     }
 ```
 
-## CacheService (ICacheService)
+## **CacheService (ICacheService)**
 Ellar does not provide cache backends directly, but instead offers a caching service that manages all the configured cache backends in your application. 
 The `CacheService` class serves as a wrapper for these cache backends and provides a uniform interface for interacting with them.
 
@@ -374,7 +375,7 @@ The CacheService class provides methods like:
 
 These methods are available for each of the configured cache backends and can be used interchangeably with any backend.
 
-## Injecting CacheService
+## **Injecting CacheService**
 `CacheService` is a core service registered in `EllarInjector` and can be injected as every other service.
 
 For example, lets make `CacheService` available in our route function.
@@ -411,7 +412,7 @@ For example, lets make `CacheService` available in our route function.
     ```
 
 
-## Using Cache Decorator
+## **Using Cache Decorator**
 Ellar provides a cache decorator that can be used to cache the responses of route functions. The cache decorator can be applied to a route function to automatically cache its response data for a specified amount of time.
 
 The cache decorator takes the following arguments:
@@ -425,8 +426,8 @@ The cache decorator takes the following arguments:
 We can rewrite the above example using `cache` decorator:
 === "Synchronous Route Function"
     ```python
-    from ellar.common import get, cache
-    
+    from ellar.common import get
+    from ellar.cache import cache
     ...
     @get('/cache-test')
     @cache(ttl=300, version='v1', key_prefix='project_name')
@@ -446,7 +447,7 @@ We can rewrite the above example using `cache` decorator:
         return processed_value
     ```
 
-### Adding Custom key gen function for cache Decorator
+### **Adding Custom key gen function for cache Decorator**
 By default, the `cache` decorator combines the route function's URL and the specified `key_prefix` value to generate the cache key used to store the response data. 
 However, you can customize this behavior by providing a `make_key_callback` function to the cache decorator.
 
@@ -455,7 +456,8 @@ The `make_key_callback` function takes an `ExecutionContext` instance (which con
 Here's an example of how to use a custom `make_key_callback` function with the cache decorator:
 === "Synchronous Route Function"
     ```python
-    from ellar.common import get, cache
+    from ellar.common import get
+    from ellar.cache import cache
     from ellar.core import ExecutionContext
     from ellar.common.helper import get_name
 
@@ -475,7 +477,8 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 === "Asynchronous Route Function"
 
     ```python
-    from ellar.common import get, cache
+    from ellar.common import get
+    from ellar.cache import cache
     from ellar.core import ExecutionContext
     from ellar.common.helper import get_name
 

docs/configurations.md

@@ -1,3 +1,4 @@
+# **Application Configurations**
 
 The `config.py` file contains all the configuration necessary in bootstrapping ellar application. 
 

docs/handling-response/response-model.md

@@ -135,23 +135,23 @@ Let's see different `ResponseModel` available in Ellar and how you can create on
 ### **ResponseModel** 
 Response model that manages rendering of other response types.
 
-- Location: `ellar.core.response.model.base.ResponseModel`
+- Location: `ellar.common.responses.models.ResponseModel`
 - response_type: `Response`
 - model_field_or_schema: `None`
 - media_type: `text/plain`
 
 ### **JSONResponseModel** 
 Response model that manages `JSON` response.
 
-- Location: `ellar.core.response.model.json.JSONResponseModel`
+- Location: `ellar.common.responses.models.json.JSONResponseModel`
 - response_type: `JSONResponse` OR `config.DEFAULT_JSON_CLASS`
 - model_field_or_schema: `Required`
 - media_type: `application/json`
 
 ### **HTMLResponseModel** 
 Response model that manages `HTML` templating response. see [`@render`]() decorator.
 
-- Location: `ellar.core.response.model.html.HTMLResponseModel`
+- Location: `ellar.common.responses.models.html.HTMLResponseModel`
 - response_type: `TemplateResponse`
 - model_field_or_schema: `None`
 - media_type: `text/html`
@@ -160,7 +160,7 @@ Response model that manages `HTML` templating response. see [`@render`]() decora
 ### **FileResponseModel** 
 Response model that manages `FILE` response. see [`@file`]() decorator.
 
-- Location: `ellar.core.response.model.file.FileResponseModel`
+- Location: `ellar.common.responses.models.file.FileResponseModel`
 - response_type: `FileResponse`
 - model_field_or_schema: `None`
 - media_type: `Required`
@@ -169,7 +169,7 @@ Response model that manages `FILE` response. see [`@file`]() decorator.
 ### **StreamingResponseModel** 
 Response model that manages `STREAMING` response. see [`@file`]() decorator.
 
-- Location: `ellar.core.response.model.file.StreamingResponseModel`
+- Location: `ellar.common.responses.models.file.StreamingResponseModel`
 - response_type: `StreamingResponse`
 - model_field_or_schema: `None`
 - media_type: `Required`
@@ -178,7 +178,7 @@ Response model that manages `STREAMING` response. see [`@file`]() decorator.
 ### **EmptyAPIResponseModel**
 Default `ResponseModel` applied when no response is defined.
 
-- Location: `ellar.core.response.model.html.EmptyAPIResponseModel`
+- Location: `ellar.common.responses.models.json.EmptyAPIResponseModel`
 - response_type: `JSONResponse` OR `config.DEFAULT_JSON_CLASS`
 - model_field_or_schema: `dict`
 - media_type: `application/json`

docs/mount.md

@@ -1 +1,63 @@
-## Coming Soon
+# **Mount**
+In Starlette, `Mount` is used to mount sub-routes and ASGI apps or WSGI apps. The same is applicable in Ellar.
+
+Let's see how to mount sub-routes in ellar
+```python
+
+from starlette.routing import Mount
+from ellar.common.routing import RouteOperation
+from ellar.common import Req
+
+def users(request=Req()):
+    return "List of users"
+
+def user(username: str, request=Req()):
+    return f"Users Profile of {username}"
+
+
+mount = Mount(
+    path='/users', 
+    routes=[
+        RouteOperation(path='/', endpoint=users, methods=['GET', 'POST'], response={200: str}), 
+        RouteOperation(path='/{username}', endpoint=user, methods=['GET', 'POST'], response={200: str})
+    ]
+)
+```
+In the construct above, we have created a starlette-like example of `Mount` with a base path `/users` and with two endpoints, 
+`/` to get list of users and `/username` to a users profile. 
+
+### **Mount with Ellar**
+Now, we have a `mount` instance for the previous code construct, to get it to work in ellar, we need to register it to a **Module**.
+
+For example,
+```python
+from ellar.common import Module
+from .path_to_mount import mount
+
+
+@Module(routers=[mount])
+class ApplicationModule:
+    pass
+
+```
+
+## **[Applying Middleware to Mount](https://www.starlette.io/middleware/#applying-middleware-to-mounts){target="_blank"}**
+Just like in every other ASGI app, middlewares can be added to `Mount` during its instantiation.
+
+For example,
+```python
+...
+from starlette.middleware import Middleware
+from starlette.middleware.gzip import GZipMiddleware
+
+
+mount = Mount(
+    path='/users', 
+    routes=[
+        RouteOperation(path='/', endpoint=users, methods=['GET', 'POST'], response={200: str}), 
+        RouteOperation(path='/{username}', endpoint=user, methods=['GET', 'POST'], response={200: str})
+    ],
+    middleware=[Middleware(GZipMiddleware)]
+)
+```
+Checkout this [documentation from starlette](https://www.starlette.io/middleware/#applying-middleware-to-mounts){target="_blank"} on some conditions to using `middleware` on Mount

docs/overview/controllers.md

@@ -1,4 +1,4 @@
-
+# **Controllers**
 The Controller is responsible for handling incoming requests and returning responses to the client.
 The purpose of a controller is to receive specific requests for an application `ApplicationRouter`. `ApplicationRouter` on the other hand, decides which `controller` should handle an incoming request.