Documentation Updates

Author: eadwinCode

docs/cli/custom-commands.md

@@ -39,43 +39,41 @@ ARGUMENTS:
 ```
 
 ## **With App Context Decorator**
-The `ellar_cli.click` module includes a command decorator function called `with_app_context`. 
+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.
 
 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

@@ -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.

docs/overview/modules.md

@@ -48,6 +48,7 @@ from ellar.core import ModuleBase
     modules=[], 
     providers=[],
     controllers=[],
+    exports=[],
     routers=[],
     commands=[],
     base_directory=None, 
@@ -63,6 +64,7 @@ class BookModule(ModuleBase):
 | `name`            | The name of the module. It's relevant for identification purposes.                                                      |
 | `modules`         | A list of dependencies required by this module.                                                                         |
 | `providers`       | Providers to be instantiated by the Ellar injector, possibly shared across this module.                                 |
+| `exports`         | List of services accessible at application scope level.                                                                 |
 | `controllers`     | Controllers defined in this module that need instantiation.                                                             |
 | `routers`         | ModuleRouters defined in this module.                                                                                   |
 | `commands`        | Functions decorated with `EllarTyper` or `command` that serve as commands.                                              |
@@ -76,19 +78,19 @@ class BookModule(ModuleBase):
 The Ellar framework offers additional module configurations to handle various aspects of the application lifecycle and behavior.
 
 ### Module Events
-Modules can define `before_init` class method to configure additional initialization parameters before instantiation. This method receives the current application config as a parameter, allowing for further customization.
+Modules can define `post_build` class method
+can be used to define additional `Module` properties after `Module` has built successfully.
 
 ```python linenums="1"
-import typing
 from ellar.common import Module
-from ellar.core import ModuleBase, Config
+from ellar.core.modules import ModuleBase, ModuleRefBase
 
 
 @Module()
 class ModuleEventSample(ModuleBase):
     @classmethod
-    def before_init(cls, config: Config) -> typing.Any:
-        """Called before creating Module object"""
+    def post_build(cls, module_ref: ModuleRefBase) -> None:
+        """Executed after a module build process is done"""
 ```
 
 ### Module Application Cycle
@@ -127,7 +129,7 @@ from ellar.core import ModuleBase
 @Module()
 class ModuleExceptionSample(ModuleBase):
     @exception_handler(404)
-    def exception_404_handler(cls, context: IHostContext, exc: Exception) -> Response:
+    def exception_404_handler(self, context: IHostContext, exc: Exception) -> Response:
         return JSONResponse(dict(detail="Resource not found."))
 ```
 
@@ -141,15 +143,15 @@ from ellar.core import ModuleBase
 @Module()
 class ModuleTemplateFilterSample(ModuleBase):
     @template_filter()
-    def double_filter(cls, n):
+    def double_filter(self, n):
         return n * 2
 
     @template_global()
-    def double_global(cls, n):
+    def double_global(self, n):
         return n * 2
 
     @template_filter(name="dec_filter")
-    def double_filter_dec(cls, n):
+    def double_filter_dec(self, n):
         return n * 2
 ```
 
@@ -198,20 +200,20 @@ from ellar.core import ModuleBase
 @Module()
 class ModuleMiddlewareSample(ModuleBase):
     @middleware()
-    async def my_middleware_function_1(cls, context: IHostContext, call_next):
+    async def my_middleware_function_1(self, context: IHostContext, call_next):
         request = context.switch_to_http_connection().get_request() # for HTTP response only
         request.state.my_middleware_function_1 = True
         await call_next()
 
     @middleware()
-    async def my_middleware_function_2(cls, context: IHostContext, call_next):
+    async def my_middleware_function_2(self, context: IHostContext, call_next):
         if context.get_type() == 'websocket':
             websocket = context.switch_to_websocket().get_client()
             websocket.state.my_middleware_function_2 = True
         await call_next()
 
     @middleware()
-    async def my_middleware_function_3(cls, context: IHostContext, call_next):
+    async def my_middleware_function_3(self, context: IHostContext, call_next):
         connection = context.switch_to_http_connection().get_client() # for HTTP response only
         if connection.headers['somekey']:
             # response = context.get_response() -> use the `response` to add extra definitions to things you want to see on

docs/overview/providers.md

@@ -220,7 +220,7 @@ a_foo_instance = AFooClass()
 @Module()
 class AModule(ModuleBase):
     def register_services(self, container: Container) -> None:
-        container.register_singleton(IFoo, AFooClass)
+        container.register(IFoo, AFooClass)
         container.register(IFooB, a_foo_instance)
 
 
@@ -281,7 +281,7 @@ Also, services can be injected as a dependency by using tags. To achieve this, t
 For example:
 
 ```python
-from ellar.di import EllarInjector, InjectByTag
+from ellar.di import EllarInjector, InjectByTag, scopes
 
 injector = EllarInjector(auto_bind=False)
 
@@ -294,7 +294,7 @@ class FooB:
     def __init__(self, foo: InjectByTag("fooTag")):
         self.foo = foo
 
-injector.container.register_singleton(Foo, tag="fooTag")
+injector.container.register(Foo, tag="fooTag", scope=scopes.singleton_scope)
 injector.container.register(FooB)
 
 assert injector.get(FooB).foo == 'foo'

docs/overview/step-one.md

@@ -127,10 +127,6 @@ The result of this CLI command is stored in `project-name/project_name/apps`
 ```
 apps/
 ├─ car/
-│  ├─ tests/
-│  │  ├─ test_controllers.py
-│  │  ├─ test_routers.py
-│  │  ├─ test_services.py
 │  ├─ controllers.py
 │  ├─ module.py
 │  ├─ schemas.py
@@ -145,7 +141,6 @@ Brief overview of the generated files:
 | `car.module.py`   | car module/app `Module` metadata definition.      |
 | `car.services.py` | For Car module service declarations.              |
 | `car.schemas.py`  | Data-transfer-object or Serializers declarations. |
-| `car.tests/`      | testing directory for the car module.             |
 
 To finish up with the created `car` module, we need to register it to the 
 `project_name.root_module.py`
@@ -179,7 +174,7 @@ then add the below.
 
 import os
 from ellar.common.constants import ELLAR_CONFIG_MODULE
-from ellar.core.factory import AppFactory
+from ellar.app import AppFactory
 from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerUI
 from .root_module import ApplicationModule
 
@@ -197,12 +192,12 @@ document_builder.set_title('Project Name API') \
     .set_license('MIT Licence', url='https://www.google.com')
 
 document = document_builder.build_document(application)
-module_config = OpenAPIDocumentModule.setup(
+OpenAPIDocumentModule.setup(
+    app=application,
     docs_ui=SwaggerUI(),
     document=document,
     guards=[]
 )
-application.install_module(module_config)
 ```
 
 Goto your browser and visit: [http://localhost:8000/docs/](http://localhost:8000/docs){target="_blank"}