python-ellar · eadwinCode · Jan 27, 2024 · Jan 23, 2024 · Jan 25, 2024 · Jan 27, 2024
diff --git a/Makefile b/Makefile
@@ -9,6 +9,7 @@ clean: ## Removing cached python compiled files
 	find . -name \*pyo | xargs  rm -fv
 	find . -name \*~  | xargs  rm -fv
 	find . -name __pycache__  | xargs  rm -rfv
+	find . -name .pytest_cache  | xargs  rm -rfv
 	find . -name .ruff_cache  | xargs  rm -rfv
 
 install: ## Install dependencies
@@ -23,14 +24,14 @@ lint:fmt ## Run code linters
 	mypy ellar_sql
 
 fmt format:clean ## Run code formatters
-	ruff format ellar_sql tests
-	ruff check --fix ellar_sql tests
+	ruff format ellar_sql tests examples
+	ruff check --fix ellar_sql tests examples
 
-test: ## Run tests
-	pytest tests
+test:clean ## Run tests
+	pytest
 
-test-cov: ## Run tests with coverage
-	pytest --cov=ellar_sql --cov-report term-missing tests
+test-cov:clean ## Run tests with coverage
+	pytest --cov=ellar_sql --cov-report term-missing
 
 pre-commit-lint: ## Runs Requires commands during pre-commit
 	make clean

