Merge pull request #231 from python-ellar/documentation_update

Documentation Updates Aug2024

Author: eadwinCode

docs/basics/application-context.md

@@ -1,22 +1,22 @@
-# **Application Context**
+# **Injector Context**
 
 In the complex web of dependencies within Ellar, 
 accessing the application instance without triggering circular import errors can be a daunting task. 
 
-To address this challenge, Ellar introduces the concept of an application context, 
+To address this challenge, Ellar introduces the concept of an injector context, 
 a powerful mechanism that facilitates smooth access to the application instance throughout various parts of the codebase.
 
-## **Understanding the Application Context**
+## **Understanding the Injector Context**
 
-The application context serves as a bridge between different components of the application, making the application object 
+The Injector context serves as a bridge between different components of the application, making the application object 
 readily available through the application Dependency Injection (DI) container. This ensures that you can access the 
 application instance without encountering import issues, whether it's during request handling, execution of CLI commands, 
 or manual invocation of the context.
 
 Two key elements of the application context are:
 
 - **current_injector**: This proxy variable refers to the current application **injector**, providing access to any service or the application instance itself.
-- **config**: A lazy loader for application configuration, which is based on the `ELLAR_CONFIG_MODULE` reference or accessed through `application.config` when the application context is active.
+- **current_config**: A lazy loader for application configuration, which is based on the `ELLAR_CONFIG_MODULE` reference or accessed through `application.config` when the application context is active.
 
 ## **Integration with Click Commands**
 
@@ -27,7 +27,7 @@ For instance, consider the following example:
 
 ```python
 import ellar_cli.click as click
-from ellar.app import current_injector
+from ellar.core import current_injector
 from ellar.di import injectable
 
 @injectable
@@ -37,7 +37,7 @@ class MyService:
 
 @click.command()
 @click.argument('name')
-@click.with_app_context
+@click.with_injector_context
 def my_command(name: str):
     my_service = current_injector.get(MyService)
     my_service.do_something()
@@ -63,8 +63,9 @@ For example, consider the following event handling setup:
 
 ```python
 from ellar.events import app_context_teardown, app_context_started
-from ellar.app import App, AppFactory, current_injector
-from ellar.threading import run_as_async
+from ellar.app import App, AppFactory
+from ellar.core import current_injector, injector_context
+from ellar.threading import run_as_sync
 
 @app_context_started.connect
 async def on_context_started():
@@ -76,9 +77,9 @@ def on_context_ended():
 
 app = AppFactory.create_app()
 
-@run_as_async
+@run_as_sync
 async def run_app_context():
-    async with app.application_context() as ctx:
+    async with injector_context(app.injector) as ctx:
         print("-----> Context is now available <------")
 
         app_instance = ctx.injector.get(App)

docs/cli/custom-commands.md

@@ -38,44 +38,42 @@ ARGUMENTS:
   --help     Show this message and exit.
 ```
 
-## **With App Context Decorator**
-The `ellar_cli.click` module includes a command decorator function called `with_app_context`. 
+## **With Injector Context Decorator**
+The `ellar_cli.click` module includes a command decorator function called `with_injector_context`. 
 This decorator ensures that a click command is executed within the application context, 
-allowing `current_injector`, and `config` to have values.
+allowing `current_injector`, and `current_config` to have values.
 
 For instance:
 
 ```python
 import ellar_cli.click as click
-from ellar.core import Config
-from ellar.app import current_injector
+from ellar.core import Config, current_injector
 
 @click.command()
 @click.argument("arg1", required=True, help="Arg1 description")
-@click.with_app_context
+@click.with_injector_context
 def command_context(arg1):
     config = current_injector.get(Config) 
     print("ALLOWED_HOSTS:", config.ALLOWED_HOSTS, ";ELLAR_CONFIG_MODULE:", config.config_module)
 
 @click.command()
 @click.argument("arg1", required=True, help="Arg1 description")
-def command_wc(arg1):
+def command_woc(arg1):
     config = current_injector.get(Config) 
     print("ALLOWED_HOSTS:", config.ALLOWED_HOSTS, ";ELLAR_CONFIG_MODULE:", config.config_module)
 ```
 
-In this example, `command_context` is wrapped with `with_app_context`, while `command_wc` is not. 
+In this example, `command_context` is wrapped with `with_injector_context`, while `command_woc` is not. 
 When executing both commands, `command_context` will run successfully, and `command_wc` will raise a RuntimeError 
 because it attempts to access a value outside the context.
 
 ## **AppContextGroup**
-`AppContextGroup` extended from `click.Group` to wrap all its commands with `with_app_context` decorator.
+`AppContextGroup` extended from `click.Group` to wrap all its commands with `with_injector_context` decorator.
 
 
 ```python
 import ellar_cli.click as click
