Merge pull request #82 from eadwinCode/websocket_documentation

WIP: Socket IO integration and Websocket documentation

Author: eadwinCode

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="#" target="blank"><img src="docs/img/EllarLogoIconOnly.png" width="200" alt="Ellar Logo" /></a>
+  <a href="#" target="blank"><img src="docs/img/EllarLogoB.png" width="200" alt="Ellar Logo" /></a>
 </p>
 
 <p align="center"> Ellar - Python ASGI web framework for building fast, efficient and scalable RESTAPIs and server-side application. </p>
@@ -16,8 +16,6 @@ Ellar is a lightweight ASGI framework for building efficient and scalable server
 It supports both OOP (Object-Oriented Programming) and FP (Functional Programming)
 
 Ellar is based on [Starlette (ASGI toolkit)](https://www.starlette.io/), a lightweight ASGI framework/toolkit well-suited for developing asynchronous web services with Python. 
-While Ellar provides a high level of abstraction on top of Starlette, it still incorporates some of its features, as well as those of FastAPI. 
-If you are familiar with these frameworks, you will find it easy to understand and use Ellar.
 
 ## **Features Summary**
 
@@ -87,7 +85,7 @@ ellar create-module car
 ## **Add Schema**
 In `car/schema.py`, lets add some serializer for car input and output data
 ```python
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 class CarSerializer(Serializer):
     name: str
@@ -228,8 +226,7 @@ class CarModule(ModuleBase):
 Ellar is not aware of `CarModule` yet, so we need to add it to the `modules` list of `ApplicationModule` at the `carsite/root_module.py`.
 ```python
 from ellar.common import Module, exception_handler
-from ellar.core import IHostContext, ModuleBase
-from ellar.core.response import JSONResponse, Response
+from ellar.core import IHostContext, ModuleBase, JSONResponse, Response
 
 from ellar.samples.modules import HomeModule
 from .apps.car.module import CarModule
@@ -249,7 +246,7 @@ then add the following below.
 import os
 
 from ellar.constants import ELLAR_CONFIG_MODULE
-from ellar.core.factory import AppFactory
+from ellar.core import AppFactory
 from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
 from .root_module import ApplicationModule
 

docs/basics/testing.md

@@ -322,11 +322,16 @@ from project_name.apps.car.schemas import CreateCarSerializer, CarListFilter
 from project_name.apps.car.services import CarRepository
 
 
+class MockCarRepository(CarRepository):
+    def get_all(self):
+        return [dict(id=2, model='CLS',name='Mercedes', year=2023)]
+
+
 class TestCarControllerE2E:
     def setup(self):
         test_module = Test.create_test_module(
             controllers=[CarController,],
-            providers=[ProviderConfig(CarRepository, use_class=CarRepository)],
+            providers=[ProviderConfig(CarRepository, use_class=MockCarRepository)],
             config_module=dict(
                 REDIRECT_SLASHES=True
             )
@@ -346,8 +351,7 @@ class TestCarControllerE2E:
             "year": 2022,
         }
 
-    @patch.object(CarRepository, 'get_all', return_value=[dict(id=2, model='CLS',name='Mercedes', year=2023)])
-    def test_get_all_action(self, mock_get_all):
+    def test_get_all_action(self):
         res = self.client.get('/car?offset=0&limit=10')
         assert res.status_code == 200
         assert res.json() == {

docs/handling-response/response-model.md

@@ -6,7 +6,7 @@ This response model holds information on the type of response to be returned.
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, get
 from ellar.core import ControllerBase
 
@@ -30,7 +30,7 @@ During route response computation, the `me` route handler response will evaluate
 The resulting route responses will be:
 
 ```python
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.core.response.model import JSONResponseModel
 
 
@@ -76,7 +76,7 @@ For example:
 from ellar.common import Controller, get
 from ellar.core import ControllerBase
 from starlette.responses import PlainTextResponse
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 
 class UserSchema(Serializer):

docs/handling-response/response.md

@@ -5,7 +5,7 @@ To use `Serializer` in Ellar, you simply need to create a class that inherits fr
 Here's an example of how you could define a serializer class for a user model:
 
 ```python
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 class UserSerializer(Serializer):
     name: str
@@ -27,7 +27,7 @@ For example:
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, get
 from ellar.core import ControllerBase
 
@@ -80,7 +80,7 @@ For instance, we can convert the `UserSchema` to a dataclass by defining `UserDa
 
 ```python
 from dataclasses import dataclass
-from ellar.serializer import DataclassSerializer
+from ellar.core.serializer import DataclassSerializer
 
 
 @dataclass
@@ -101,7 +101,7 @@ The `response` parameter takes different shape. Let's see how to return a differ
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, get
 from ellar.core import ControllerBase
 
@@ -185,7 +185,7 @@ Also, we can return response object from endpoint functions, and it will overrid
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, get
 from ellar.core import ControllerBase
 from starlette.responses import PlainTextResponse

docs/img/live_support_websocket.gif

@@ -15,16 +15,17 @@
 Ellar is a lightweight ASGI framework for building efficient and scalable server-side python applications.
 It supports both OOP (Object-Oriented Programming) and FP (Functional Programming)
 
-Ellar is based on [Starlette (ASGI toolkit)](https://www.starlette.io/), a lightweight ASGI framework/toolkit well-suited for developing asynchronous web services in Python. 
-And while Ellar provides a high level of abstraction on top of Starlette, it still incorporates some of its features, as well as those of FastAPI. 
-If you are familiar with these frameworks, you will find it easy to understand and use Ellar.
+Ellar is also a higher level of abstraction of [Starlette (ASGI toolkit)](https://www.starlette.io/), a lightweight ASGI framework/toolkit well-suited for developing asynchronous web services in Python.
 
 ## **Inspiration**
-Ellar was deeply influenced by [NestJS](https://docs.nestjs.com/) for its ease of use and ability to handle complex project structures and applications. 
-Additionally, it took some concepts from [FastAPI](https://fastapi.tiangolo.com/) in terms of request parameter handling and data serialization with Pydantic. 
+Ellar was deeply influenced by [NestJS](https://docs.nestjs.com/) for its ease of use, project structures and patterns that aids in building small or complex project applications.
+Also, Ellar took some concepts from [FastAPI](https://fastapi.tiangolo.com/) in terms of request parameter handling and data serialization with Pydantic. 
+
+The objective of Ellar is to provide a high level of abstracted interface to the web, along with a well-structured project setup, give room for object-oriented approach to web application design, 
+allow you chose your desired application architecture, and ultimately, deliver speedy handling to requests.
+
+As developers, we never know how big a project can become or evolve over time but following some design patterns and architecture makes it easier to build a more testable and maintainable application.
 
-With that said, the objective of Ellar is to offer a high level of abstraction in its framework APIs, along with a well-structured project setup, an object-oriented approach to web application design, 
-the ability to adapt to any desired software architecture, and ultimately, speedy request handling.
 
 
 ## **Features Summary**

docs/index.md

@@ -215,7 +215,7 @@ Before that, we need to define our data input/output serializers
 
 ```python
 # project_name/apps/car/schema.py
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from pydantic import Field
 
 
@@ -258,7 +258,7 @@ Ellar will compute values for all the route handler parameters and validates the
 !!! info
     if a parameter is not annotated, it will be assumed as a `string` type
 
-![CreateDogSchema](../img/create-car-schema.png)
+![CreateCarSchema](../img/create-car-schema.png)
 
 Let's add other endpoints
 

docs/overview/controllers.md

@@ -46,12 +46,14 @@ from ellar.core import WebSocket
 def sample_endpoint_ws(self, websocket: WebSocket, data_schema: str = WsBody()):
     pass
 
-@sample_endpoint_ws.connect
+@ws_route.connect(sample_endpoint_ws)
 async def on_connect(self, websocket: WebSocket):
+    # Called when there is a connection to `sample_endpoint_ws`
     await websocket.accept()
 
-@sample_endpoint_ws.disconnect
-async def on_connect(self, websocket: WebSocket, code: int):
+@ws_route.disconnect(sample_endpoint_ws)
+async def on_disconnect(self, websocket: WebSocket, code: int):
+    # Called when there is a disconnect from `sample_endpoint_ws`
     await websocket.close(code)
 ```
 
@@ -253,7 +255,7 @@ And the route function is required to return a dictionary object that follows a
 ```python
 import typing as t
 from enum import Enum
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 
 class ContentDispositionType(str, Enum):
@@ -361,7 +363,7 @@ For example:
 ```python
 import typing as t
 from ellar.common import serializer_filter, get
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 class UserSchema(Serializer):
     username: str

docs/overview/custom_decorators.md

@@ -146,11 +146,11 @@ Brief overview of the generated files:
 |-------------------|---------------------------------------------------|
 | `car.controllers` | A basic controller with an `index` route.         |
 | `car.module.py`   | car module/app `Module` metadata definition.      |
-| `car.services.py` | For Dogs module service declarations.             |
+| `car.services.py` | For Car module service declarations.              |
 | `car.schemas.py`  | Data-transfer-object or Serializers declarations. |
-| `car.tests/`      | testing directory for the dogs module.            |
+| `car.tests/`      | testing directory for the car module.             |
 
-To finish up with the created `dogs` module, we need to register it to the 
+To finish up with the created `car` module, we need to register it to the 
 `project_name.root_module.py`
 
 ```python
@@ -167,7 +167,7 @@ class ApplicationModule(ModuleBase):
 ```
 That's it.
 
-Goto your browser and visit: [http://localhost:8000/dogs/](http://localhost:8000/car/)
+Goto your browser and visit: [http://localhost:8000/car/](http://localhost:8000/car/)
 ```json
 {
   "detail": "Welcome Car Resource"

docs/overview/index.md

@@ -14,7 +14,7 @@ First, you need to import `Serializer` from `ella.serializer`:
 
 ```python
 # project_name/apps/items/controllers.py
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 
 # class Item(Serializer):
 #     name: str
@@ -33,7 +33,7 @@ Use standard Python types for all the attributes:
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, post
 from ellar.core import ControllerBase
 
@@ -81,7 +81,7 @@ To add it to your *path operation*, declare it the same way you declared the pat
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, post
 from ellar.core import ControllerBase
 
@@ -137,7 +137,7 @@ You can declare path parameters **and** body requests at the same time.
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, post, put
 from ellar.core import ControllerBase
 
@@ -168,7 +168,7 @@ You can also declare **body**, **path** and **query** parameters, all at the sam
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, post, put
 from ellar.core import ControllerBase
 
@@ -213,7 +213,7 @@ But you can instruct **Ellar** to treat it as another body key using Body:
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, Body, post, put
 from ellar.core import ControllerBase
 from pydantic import BaseModel
@@ -274,7 +274,7 @@ For example:
 ```python
 # project_name/apps/items/controllers.py
 
-from ellar.serializer import Serializer
+from ellar.core.serializer import Serializer
 from ellar.common import Controller, Body, post, put
 from ellar.core import ControllerBase
 from pydantic import BaseModel