Merge pull request #179 from python-ellar/refactoring

Final Overall Refactor

Author: eadwinCode

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+<[email protected]>.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

README.md

@@ -113,11 +113,11 @@ document_builder.set_title('Ellar API') \
 
 document = document_builder.build_document(app)
 module = OpenAPIDocumentModule.setup(
+    app=app,
     docs_ui=SwaggerUI(),
     document=document,
     guards=[]
 )
-app.install_module(module)
 
 
 if __name__ == "__main__":

docs/basics/application-context.md

@@ -0,0 +1,95 @@
+# **Application 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, 
+a powerful mechanism that facilitates smooth access to the application instance throughout various parts of the codebase.
+
+## **Understanding the Application Context**
+
+The application 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.
+
+## **Integration with Click Commands**
+
+By decorating Click commands with `click.with_app_context`, you can effortlessly incorporate the application context 
+into their CLI workflows. This allows them to leverage the full power of the application context when executing commands.
+
+For instance, consider the following example:
+
+```python
+import ellar_cli.click as click
+from ellar.app import current_injector
+from ellar.di import injectable
+
+@injectable
+class MyService:
+    def do_something(self) -> None:
+        pass
+
+@click.command()
+@click.argument('name')
+@click.with_app_context
+def my_command(name: str):
+    my_service = current_injector.get(MyService)
+    my_service.do_something()
+```
+
+Here, the `click.with_app_context` decorator ensures that the application context is available within the `my_command` function, 
+allowing seamless access to application resources.
+
+## **Lifecycle of the Application Context**
+
+The application context operates as an asynchronous context manager, automatically created at 
+the beginning of request handling and gracefully torn down upon completion of the request. 
+
+## **Handling Application Context Events**
+
+Additionally, the application context offers event hooks that you can leverage to perform custom actions at 
+specific points in the context's lifecycle. 
+
+Two such events are `app_context_started` and `app_context_teardown`, 
+which are triggered at the beginning and end of the context, respectively.
+
+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
+
+@app_context_started.connect
+async def on_context_started():
+    print('=======> Context Started <=======')
+
+@app_context_teardown.connect
+def on_context_ended():
+    print('=======> Context ended <=========')
+
+app = AppFactory.create_app()
+
+@run_as_async
+async def run_app_context():
+    async with app.application_context() as ctx:
+        print("-----> Context is now available <------")
+
+        app_instance = ctx.injector.get(App)
+        app_instance_2 = current_injector.get(App)
+
+        assert app_instance == app == app_instance_2
+    print("-----> Context is now destroyed <------")
+
+if __name__ == '__main__':
+    run_app_context()
+```
+
+In this example, event handlers are registered to execute custom logic when the application context starts and ends. 
+This allows you to perform initialization or cleanup tasks as needed.

…pp/apps/events/tests/test_controllers.py docs/basics/storage.mdexamples/02-socketio-app/socketio_app/apps/events/tests/test_controllers.py renamed to docs/basics/storage.md examples/02-socketio-app/socketio_app/apps/events/tests/test_controllers.py renamed to docs/basics/storage.md

@@ -41,7 +41,7 @@ ARGUMENTS:
 ## **With App Context Decorator**
 The `ellar_cli.click` module includes a command decorator function called `with_app_context`. 
 This decorator ensures that a click command is executed within the application context, 
-allowing `current_app`, `current_injector`, and `current_config` to have values.
+allowing `current_injector`, and `config` to have values.
 
 For instance:
 

docs/cli/custom-commands.md

@@ -1 +1,81 @@
-# Coming Soon
+# **Contribution Guidelines**
+
+Thank you for considering contributing to Ellar! Your contributions help make the project better for everyone. 
+Please take a moment to review the following guidelines before getting started.
+
+## Setting up the Development Environment
+
+1. **Fork the repository:** Fork the Ellar repository on GitHub and clone it locally.
+
+2. **Virtual Environment:** Create and activate a virtual environment for the project.
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Linux/macOS
+   ```
+
+   ```bash
+   python -m venv venv
+   .\venv\Scripts\activate  # Windows
+   ```
+
+3. **Install `flit`:** Ensure you have `flit` installed globally.
+
+   ```bash
+   pip install flit
+   ```
+
+4. **Install Dependencies:** Install development libraries and pre-commit hooks.
+
+   ```bash
+   make install
+   ```
+
+### **Code Style and Formatting**
+
+- **Formatting:** To format your code and ensure consistency, run:
+
+  ```bash
+  make fmt
+  ```
+  
+- **Linting:** Ellar uses `mypy` and `ruff` for linting. Run the following command to check code linting:
+
+  ```bash
+  make lint
+  ```
+
+### **Testing**
+
+- **Unit Tests:** We use `pytest` for unit testing. Run the test suite:
+
+  ```bash
+  make test
+  ```
+
+- **Test Coverage:** To check test coverage:
+
+  ```bash
+  make test-cov
+  ```
+
+### **Submitting a Pull Request**
+
+1. **Branch:** Create a new branch for your feature or bug fix.
+
+   ```bash
+   git checkout -b feature-branch
+   ```
+
+2. **Commit Messages:** Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for your commit messages.
+
+3. **Push Changes:** Push your branch to your forked repository.
+
+   ```bash
+   git push origin feature-branch
+   ```
+
+4. **Pull Request:** Open a pull request against the `master` branch of the Ellar repository. Provide a clear and descriptive title and description for your changes.
+
+
+Thank you for contributing to Ellar! 🚀