Merge pull request #123 from python-ellar/intro_doc_change

Doc Updates

Author: eadwinCode

Makefile

@@ -9,7 +9,6 @@ clean: ## Removing cached python compiled files
 	find . -name \*pyo | xargs  rm -fv
 	find . -name \*~  | xargs  rm -fv
 	find . -name __pycache__  | xargs  rm -rfv
-	ruff --clean
 
 install: ## Install dependencies
 	flit install --deps develop --symlink
@@ -33,8 +32,7 @@ test: ## Run tests
 test-cov: ## Run tests with coverage
 	pytest --cov=ellar --cov-report term-missing
 
-doc-deploy: ## Run Deploy Documentation
-	make clean
+doc-deploy:clean ## Run Deploy Documentation
 	mkdocs gh-deploy --force --ignore-version
 
 doc-serve: ## Launch doc local server

README.md

@@ -43,244 +43,90 @@ Ellar is based on [Starlette (ASGI toolkit)](https://www.starlette.io/), a light
 - Pydantic
 
 ## **Installation**
-### Poetry Installation
-For [Poetry](https://python-poetry.org/) usages
-
-```shell
-poetry add ellar-cli
-```
-
-### Pip Installation
-For normal pip installation
-```shell
-pip install ellar-cli
-```
-
-## **Creating a project**
-To create an ellar project, you need to have a `pyproject.toml` available on your root directory.
-This is necessary for ellar to store some `metadata` about your project. 
-
-For Pip Users, you need to create `pyproject.toml` file
-```shell
-ellar new carsite
-```
-If you are using `Poetry`, at your project root directory with `pyproject.toml`,
-run the ellar create project cli command,
-```shell
-ellar create-project carsite
-```
-
-## **Run your project**
-Ellar runs [UVICORN - ASGI Server](https://www.uvicorn.org/) under the hood.
-```shell
-ellar runserver --reload
-```
-`--reload` is to watch for file changes
-
-Now go to [http://127.0.0.1:8000](http://127.0.0.1:8000)
-![Swagger UI](https://python-ellar.github.io/ellar/img/ellar_framework.png)
-
-For more info on Ellar CLI, click [here](https://github.com/python-ellar/ellar-cli)
-
-## **Adding a project module**
-A project module is a project app defining a group of controllers or services including templates and static files.
-So, now we have a project created, lets add an app to the project.
 ```shell
-ellar create-module car
+$(venv) pip install ellar
 ```
 
-## **Add Schema**
-In `car/schema.py`, lets add some serializer for car input and output data
+## **Try This**
 ```python
-from ellar.common import Serializer
+import uvicorn
+from ellar.common import Body, Controller, ControllerBase, delete, get, post, put, Serializer, Provide
+from ellar.core import AppFactory
+from ellar.di import injectable, request_scope
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
+from pydantic import Field
+from pathlib import Path
+
 
-class CarSerializer(Serializer):
+class CreateCarSerializer(Serializer):
     name: str
+    year: int = Field(..., gt=0)
     model: str
-    brand: str
-
-
-class RetrieveCarSerializer(CarSerializer):
-    pk: str
-```
-
-## **Add Services**
-In `car/services.py`, lets create a dummy repository `CarDummyDB` to manage our car data.
-```python
-import typing as t
-import uuid
-from ellar.di import injectable, singleton_scope
-
 
-@injectable(scope=singleton_scope)
-class CarDummyDB:
-    class CarDummyDBItem:
-        pk: str
 
-        def __init__(self, **data: t.Dict) -> None:
-            self.__dict__ = data
-
-        def __eq__(self, other):
-            if isinstance(other, CarDummyDB.CarDummyDBItem):
-                return self.pk == other.pk
-            return self.pk == str(other)
-
-    def __init__(self) -> None:
-        self._data: t.List[CarDummyDB.CarDummyDBItem] = []
-
-    def add_car(self, data: t.Dict) -> str:
-        pk = uuid.uuid4()
-        _data = dict(data)
-        _data.update(pk=str(pk))
-        item = self.CarDummyDBItem(**_data)
-        self._data.append(item)
-        return item.pk
-
-    def list(self) -> t.List["CarDummyDB.CarDummyDBItem"]:
-        return self._data
-
-    def update(self, car_id: str, data: t.Dict) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
-        idx = self._data.index(car_id)
-        if idx >= 0:
-            _data = dict(data)
-            _data.update(pk=str(car_id))
-            self._data[idx] = self.CarDummyDBItem(**_data)
-            return self._data[idx]
-
-    def get(self, car_id: str) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
-        idx = self._data.index(car_id)
-        if idx >= 0:
-            return self._data[idx]
-
-    def remove(self, car_id: str) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
-        idx = self._data.index(car_id)
-        if idx >= 0:
-            return self._data.pop(idx)
-```
-## **Add Controller**
-In `car/controllers.py`, lets create `CarController`
-
-```python
-import typing as t
-from ellar.common import Controller, delete, get, put, post, ControllerBase
-from ellar.common.exceptions import NotFound
-from .schemas import CarSerializer, RetrieveCarSerializer
-from .services import CarDummyDB
+@injectable(scope=request_scope)
+class CarService:
+    def __init__(self):
+        self.detail = 'a service'
 
 
 @Controller
-class CarController(ControllerBase):
-    def __init__(self, db: CarDummyDB) -> None:
-        self.car_db = db
-
-    @post("/create", response={200: str})
-    async def create_cat(self, payload: CarSerializer):
-        pk = self.car_db.add_car(payload.dict())
-        return pk
-
-    @put("/{car_id:str}", response={200: RetrieveCarSerializer})
-    async def update_cat(self, car_id: str, payload: CarSerializer):
-        car = self.car_db.update(car_id, payload.dict())
-        if not car:
-            raise NotFound("Item not found")
-        return car
-
-    @get("/{car_id:str}", response={200: RetrieveCarSerializer})
-    async def get_car_by_id(self, car_id: str):
-        car = self.car_db.get(car_id)
-        if not car:
-            raise NotFound('Item not found.')
-        return car
-
-    @delete("/{car_id:str}", response={204: dict})
-    async def deleted_cat(self, car_id: str):
-        car = self.car_db.remove(car_id)
-        if not car:
-            raise NotFound('Item not found.')
-        return 204, {}
-
-    @get("/", response={200: t.List[RetrieveCarSerializer]})
-    async def list(self):
-        return self.car_db.list()
-
-```
-## **Register Service and Controller**
-In `car/module.py`, lets register `CarController` and `CarDummyDB`
-
-```python
-from ellar.common import Module
-from ellar.core import ModuleBase
-from ellar.di import Container
-
-from .controllers import CarController
-from .services import CarDummyDB
-
-
-@Module(
-    controllers=[CarController],
-    providers=[CarDummyDB],
-    routers=[],
-)
-class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
-```
-
-## **Registering Module**
-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, JSONResponse, Response, IHostContext
-from ellar.core import ModuleBase
-
-from ellar.samples.modules import HomeModule
-from .car.module import CarModule
-
-
-@Module(modules=[HomeModule, CarModule])
-class ApplicationModule(ModuleBase):
-    @exception_handler(404)
-    def exception_404_handler(cls, context: IHostContext, exc: Exception) -> Response:
-        return JSONResponse(dict(detail="Resource not found."))
-
-```
-## **Enabling OpenAPI Docs**
-To start up openapi, we need to go back to project folder in the `server.py`
-then add the following below.
-```python
-import os
-
-from ellar.constants import ELLAR_CONFIG_MODULE
-from ellar.core import AppFactory
-from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
-from .root_module import ApplicationModule
-
-application = AppFactory.create_from_app_module(
-    ApplicationModule,
-    config_module=os.environ.get(
-        ELLAR_CONFIG_MODULE, "carsite.config:DevelopmentConfig"
-    ),
+class MotoController(ControllerBase):
+    def __init__(self, service: CarService):
+        self._service = service
+    
+    @post()
+    async def create(self, payload: CreateCarSerializer = Body()):
+        assert self._service.detail == 'a service'
+        result = payload.dict()
+        result.update(message='This action adds a new car')
+        return result
+
+    @put('/{car_id:str}')
+    async def update(self, car_id: str, payload: CreateCarSerializer = Body()):
+        result = payload.dict()
+        result.update(message=f'This action updated #{car_id} car resource')
+        return result
+
+    @get('/{car_id:str}')
+    async def get_one(self, car_id: str, service: CarService = Provide()):
+        assert self._service == service
+        return f"This action returns a #{car_id} car"
+
+    @delete('/{car_id:str}')
+    async def delete(self, car_id: str):
+        return f"This action removes a #{car_id} car"
+
+
+app = AppFactory.create_app(
+    controllers=[MotoController],
+    providers=[CarService],
+    base_directory=str(Path(__file__).parent),
+    config_module=dict(REDIRECT_SLASHES=True),
+    template_folder='templates'
 )
-
 document_builder = OpenAPIDocumentBuilder()
-document_builder.set_title('CarSite API') \
-    .set_version('1.0.0') \
-    .set_contact(name='Eadwin', url='https://www.yahoo.com', email='eadwin@gmail.com') \
+document_builder.set_title('Ellar API') \
+    .set_version('1.0.2') \
+    .set_contact(name='Author', url='https://www.yahoo.com', email='author@gmail.com') \
     .set_license('MIT Licence', url='https://www.google.com')
 
-document = document_builder.build_document(application)
+document = document_builder.build_document(app)
 module = OpenAPIDocumentModule.setup(
-    document=document,
     document_generator=SwaggerDocumentGenerator(),
+    document=document,
     guards=[]
 )
-application.install_module(module)
+app.install_module(module)
+
+
+if __name__ == "__main__":
+    uvicorn.run("main:app", port=5000, reload=True)
 ```
 
-Now we can test our API at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs#/)
-Please ensure your server is running
-![Swagger UI](https://python-ellar.github.io/ellar/img/car_api.png)
+Now we can test our API at [http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs#/)
+
+You can also try the [quick-project](https://python-ellar.github.io/ellar/quick-project/) setup to get a good idea of the library.
 
 ## **HTML Templating**
 Ellar has built-in support for Jinja2, which is a popular template engine for HTML. This feature allows for easy and efficient HTML templating similar to that of Flask. Jinja2 can be used to create reusable templates, and to insert dynamic data into HTML pages. It also has support for template inheritance, control structures, and other useful features that can help to simplify and streamline the process of creating HTML templates.

docs/cli/custom-commands.md

@@ -87,3 +87,25 @@ Commands:
   runserver       - Starts Uvicorn Server -
   say-hi 
 ```
+
+## **Using Click Commands**
+If prefer click commands, Ellar-CLI supports that too. Simply create a click command and register it to any module registered in
+the `ApplicationModule`. For example
+
+```python
+import click
+from ellar.common import JSONResponse, Module, Response, exception_handler
+from ellar.core import ModuleBase
+from ellar.core.connection import Request
+
+@click.command()
+def say_hello():
+    click.echo("Hello from ellar.")
+
+
+@Module(commands=[say_hello])
+class ApplicationModule(ModuleBase):
+    @exception_handler(404)
+    def exception_404_handler(cls, request: Request, exc: Exception) -> Response:
+        return JSONResponse({"detail": "Resource not found."})
+```