Merge pull request #100 from eadwinCode/ellar_life_span_wrapper

Extended Lifespan to Module classes

Author: eadwinCode

docs/basics/custom-providers.md

@@ -0,0 +1,144 @@
+# **Dynamic Modules**
+We have seen in many example given on how to statically configure a [module](../../overview/modules.md){_target='blank}. 
+In this section we are going to look at different ways to dynamically set up a module.
+
+Why is this important? Consider a scenario where a general-purpose module needs to behave differently in different use cases, 
+it may be useful to use a configuration-based approach to allow customization. This is similar to the concept of a "plugin" in many systems, 
+where a generic facility requires some configuration before it can be used by a consumer.
+
+## **Module Dynamic Setup**
+
+To dynamically configure a module, the module should inherit from `IModuleSetup` and provide a `setup` method or `setup_register` method
+that performs the necessary actions for setting up the module and then returns a `DynamicModule` or `ModuleSetup` instance.
+
+```python
+import typing as t
+from ellar.core.modules import DynamicModule, ModuleSetup
+
+class IModuleSetup:
+    """Modules that must have a custom setup should inherit from IModuleSetup"""
+
+    @classmethod
+    def setup(cls, *args: t.Any, **kwargs: t.Any) -> DynamicModule:
+        pass
+    
+    @classmethod
+    def register_setup(cls, *args: t.Any, **kwargs: t.Any) -> ModuleSetup:
+        pass
+
+```
+
+Note that `setup` method returns a `DynamicModule` instance, while `register_setup` method returns a `ModuleSetup` instance. 
+The `DynamicModule` instance is used when the module requires some configuration before it can be used by a consumer, 
+while the `ModuleSetup` instance is used when the module does not require any additional configuration outside the ones provided in the application config.
+
+## **DynamicModule**
+`DynamicModule` is a dataclass type that is used **override** `Module` decorated attributes at easy without having to modify the module code directly. 
+In other words, it gives you the flexibility to reconfigure module.
+
+For example: Lets look at the code below:
+```python
+from ellar.common import Module
+from ellar.core import DynamicModule
+from ellar.di import ProviderConfig
+
+@Module(providers=[ServiceA, ServiceB])
+class ModuleA:
+    pass
+
+# we can reconfigure ModuleA dynamically using `DynamicModule` as shown below
+
+@Module(
+    modules=[
+        DynamicModule(
+            ModuleA, 
+            providers=[
+                ProviderConfig(ServiceA, use_class=str),
+                ProviderConfig(ServiceB, use_class=dict),
+            ]
+        )
+    ]
+)
+class ApplicationModule:
+    pass
+```
+`ModuleA` has been defined with some arbitrary providers (`ServiceA` and `ServiceB`), but during registration of `ModuleA` in `ApplicationModule`,
+we used `DynamicModule` to **override** its Module attribute `providers` with a new set of data.
+
+
+## **ModuleSetup**
+ModuleSetup is a dataclass type that used to set up a module based on its dependencies. 
+It allows you to define the module **dependencies** and allow a **callback factory** function for a module dynamic set up.
+
+**`ModuleSetup` Properties**:
+
+- **`module`:** a required property that defines the type of module to be configured. The value must be a subclass of ModuleBase or IModuleSetup.
+- **`inject`:** a sequence property that holds the types to be injected to the factory method. The order of the types will determine the order at which they are injected.
+- **`factory`:** a factory function used to configure the module and take `Module` type as first argument and other services as listed in `inject` attribute.
+
+Let's look this `ModuleSetup` example code below with our focus on how we eventually configured `DynamicService` type, 
+how we used `my_module_configuration_factory` to dynamically build `MyModule` module.
+
+```python
+import typing as t
+from ellar.common import Module, IModuleSetup
+from ellar.di import ProviderConfig
+from ellar.core import DynamicModule, ModuleBase, Config, ModuleSetup, AppFactory
+
+
+class Foo:
+    def __init__(self):
+        self.foo = 'foo'
+
+
+class DynamicService:
+    def __init__(self, param1: t.Any, param2: t.Any, foo: str):
+        self.param1 = param1
+        self.param2 = param2
+        self.foo = foo
+
+
+@Module()
+class MyModule(ModuleBase, IModuleSetup):
+    @classmethod
+    def setup(cls, param1: t.Any, param2: t.Any, foo: Foo) -> DynamicModule:
+        return DynamicModule(
+            cls,
+            providers=[ProviderConfig(DynamicService, use_value=DynamicService(param1, param2, foo.foo))],
+        )
+
+
+def my_module_configuration_factory(module: t.Type[MyModule], config: Config, foo: Foo):
+    return module.setup(param1=config.param1, param2=config.param2, foo=foo)
+
+
+@Module(modules=[ModuleSetup(MyModule, inject=[Config, Foo], factory=my_module_configuration_factory),], providers=[Foo])
+class ApplicationModule(ModuleBase):
+    pass
+
+
+app = AppFactory.create_from_app_module(ApplicationModule, config_module=dict(
+    param1="param1",
+    param2="param2",
+))
+
+dynamic_service = app.injector.get(DynamicService)
+assert dynamic_service.param1 == "param1"
+assert dynamic_service.param2 == "param2"
+assert dynamic_service.foo == "foo"
+```
+In the example, we started by defining a service `DynamicService`, whose parameter depended on some values from application config
+and from another service `Foo`. We then set up a `MyModule` and used as **setup** method which takes all parameter needed by 
+`DynamicService` after that, we created `DynamicService` as a singleton and registered as a provider in `MyModule` 
+for it to be accessible and injectable. 
+
+At this point, looking at the setup function of `MyModule`, its clear `MyModule` depends on `Config` and `Foo` service. And this is where `ModuleSetup` usefulness comes in.
+
+During registration in `ApplicationModule`, we wrapped `MyModule` around a `ModuleSetup` and stated its dependencies in the `inject` property and also
+provided a `my_module_configuration_factory` factory that takes in module dependencies and return a `DynamicModule` configuration of `MyModule`.  
+
+When `AppFactory` starts module bootstrapping, `my_module_configuration_factory` will be called with 
+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"}

docs/basics/dynamic-modules.md

@@ -163,7 +163,7 @@ 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
+### **How to access the current execution context**
 You can access the current execution context using the `Context()` function. 
 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.

docs/basics/events.md

@@ -0,0 +1,104 @@
+# **Injector Scopes**
+There are 3 different scopes which defines ways a service/provider is instantiated.
+
+- [TRANSIENT SCOPE](#transientscope-)
+- [SINGLETON SCOPE](#singletonscope-)
+- [REQUEST SCOPE](#requestscope-)
+
+## **`transient_scope`**: 
+Whenever a transient scoped provider is required, a new instance of the provider is created
+
+```python
+# main.py
+
+from ellar.di import EllarInjector, transient_scope, injectable
+
+injector = EllarInjector(auto_bind=False)
+
+
+@injectable(scope=transient_scope)
+class ATransientClass:
+    pass
+
+injector.container.register(ATransientClass)
+# OR
+# injector.container.register_transient(ATransientClass)
+
+def validate_transient_scope():
+    a_transient_instance_1 = injector.get(ATransientClass)
+    a_transient_instance_2 = injector.get(ATransientClass)
+    
+    assert a_transient_instance_2 != a_transient_instance_1 # True
+
+    
+if __name__ == "__main__":
+    validate_transient_scope()
+```
+
+## **`singleton_scope`**: 
+A singleton scoped provider is created once throughout the lifespan of the Container instance.
+
+For example:
+```python
+# main.py
+
+from ellar.di import EllarInjector, singleton_scope, injectable
+
+injector = EllarInjector(auto_bind=False)
+# OR
+
+@injectable(scope=singleton_scope)
+class ASingletonClass:
+    pass
+
+injector.container.register(ASingletonClass)
+# OR
+# injector.container.register_singleton(ASingletonClass)
+
+def validate_singleton_scope():
+    a_singleton_instance_1 = injector.get(ASingletonClass)
+    a_singleton_instance_2 = injector.get(ASingletonClass)
+
+    assert a_singleton_instance_2 == a_singleton_instance_1 # True
+
+if __name__ == "__main__":
+    validate_singleton_scope()
+```
+
+## **`request_scope`**: 
+A request scoped provider is instantiated once during the scope of the request. And it's destroyed once the request is complete.
+It is important to note that `request_scope` behaves like a `singleton_scope` during HTTPConnection mode and behaves like a `transient_scope` outside HTTPConnection mode.
+
+```python
+# main.py
+
+import uvicorn
+from ellar.di import EllarInjector, request_scope, injectable
+
+injector = EllarInjector(auto_bind=False)
+
+
+@injectable(scope=request_scope)
+class ARequestScopeClass:
+    pass
+
+
+injector.container.register(ARequestScopeClass)
+
+
+async def scoped_request(scope, receive, send):
+    async with injector.create_asgi_args(scope, receive, send) as request_injector:
+        request_instance_1 = request_injector.get(ARequestScopeClass)
+        request_instance_2 = request_injector.get(ARequestScopeClass)
+        assert request_instance_2 == request_instance_1
+
+    request_instance_1 = injector.get(ARequestScopeClass)
+    request_instance_2 = injector.get(ARequestScopeClass)
+
+    assert request_instance_2 != request_instance_1
+
+
+if __name__ == "__main__":
+    uvicorn.run("main:scoped_request", port=5000, log_level="info")
+
+```

docs/basics/execution-context.md

@@ -0,0 +1,108 @@
+# **Lifespan**
+Ellar applications registers a lifespan manager. The manager handles lifespan handler registered in the configuration under the variable name
+**`DEFAULT_LIFESPAN_HANDLER`**. 
+
+It also executes code that needs to run before the application starts up, or when the application is shutting down. 
+The lifespan manager must be run before ellar starts serving incoming request.
+
+```python
+import uvicorn
+import contextlib
+from ellar.core import App, AppFactory
+
+@contextlib.asynccontextmanager
+async def some_async_resource():
+    print("running some-async-resource function")
+    yield 
+    print("existing some-async-resource function")
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app: App):
+    async with some_async_resource():
+        print("Run at startup!")
+        yield
+        print("Run on shutdown!")
+
+
+application = AppFactory.create_app(config_module=dict(
+    DEFAULT_LIFESPAN_HANDLER=lifespan
+))
+
+if __name__ == "__main__":
+    uvicorn.run(application, port=5000, log_level="info")
+```
+The construct above will generate the output below:
+```shell
+INFO:     Started server process [11772]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:5000 (Press CTRL+C to quit)
+
+running some-async-resource function
+Run at startup!
+
+INFO:     Shutting down
+INFO:     Waiting for application shutdown.
+INFO:     Application shutdown complete.
+INFO:     Finished server process [11772]
+
+Run on shutdown!
+existing some-async-resource function
+```
+
+## **Modules and Lifespan**
+Any module that wants to engage in application lifespan must inherit `IApplicationStartup` for startup actions or `IApplicationShutdown` for shutdown actions 
+or inherit both for startup and shutdown actions. 
+
+`IApplicationStartup` has an abstractmethod `on_startup` function and `IApplicationShutdown` has an abstractmethod `on_shutdown` function.
+
+```python
+from abc import abstractmethod
+
+
+class IApplicationStartup:
+    @abstractmethod
+    async def on_startup(self, app: "App") -> None:
+        ...
+
+
+class IApplicationShutdown:
+    @abstractmethod
+    async def on_shutdown(self) -> None:
+        ...
+```
+Let's assume we have a module that extends both `IApplicationStartup` and `IApplicationShutdown` to execute some actions on startup and on shutdown as shown below:
+
+```python
+from ellar.common import IApplicationShutdown, IApplicationStartup, Module
+
+@Module()
+class SampleModule(IApplicationShutdown, IApplicationStartup):
+    
+    async def on_startup(self, app) -> None:
+        print("Run at startup! in SampleModule")
+
+    async def on_shutdown(self) -> None:
+        print("Run on shutdown! in SampleModule")
+
+```
+
+## **Running lifespan in tests**
+You should use `TestClient` as a context manager, to ensure that the lifespan is called.
+
+```python
+from ellar.testing import Test
+from .main import SampleModule
+
+test_module = Test.create_test_module(modules=[SampleModule])
+
+def test_lifespan():
+    with test_module.get_test_client() as client:
+        # Application's lifespan is called on entering the block.
+        response = client.get("/")
+        assert response.status_code == 200
+
+    # And the lifespan's teardown is run when exiting the block.
+
+```

docs/basics/injection-scope.md

@@ -290,7 +290,7 @@ To execute e2e tests, we adopt a similar configuration to that of unit testing,
 and Ellar's use of **TestClient**, a tool provided by Starlette, to facilitates the simulation of HTTP requests
 
 ### **TestClient**
-Starlette provides a [TestClient](https://www.starlette.io/testclient/) for making requests ASGI Applications, and it's based on [httpx](https://www.python-httpx.org/) library similar to requests.
+Starlette provides a [TestClient](https://www.starlette.io/testclient/){target="_blank"} for making requests ASGI Applications, and it's based on [httpx](https://www.python-httpx.org/) library similar to requests.
 ```python
 from starlette.responses import HTMLResponse
 from starlette.testclient import TestClient