-from ellar.core import Config
-from ellar.app import current_injector
+from ellar.core import Config, current_injector
 
 cm = click.AppContextGroup(name='cm')
 
@@ -94,37 +92,36 @@ def command_wc(arg1):
 ```
 All commands registered under `cm` will be executed under within the context of the application. 
 
-### **Disabling `with_app_context` in AppContextGroup**
+### **Disabling `with_injector_context` in AppContextGroup**
 There are some cases where you may want to execute a command under `AppContextGroup` outside application context.
-This can be done by setting `with_app_context=False` as command parameter.
+This can be done by setting `with_injector_context=False` as command parameter.
 
 ```python
 import ellar_cli.click as click
 
 cm = click.AppContextGroup(name='cm')
 
-@cm.command(with_app_context=False)
+@cm.command(with_injector_context=False)
 @click.argument("arg1", required=True, help="Arg1 description")
 def command_wc(arg1):
     # config = current_injector.get(Config) 
     print("ALLOWED_HOSTS:Unavailable;ELLAR_CONFIG_MODULE:Unavailable")
 ```
 
 ## Async Command
-The `ellar_cli.click` package provides a utility decorator function, `run_as_async`, 
+The `ellar_cli.click` package provides a utility decorator function, `run_as_sync`, 
 specifically designed to execute coroutine commands. 
 This is useful when you want to define asynchronous commands using the `click` package. 
 Here's an example:
 
 ```python
 import ellar_cli.click as click
-from ellar.core import Config
-from ellar.app import current_injector
+from ellar.core import Config,current_injector
 
 @click.command()
 @click.argument("arg1", required=True, help="Arg1 description")
-@click.with_app_context
-@click.run_as_async
+@click.with_injector_context
+@click.run_as_sync
 async def command_context(arg1):
     config = current_injector.get(Config) 
     print("ALLOWED_HOSTS:", config.ALLOWED_HOSTS, ";ELLAR_CONFIG_MODULE:", config.config_module)
@@ -148,7 +145,7 @@ def makemigrations():
     """Create DB Migration """
 
 @db.command()
-def migrate():
+async def migrate():
     """Applies Migrations"""
 ```
 
@@ -184,7 +181,7 @@ Commands:
 
 ```
 
-Having explored various methods for crafting commands and understanding the roles of `wrap_app_context` and `run_as_async` decorators, 
+Having explored various methods for crafting commands and understanding the roles of `with_injector_context` and `run_as_sync` decorators, 
 you now possess the knowledge to create diverse commands for your Ellar application. 
 
 It's crucial to keep in mind that any custom command you develop needs to be registered within a `@Module` class, which, 

docs/overview/custom_decorators.md

@@ -45,8 +45,9 @@ The **Inject[Type]** annotation is used to inject a service registered in Ellar
 
 For example:
 ```python
+from ellar.app import App
 from ellar.common import ModuleRouter, Inject
-from ellar.core import App, Config
+from ellar.core import Config
 from sqlalchemy.ext.asyncio import AsyncSession
 
 
@@ -172,7 +173,7 @@ def get_requests_case_2(
 ## **Custom Parameter Decorators**
 You can create your own route parameter decorators whenever necessary. You simply need to follow a contract, `NonParameterResolver`, and override the resolve function.
 
-The `NonParameterResolver` has two attribute, `type_annotation` and `parameter_name`, that are provided automatically when computing route function parameter dependencies.
+The `NonParameterResolver` has two attributes, `type_annotation` and `parameter_name`, that are provided automatically when computing route function parameter dependencies.
 The `type_annotation` and `parameter_name` are determined from the parameter declaration like so - `def route_function(parameter_name:type_annotation = NonParameterResolver())`.
 
 All `NonParameterResolver` receives current `IExecutionContext` during route function execution, and it must return a tuple of dict object of the resulting resolve data with `parameter_name` and list of errors if any. 
@@ -445,11 +446,13 @@ See [Ellar-CLI Custom Commands](../cli/introduction.md){target="_blank"}
 
 - `@exception_handler`: This decorator is used to register a function as an exception handler. This function will be called when an unhandled exception occurs during a request. It should take the exception instance as its only argument and return a response object.
 
-- `@middleware`: This decorator is used to register a function as a middleware. Middlewares are called for each incoming request and can be used to modify the request or response, or perform any other actions before or after the request is handled.
+- `@middleware`: This decorator is used to register a function as middleware. Middlewares are called for each incoming request and can be used to modify the request or response, or perform any other actions before or after the request is handled.
 
-- `@template_filter`: This decorator is used to register a function as a Jinja2 template filter. The function should take one or more arguments and return a modified value.
+- `@template_filter`: This decorator is used to register a function as a Jinja2 template filter. 
 
-- `@template_global`: This decorator is used to register a function as a global variable available in all Jinja2 templates. The function can be called without any arguments and should return a value.
+- `@template_global`: This decorator is used to register a function as a global variable available in all Jinja2 templates.
 
+- `@template_context`: This decorator is used to register a function as a global template context for dynamic template context processing.
+  
 These decorators can be used to define functions that will be executed at specific points in the application's lifecycle. 
 They provide a way to separate and organize the different parts of an application. See [Module Additional Configuration](modules.md#additional-module-configurations){target="_blank"} for examples on how these decorator functions are used.

docs/overview/exception_handling.md

@@ -10,8 +10,8 @@ it is intercepted by this middleware, which then automatically sends an appropri
 }
 ```
 Depending on the application's configuration and the value of `DEBUG`, the exception handling behavior differs. 