diff --git a/README.md b/README.md
@@ -8,9 +8,6 @@
 [![PyPI version](https://img.shields.io/pypi/v/ellar-sql.svg)](https://pypi.python.org/pypi/ellar-sql)
 [![PyPI version](https://img.shields.io/pypi/pyversions/ellar-sql.svg)](https://pypi.python.org/pypi/ellar-sql)
 
-## Project Status
-- [x] Production Ready
-- [ ] SQLAlchemy Django Like Query
 
 ## Introduction
 EllarSQL Module adds support for `SQLAlchemy` and `Alembic` package to your Ellar application
@@ -20,6 +17,8 @@ EllarSQL Module adds support for `SQLAlchemy` and `Alembic` package to your Ella
 $(venv) pip install ellar-sql
 ```
 
+This library was inspired by [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/en/3.1.x/){target="_blank"}
+
 ## Features
 
 - Migration

diff --git a/docs/index.md b/docs/index.md
@@ -37,12 +37,10 @@ EllarSQL comes packed with a set of awesome features designed:
 ## **Requirements**
 EllarSQL core dependencies includes:
 
-- Python version >= 3.8
-- Ellar Framework >= 0.6.7
-- SQLAlchemy ORM >= 2.0.16
+- Python >= 3.8
+- Ellar >= 0.6.7
+- SQLAlchemy >= 2.0.16
 - Alembic >= 1.10.0
-- Pillow >= 10.1.0
-- Python-Magic >= 0.4.27
 
 ## **Installation**
 

diff --git a/docs/migrations/env.md b/docs/migrations/env.md
@@ -3,6 +3,7 @@
 In the generated migration template, EllarSQL adopts an async-first approach for handling migration file generation. 
 This approach simplifies the execution of migrations for both `Session`, `Engine`, `AsyncSession`, and `AsyncEngine`, 
 but it also introduces a certain level of complexity.
+
 ```python
 from logging.config import fileConfig
 
@@ -137,7 +138,7 @@ class MyCustomMigrationEnv(AlembicEnvMigrationBase):
 
         """
         key, engine = self.db_service.engines.popitem()
-        metadata = get_metadata(key, certain=True)
+        metadata = get_metadata(key, certain=True).metadata
 
         conf_args = {}
         conf_args.setdefault(

diff --git a/docs/migrations/index.md b/docs/migrations/index.md
@@ -1,15 +1,15 @@
 # **Migrations**
-EllarSQL also extends Alembic package
-to add migration functionality to your application and make database operations available through EllarCLI commandline interface.
+EllarSQL also extends **Alembic** package
+to add migration functionality and make database operations accessible through **EllarCLI** commandline interface.
 
-EllarSQL with Alembic does not override Alembic action rather provide Alembic all the configs/information
-it needs to for a proper migration operation in your application.
+**EllarSQL** with Alembic does not override Alembic action rather provide Alembic all the configs/information
+it needs to for a proper migration/database operations.
 Its also still possible to use Alembic outside EllarSQL setup when necessary.
 
 This section is inspired by [`Flask Migrate`](https://flask-migrate.readthedocs.io/en/latest/#)
 
 ## **Quick Example**
-We assume you have set up `EllarSQLModule` in your application and you have specified `migration_options`.
+We assume you have set up `EllarSQLModule` in your application, and you have specified `migration_options`.
 
 Create a simple `User` model as shown below:
 

diff --git a/docs/models/configuration.md b/docs/models/configuration.md
@@ -1,13 +1,12 @@
 # **EllarSQLModule Config**
+**`EllarSQLModule`** is an Ellar Dynamic Module that offers two ways of configuration:
 
-**`EllarSQLModule`** is a versatile module, allowing configuration through the application `Config`. 
-This configuration can be done either using `EllarSQLModule.register_setup()` within your application setup or directly 
-during module registration with `EllarSQLModule.setup()`.
+- `EllarSQLModule.register_setup()`: This method registers a `ModuleSetup` that depends on the application config.
+- `EllarSQLModule.setup()`: This method immediately sets up the module with the provided options.
 
-While examples have been provided for using `EllarSQLModule.setup()`, this section will shed light 
-on the usage of `EllarSQLModule.register_setup()`. Before diving into that, let's first explore 
-the setup options available for `EllarSQLModule`.
+While we've explored many examples using `EllarSQLModule.setup()`, this section will focus on the usage of `EllarSQLModule.register_setup()`.
 
+Before delving into that, let's first explore the setup options available for `EllarSQLModule`.
 ## **EllarSQLModule Configuration Parameters**
 
 - **databases**: _typing.Union[str, typing.Dict[str, typing.Any]]_:
@@ -128,16 +127,17 @@ For more in-depth information
 on [dealing with disconnects](https://docs.sqlalchemy.org/core/pooling.html#dealing-with-disconnects){target="_blank"}, 
 refer to SQLAlchemy's documentation on handling connection issues.
 
-## **EllarSQLModule With App Config**
-As stated above, **EllarSQLModule** can be configured from application through `EllarSQLModule.register_setup`.
-This will register a [ModuleSetup](https://python-ellar.github.io/ellar/basics/dynamic-modules/#modulesetup){target="_blank"} factory that checks for `ELLAR_SQL` in application config.
-The value of `ELLAR_SQL` read from the application config will be passed `EllarSQLModule` setup action
-which validates and initializes the module.
+## **EllarSQLModule RegisterSetup**
+As mentioned earlier, **EllarSQLModule** can be configured from the application through `EllarSQLModule.register_setup`. 
+This process registers a [ModuleSetup](https://python-ellar.github.io/ellar/basics/dynamic-modules/#modulesetup){target="_blank"} factory
+that depends on the Application Config object. 
+The factory retrieves the `ELLAR_SQL` attribute from the config and validates the data before passing it to `EllarSQLModule` for setup.
 
-It's important to note
-that `ELLAR_SQL` will be a dictionary object with the above [configuration parameters](#ellarsqlmodule-configuration-parameters) as keys.
+It's essential to note 
+that `ELLAR_SQL` will be a dictionary object with the [configuration parameters](#ellarsqlmodule-configuration-parameters) 
+mentioned above as keys.
 
-A Quick example:
+Here's a quick example:
 ```python title="db_learning/root_module.py"
 from ellar.common import Module, exception_handler, IExecutionContext, JSONResponse, Response, IApplicationStartup
 from ellar.app import App
@@ -180,8 +180,10 @@ class DevelopmentConfig(BaseConfig):
         'models': []
     }
 ```
-We have added config for **EllarSQLModule** through `ELLAR_SQL`. And from there, the rest of the actions 
-will be the same as to normal registration with `EllarSQLModule.setup()`.
+The registered ModuleSetup factory reads the `ELLAR_SQL` value and configures the `EllarSQLModule` appropriately.
 
-But with this approach,
-we can seamlessly change **EllarSQLModule** configuration in any environment like CI, Development, Staging or Production.
+This approach is particularly useful when dealing with multiple environments. 
+It allows for seamless modification of the **ELLAR_SQL** values in various environments such as 
+Continuous Integration (CI), Development, Staging, or Production. 
+You can easily change the settings for each environment 
+and export the configurations as a string to be imported into `ELLAR_CONFIG_MODULE`.
diff --git a/docs/models/index.md b/docs/models/index.md
@@ -1,13 +1,13 @@
 # **Quick Start**
-In this section,
-we shall go over how to set up **EllarSQL** in your ellar application
-and have all necessary service registered and configuration set and ready to use.
+In this segment, we will walk through the process of configuring **EllarSQL** within your Ellar application, 
+ensuring that all essential services are registered, configurations are set, and everything is prepared for immediate use.
 
-Before we proceed, we assume you have a clear understanding 
-of how [Ellar Modules](https://python-ellar.github.io/ellar/basics/dynamic-modules/#module-dynamic-setup){target="_blank"} work.
+Before we delve into the setup instructions, it is assumed that you possess a comprehensive 
+understanding of how [Ellar Modules](https://python-ellar.github.io/ellar/basics/dynamic-modules/#module-dynamic-setup){target="_blank"} 
+operate.
 
 ## **Installation**
-Let's install all necessary packages. Also assuming your python environment has been configured:
+Let us install all the required packages, assuming that your Python environment has been properly configured:
 
 #### **For Existing Project:**
 ```shell
@@ -99,10 +99,10 @@ class UsersController(ecm.ControllerBase):
 ```
 
 ## **EllarSQLModule Setup**
-In `root_module.py`, we need to do two things:
+In the `root_module.py` file, two main tasks need to be performed:
 
-- Register `UsersController` to have `/users` available when we start the application
-- configure `EllarSQLModule` to configure and register all necessary services such as `EllarSQLService`, `Session` and `Engine`
+1. Register the `UsersController` to make the `/users` endpoint available when starting the application.
+2. Configure the `EllarSQLModule`, which will set up and register essential services such as `EllarSQLService`, `Session`, and `Engine`.
 
 ```python title="db_learning/root_module.py"
 from ellar.common import Module, exception_handler, IExecutionContext, JSONResponse, Response, IApplicationStartup
@@ -111,7 +111,6 @@ from ellar.core import ModuleBase
 from ellar_sql import EllarSQLModule, EllarSQLService
 from .controller import UsersController
 
-
 @Module(
     modules=[EllarSQLModule.setup(
         databases={
@@ -133,19 +132,19 @@ class ApplicationModule(ModuleBase, IApplicationStartup):
     def exception_404_handler(cls, ctx: IExecutionContext, exc: Exception) -> Response:
         return JSONResponse(dict(detail="Resource not found."), status_code=404)
 ```
-In the above illustration,
-we registered `UserController` and `EllarSQLModule` with some configurations on database and migration options.
-See more on `EllarSQLModule` configurations.
 
-Also, on the `on_startup` function, we retrieved `EllarSQLService` registered into the system through `EllarSQLModule`,
-and call the `create_all()` function to create the SQLAlchemy tables.
+In the provided code snippet:
+
+- We registered `UserController` and `EllarSQLModule` with specific configurations for the database and migration options. For more details on [`EllarSQLModule` configurations](./configuration.md#ellarsqlmodule-config).
+
+- In the `on_startup` method, we obtained the `EllarSQLService` from the Ellar Dependency Injection container using `EllarSQLModule`. Subsequently, we invoked the `create_all()` method to generate the necessary SQLAlchemy tables.
 
-At this point, we are ready to test the application. 
+With these configurations, the application is now ready for testing.
 ```shell
 ellar runserver --reload
 ```
-Also,
-remember to uncomment the `OpenAPIModule` configurations
-in `server.py` to be able to visualize and interact with the `/users` the endpoint.
+Additionally, please remember to uncomment the configurations for the `OpenAPIModule` in the `server.py` 
+file to enable visualization and interaction with the `/users` endpoint.
 
-With that said, visit [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs){target="_blank"}
+Once done, 
+you can access the OpenAPI documentation at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs){target="_blank"}.