Merge pull request #73 from eadwinCode/module_configuration_2

Module configuration

Author: eadwinCode

Makefile

@@ -39,7 +39,7 @@ doc-deploy: ## Run Deploy Documentation
 	mkdocs gh-deploy --force --ignore-version
 
 doc-serve: ## Launch doc local server
-	make mkdoc serve
+	mkdocs serve
 
 pre-commit-lint: ## Runs Requires commands during pre-commit
 	make clean

README.md

@@ -40,19 +40,15 @@ If you are familiar with these frameworks, you will find it easy to understand a
 ## Installation
 ### Poetry Installation
 For [Poetry](https://python-poetry.org/) usages
+
 ```shell
-poetry add ellar[standard]
+poetry add ellar-cli
 ```
 
 ### Pip Installation
 For normal pip installation
 ```shell
-pip install ellar[standard]
-```
-### NB:
-Some shells may treat square braces (`[` and `]`) as special characters. If that's the case here, then use a quote around the characters to prevent unexpected shell expansion.
-```shell
-pip install "ellar[standard]"
+pip install ellar-cli
 ```
 
 ## Create a project
@@ -234,7 +230,6 @@ Ellar is not aware of `CarModule` yet, so we need to add it to the `modules` lis
 ```python
 from ellar.common import Module, exception_handler
 from ellar.core import IHostContext, ModuleBase
-from ellar.core.connection import Request
 from ellar.core.response import JSONResponse, Response
 
 from ellar.samples.modules import HomeModule
@@ -256,7 +251,7 @@ import os
 
 from ellar.constants import ELLAR_CONFIG_MODULE
 from ellar.core.factory import AppFactory
-from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
 from .root_module import ApplicationModule
 
 application = AppFactory.create_from_app_module(
@@ -273,8 +268,12 @@ document_builder.set_title('CarSite API') \
     .set_license('MIT Licence', url='https://www.google.com')
 
 document = document_builder.build_document(application)
-module = application.install_module(OpenAPIDocumentModule, document=document)
-module.setup_swagger_doc()
+module = OpenAPIDocumentModule.setup(
+    document=document,
+    document_generator=SwaggerDocumentGenerator(),
+    guards=[]
+)
+application.install_module(module)
 ```
 
 Now we can test our API at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs#/)
@@ -303,4 +302,3 @@ Project is still in development
 - Documentation - (in progress)
 - Interceptors  -  [Aspect Oriented Programming](https://en.wikipedia.org/wiki/Aspect-oriented_programming) (AOP) technique
 - Database Plugin with [Encode/ORM](https://github.com/encode/orm)
-- API Throttling

docs/background-task.md

@@ -0,0 +1 @@
+## Coming Soon

docs/basics/api-docs.md

@@ -0,0 +1 @@
+## Coming Soon

docs/basics/commands.md

@@ -0,0 +1 @@
+## Coming Soon

docs/basics/events.md

@@ -0,0 +1 @@
+## Coming Soon

docs/basics/testing.md

@@ -0,0 +1 @@
+## Coming Soon

docs/basics/versioning.md

@@ -7,21 +7,64 @@ 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
-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.
+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.
 
-The configuration of your cache defined in `CACHES` variable in `config.py` file.
+To set up cache, we need to use `CacheModule`. `CacheModule` provides two methods, `CacheModule.register_setup` and `CacheModule.setup`, for setting up `cache` in ellar applications.
 
-```python
-# project_name/config.py
+=== "CacheModule Register Setup"
+    This setup method requires you to defined `CACHES` variable containing 
+    key value pairs of cache backends in `config.py` file.
+    
+    for example:
+        
+    ```python
+    # project_name/config.py
+    
+    from ellar.core import ConfigDefaultTypesMixin
+    from ellar.cache.backends.local_cache import LocalMemCacheBackend
+    
+    class DevelopmentConfig(ConfigDefaultTypesMixin):
+        CACHES = {
+            'default': LocalMemCacheBackend(ttl=300, key_prefix='local', version=1)
+        }
+    ```
+    
+    After that you register `CacheModule` to application modules
+    ```python
+    # project_name/root_module.py
+    from ellar.cache import CacheModule
+    from ellar.common import Module
+    
+    @Module(modules=[CacheModule.register_setup()])
+    class ApplicationModule:
+        pass
+    ```
+    The `register_setup` will read `CACHES` from application config and setup the `CacheService` appropriately.
 
-from ellar.core import ConfigDefaultTypesMixin
-from ellar.cache.backends.local_cache import LocalMemCacheBackend
+=== "CacheModule Setup"
+    The setup method requires direct definition of cache backend on the `CacheModule` setup function.
+    
+    for example:
 
-class DevelopmentConfig(ConfigDefaultTypesMixin):
-    CACHES = {
-        'default': LocalMemCacheBackend(timeout=300, key_prefix='local', version=1)
-    }
-```
+    ```python
+    # project_name/root_module.py
+    from ellar.cache import CacheModule
+    from ellar.cache.backends.local_cache import LocalMemCacheBackend
+    from ellar.common import Module
+    
+    @Module(modules=[
+        CacheModule.setup(
+            default=LocalMemCacheBackend(ttl=300, key_prefix='default', version=1),
+            local=LocalMemCacheBackend(key_prefix='local'),
+            others=LocalMemCacheBackend(key_prefix='others'),
+        )
+    ])
+    class ApplicationModule:
+        pass
+    ```
+    In CacheModule.`setup`, the `default` parameter must be provided and other cache 
+    backends will be defined as keyword-arguments just like `local` and `others` incase you want to set up more than one cache backend.
 
 ### **Memcached**
 [Memcached](https://memcached.org/) is an entirely memory-based cache server, originally developed to handle high loads at LiveJournal.com and subsequently open-sourced by Danga Interactive.
@@ -273,7 +316,7 @@ class DevelopmentConfig(ConfigDefaultTypesMixin):
         'default': PyMemcacheCacheBackend(
             servers=['127.0.0.1:11211'], 
             options={'default_noreply': True}, 
-            timeout=300, 
+            ttl=300, 
             version=1, 
             key_prefix='project_name'
         )
@@ -296,7 +339,7 @@ from ellar.cache.backends.local_cache import LocalMemCacheBackend
 class DevelopmentConfig(ConfigDefaultTypesMixin):
     CACHES = {
         'default': RedisCacheBackend(servers=['redis://127.0.0.1:6379'], key_prefix='project_name'),
-        'secondary': LocalMemCacheBackend(timeout=300, key_prefix='project_name', version=1)
+        'secondary': LocalMemCacheBackend(ttl=300, key_prefix='project_name', version=1)
     }
 ```
 
@@ -313,14 +356,14 @@ The CacheService class provides methods like:
 
 - **get**_**(key: str, version: str = None, backend: str = None)**_: gets `key` value from a specified cache backend.
 - **get_async**_**(key: str, version: str = None, backend: str = None)**_: asynchronous version of `get` action
-- **set**_**(key: str, value: t.Any, timeout: t.Union[float, int] = None, version: str = None,backend: str = None)**_: sets value to a key to a specified cache backend.
-- **set_async**_**(key: str, value: t.Any, timeout: t.Union[float, int] = None, version: str = None,backend: str = None)**_: asynchronous version of `set` action
+- **set**_**(key: str, value: t.Any, ttl: t.Union[float, int] = None, version: str = None,backend: str = None)**_: sets value to a key to a specified cache backend.
+- **set_async**_**(key: str, value: t.Any, ttl: t.Union[float, int] = None, version: str = None,backend: str = None)**_: asynchronous version of `set` action
 - **delete**_**(key: str, version: str = None, backend: str = None)**_: deletes a key from a specified cache backend.
 - **delete_async**_**(key: str, version: str = None, backend: str = None)**_: asynchronous version of `delete` action
 - **has_key**_**(key: str, version: str = None, backend: str = None)**_: checks if a key exist in a specified backend
 - **has_key_async**_**(key: str, version: str = None, backend: str = None)**_: asynchronous version of `has_key` action
-- **touch**_**(key: str, timeout: t.Union[float, int] = None, version: str = None, backend: str = None)**_: sets a new expiration for a key
-- **touch_async**_**(key: str, timeout: t.Union[float, int] = None, version: str = None, backend: str = None)**_: asynchronous version of `touch` action
+- **touch**_**(key: str, ttl: t.Union[float, int] = None, version: str = None, backend: str = None)**_: sets a new expiration for a key
+- **touch_async**_**(key: str, ttl: t.Union[float, int] = None, version: str = None, backend: str = None)**_: asynchronous version of `touch` action
 - **incr**_**(key: str, delta: int = 1, version: str = None, backend: str = None)**_: increments a value for a key by delta
 - **incr_async**_**(key: str, delta: int = 1, version: str = None, backend: str = None)**_: asynchronous version of `incr` action
 - **decr**_**(key: str, delta: int = 1, version: str = None, backend: str = None)**_: decrement a value for a key by delta
@@ -373,7 +416,7 @@ Ellar provides a cache decorator that can be used to cache the responses of rout
 
 The cache decorator takes the following arguments:
 
-- `timeout`: the amount of time (in seconds) for which the response data should be cached.
+- `ttl`(time to live): the amount of time (in seconds) for which the response data should be cached.
 - `key_prefix` (optional): a string that is used to prefix the cache key, allowing for easy differentiation between different cache items.
 - `version` (optional): a string that is used to version the cache key, allowing for cache invalidation when the data schema changes.
 - `backend` (optional): the name of the cache backend to use for storing the cached data. By default, the `default` cache backend is used.
@@ -386,7 +429,7 @@ We can rewrite the above example using `cache` decorator:
 
     ...
     @get('/cache-test')
-    @cache(timeout=300, version='v1', key_prefix='project_name')
+    @cache(ttl=300, version='v1', key_prefix='project_name')
     def my_route_function(self):
         processed_value = 'some-value'
         return processed_value
@@ -397,7 +440,7 @@ We can rewrite the above example using `cache` decorator:
 
     ...
     @get('/cache-test')
-    @cache(timeout=300, version='v1', key_prefix='project_name')
+    @cache(ttl=300, version='v1', key_prefix='project_name')
     async def my_route_function(self):
         processed_value = 'some-value'
         return processed_value
@@ -422,7 +465,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 
     ...
     @get("/my_endpoint")
-    @cache(timeout=60, make_key_callback=make_key_function)
+    @cache(ttl=60, make_key_callback=make_key_function)
     def my_endpoint(self):
         # Code to generate response data here
         processed_value = 'some-value'
@@ -442,7 +485,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 
     ...
     @get("/my_endpoint")
-    @cache(timeout=60, make_key_callback=make_key_function)
+    @cache(ttl=60, make_key_callback=make_key_function)
     async def my_endpoint(self):
         # Code to generate response data here
         processed_value = 'some-value'

docs/caching.md

@@ -0,0 +1,55 @@
+
+Ella CLI provides a way by which commands can be grouped.
+
+For instance, a `db` command may have sub-commands like `makemigrations`, `migrate`, `reset-db` etc.
+
+To achieve this use-case, let us create a file `commands.py` in the root level of the project.
+
+```python
+from ellar.commands import EllarTyper
+
+db = EllarTyper(name="db")
+
+
+@db.command(name="make-migrations")
+def makemigrations():
+    """Create DB Migration """
+
+@db.command()
+def migrate():
+    """Applies Migrations"""
+```
+
+## Register EllarTyper Command
+
+Lets, make the `db` visible on the CLI.
+
+In other for Ellar CLI to identify custom command, its has to be registered to a `@Module` class.
+
+```python
+from ellar.common import Module
+from ellar.core import ModuleBase
+from .commands import db
+
+@Module(commands=[db])
+class ApplicationModule(ModuleBase):
+    pass
+```
+
+open your terminal and navigate to project directory and run the command below
+```shell
+ellar db --help
+```
+
+command output
+```shell
+Usage: Ellar, Python Web framework db [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  make-migrations  Create DB Migration
+  migrate          Applies Migrations
+
+```

docs/commands/command-grouping.md

@@ -0,0 +1,31 @@
+
+This command helps you create an Ellar project module, like a small app within a project.
+It depends on the existence of an Ellar project.
+
+```shell
+ellar create-module my_project_module
+```
+
+will create a folder as follows:
+```angular2html
+john_doe/
+├─ apps/
+│  ├─ my_project_module/
+│  │  ├─ tests/
+│  │  │  ├─ __init__.py
+│  │  ├─ controllers.py
+│  │  ├─ module.py
+│  │  ├─ routers.py
+│  │  ├─ services.py
+│  │  ├─ __init__.py
+│  ├─ __init__.py
+├─ core/
+├─ domain/
+├─ tests/
+│  ├─ __init__.py
+├─ __init__.py/
+├─ config.py
+├─ root_module.py                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         dsssss                                                                                                                                                                                                                                                        cxccccccxxcxxnew_file
+├─ server.py
+
+```

docs/commands/create-module-command.md

@@ -0,0 +1,19 @@
+
+This command helps you create just an Ellar project provided the `"pyproject.toml"` file exists in the working directory(`CWD`)
+
+```shell
+ellar create-project my_new_project
+```
+
+will create a folder as follows:
+```angular2html
+my_new_project/
+├─ apps/
+│  ├─ __init__.py
+├─ core/
+├─ config.py
+├─ domain
+├─ root_module.py
+├─ server.py
+├─ __init__.py
+```