-When `config.DEBUG` is True, the exception that is raised is shown to the client for easy error debugging. 
-However, when `config.DEBUG` is False, a 500 error is returned to the client, as illustrated below:
+When `current_config.DEBUG` is True, the exception that is raised is shown to the client for easy error debugging. 
+However, when `current_config.DEBUG` is False, a 500 error is returned to the client, as illustrated below:
 
 ```json
 {
@@ -91,7 +91,8 @@ Service Unavailable
 
 
 ## **Exception Handlers**
-Exception Handlers are classes or functions that handles what response that is returned to the client for specific exception types.
+Exception Handlers are classes or functions
+that handle what response that is returned to the client for specific exception types.
 
 Here is an example of an ExceptionHandler that handles `HTTPException` in the application:
 
@@ -298,38 +299,31 @@ To make the `exception_handler_fun` work as an ExceptionHandler, you will need t
 ```python
 from starlette.responses import PlainTextResponse
 from ellar.common import IExecutionContext
-from ellar.common.exceptions import CallableExceptionHandler
+from ellar.core.exceptions import CallableExceptionHandler, as_exception_handler
 
 
-def exception_handler_fun(ctx: IExecutionContext, exc: Exception):
+@as_exception_handler
+def exception_400_handler(ctx: IExecutionContext, exc: Exception):
     return PlainTextResponse('Bad Request', status_code=400)
-
-
-exception_400_handler = CallableExceptionHandler(
-    exc_class_or_status_code=400, callable_exception_handler=exception_handler_fun
-)
 ```
 In the example above, you have created an `exception_400_handler` Exception Handler to handle HTTP exceptions with a status code of 400. 
 You can then register it as an exception handler in your configuration, as we did in the previous section:
 
-Additionally, `exception_handler_fun` can be configured to handle a custom exception type, as shown below:
+Additionally, We can create a handler to handle custom exception types, as shown below:
 
 ```python
 from starlette.responses import PlainTextResponse
 from ellar.common import IExecutionContext
-from ellar.common.exceptions import CallableExceptionHandler
+from ellar.core.exceptions import as_exception_handler
 
 
 class CustomException(Exception):
     pass
 
 
-def exception_handler_fun(ctx: IExecutionContext, exc: Exception):
+@as_exception_handler(CustomException)
+def exception_custom_handler(ctx: IExecutionContext, exc: Exception):
     return PlainTextResponse('Bad Request', status_code=400)
 
-
-exception_custom_handler = CallableExceptionHandler(
-    exc_class_or_status_code=CustomException, callable_exception_handler=exception_handler_fun
-)
 ```
 In this example, `exception_custom_handler` is configured to handle a custom exception type, CustomException.

docs/overview/guards.md

@@ -1,7 +1,8 @@
 # **Guards**
 
 A **Guard** in Ellar is a way to add **authentication** and **authorization** checks to your application. 
-It acts as a middleware and runs before executing the route handler. If the guard returns **false**, the request is rejected and the execution is stopped. 
+It acts as middleware and runs before executing the route handler. 
+If the guard returns **false**, the request is rejected and the execution is stopped. 
 
 **Guards** can be used to check for specific roles, permissions, or any other arbitrary condition. 
 They can be easily applied to individual routes or groups of routes using `@guard` decorator.

docs/overview/interceptors.md

@@ -145,4 +145,6 @@ class InterceptCustomException(EllarInterceptor):
             return {"message": str(cex)}
 ```
 
-In the above code, the `InterceptCustomException` interceptor catches any `CustomException` raised during the execution of the request/response cycle. It then modifies the response object to set the status code to 400 and returns a JSON response containing the exception message. This allows for custom handling of exceptions within the interceptor before they are propagated to the system's exception handlers.
+In the above code, the `InterceptCustomException` interceptor catches any `CustomException` raised during the execution of the request/response cycle. 
+It then modifies the response object to set the status code to 400 and returns a JSON response containing the exception message. 
+This allows for custom handling of exceptions within the interceptor before they are propagated to the system's exception handlers.