Merge pull request #7 from eadwinCode/init_command

Ellar New Project Command

Author: eadwinCode

README.md

@@ -9,3 +9,5 @@
 [![PyPI version](https://badge.fury.io/py/ellar-cli.svg)](https://badge.fury.io/py/ellar-cli)
 [![PyPI version](https://img.shields.io/pypi/v/ellar-cli.svg)](https://pypi.python.org/pypi/ellar-cli)
 [![PyPI version](https://img.shields.io/pypi/pyversions/ellar-cli.svg)](https://pypi.python.org/pypi/ellar-cli)
+
+Full Documentation: [Here](https://eadwincode.github.io/ellar-cli/)

docs/command-grouping.md

@@ -0,0 +1,46 @@
+
+Ella CLI provides a way by which commands can be grouped together. 
+
+For instance, a `db` command may have sub-commands like `makemigrations`, `migrate`, `reset-db` etc.
+
+To achieve this use-case, create a file `commands.py` in root 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"""
+```
+in `ApplicationModule`, add the command to `Module` commands parameter 
+```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/create-module-command.md

@@ -0,0 +1,28 @@
+
+This command helps you create 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
+|   |   └── __init__.py
+|   |   └── controllers.py
+|   |   └── module.py
+|   |   └── routers.py
+|   |   └── schemas.py
+|   |   └── services.py
+|   |   └── tests
+|   └── __init__.py
+├── core
+├── domain
+└── __init__.py
+└── config.py
+└── root_module.py
+└── server.py
+```

docs/create-project-command.md

@@ -0,0 +1,19 @@
+
+This command helps you create just an ellar project provided `pyproject.toml` exist 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
+├── domain
+└── __init__.py
+└── config.py
+└── root_module.py
+└── server.py
+```

docs/custom-commands.md

@@ -0,0 +1,57 @@
+This is a quick example of how to create a custom command. Also, hints on working of ella cli.
+
+Ellar CLI tools is a wrapper round [typer](), 
+so it's easy to get CLI context available in the command action.
+Ellar CLI exposes some cli context necessary for validation and interacting with ellar project.
+
+Create a file `commands.py` in root project
+```python
+import typing as t
+import typer
+from ellar.common import command
+from ellar_cli.service import EllarCLIService
+from ellar_cli.constants import ELLAR_META
+
+@command
+def my_new_command(ctx:typer.Context):
+    """my_new_command cli description """
+    ellar_cli_service = t.cast(t.Optional[EllarCLIService], ctx.meta.get(ELLAR_META))
+```
+`ellar_cli_service` holds ellar project meta-data
+Lets, make the `my_new_command` visible on the cli.
+
+In `ApplicationModule`, add the command to `Module` commands parameter 
+```python
+from ellar.common import Module
+from ellar.core import ModuleBase
+from .commands import my_new_command
+
+@Module(commands=[my_new_command])
+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 [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  -p, --project TEXT              Run Specific Command on a specific project
+  --install-completion [bash|zsh|fish|powershell|pwsh]
+                                  Install completion for the specified shell.
+  --show-completion [bash|zsh|fish|powershell|pwsh]
+                                  Show completion for the specified shell, to
+                                  copy it or customize the installation.
+  --help                          Show this message and exit.
+
+Commands:
+  create-module   - Scaffolds Ellar Application Module -
+  create-project  - Scaffolds Ellar Application -
+  my-new-command  my_new_command cli description
+  new             - Runs a complete Ellar project scaffold and creates...
+  runserver       - Starts Uvicorn Server -
+  say-hi 
+```

docs/index.md

@@ -2,117 +2,33 @@
   <a href="#" target="blank"><img src="img/EllarLogoIconOnly.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>
+<p align="center"> Ellar CLI Tool for Scaffolding Ellar Projects and Modules and also running Ellar Commands</p>
 
-![Test](https://github.com/eadwinCode/ellar/actions/workflows/test_full.yml/badge.svg)
-![Coverage](https://img.shields.io/codecov/c/github/eadwinCode/ellar)
-[![PyPI version](https://badge.fury.io/py/ellar.svg)](https://badge.fury.io/py/ellar)
-[![PyPI version](https://img.shields.io/pypi/v/ellar.svg)](https://pypi.python.org/pypi/ellar)
-[![PyPI version](https://img.shields.io/pypi/pyversions/ellar.svg)](https://pypi.python.org/pypi/ellar)
+![Test](https://github.com/eadwinCode/ellar-cli/actions/workflows/test_full.yml/badge.svg)
+![Coverage](https://img.shields.io/codecov/c/github/eadwinCode/ellar-cli)
+[![PyPI version](https://badge.fury.io/py/ellar-cli.svg)](https://badge.fury.io/py/ellar-cli)
+[![PyPI version](https://img.shields.io/pypi/v/ellar-cli.svg)](https://pypi.python.org/pypi/ellar-cli)
+[![PyPI version](https://img.shields.io/pypi/pyversions/ellar-cli.svg)](https://pypi.python.org/pypi/ellar-cli)
 
-## Features
-- Pydantic integration
-- DI Container
-- Templating with Jinja2
-- OpenAPI Documentation (Swagger and ReDoc)
-- Controller (MVC)
-- Guards (Authentications, roles and permissions)
-- Modularization (eg: flask blueprint)
-- Websocket support
-- Session and Cookie support
-- CORS, GZip, Static Files, Streaming responses
-- Test client built on `requests`
-- In-process background tasks.
-- Startup and shutdown events.
-- Application Events
-- Compatible with `asyncio` and `trio` backends.
+# Introduction
+Ellar CLI is an abstracted tool for ellar web framework that helps in standard project scaffold of the framework, module project scaffold, runing the project local server using uvicorn and runing custom command registered in application module or any ellar module.
 
 ## Requirements
-- Python >= 3.6
-- Starlette
-- Pydantic
-- Injector
+- Python >= 3.7
+- Ellar
 
 ## Installation
-
+if you have [ellar](https://github.com/eadwinCode/ellar) install ready
 ```
-pip install ellar
+pip install ellar-cli
 ```
-
-## Usage
-
-Create a file `controller.py`:
-
-```Python
-from ellar.common import ModuleRouter, Controller, get
-
-router = ModuleRouter('', tag='Math')
-
-
-@router.get("/add")
-def add(request, a: int, b: int):
-    return {"result": a + b}
-
-
-@Controller("", tag='Math')
-class MathAPI:
-
-    @get('/subtract', )
-    def subtract(self, a: int, b: int):
-        """Subtracts a from b"""
-        return {"result": a - b}
-
-    @get('/divide', )
-    def divide(self, a: int, b: int):
-        """Divides a by b"""
-        return {"result": a / b}
-
-    @get('/multiple', )
-    def multiple(self, a: int, b: int):
-        """Multiples a with b"""
-        return {"result": a * b}
-
+Full installation
+```shell
+pip install ellar-cli[full]
 ```
 
-Create another file `server.py`:
-
-```Python
-from ellar.core import AppFactory
-from ellar.openapi import OpenAPIDocumentBuilder, OpenAPIDocumentModule
-from .controller import router, MathAPI
-
-
-app = AppFactory.create_app(routers=(router, ), controllers=(MathAPI, ))
-
-document_builder = OpenAPIDocumentBuilder()
-document_builder.set_title('Your Title')\
-    .set_version('1.0.2')\
-    .set_contact(name='Eadwin', url='https://www.yahoo.com', email='[email protected]')\
-    .set_license('MIT Licence', url='https://www.google.com')
-
-document = document_builder.build_document(app)
-module = app.install_module(OpenAPIDocumentModule, document=document)
-module.setup_swagger_doc()
-```
+## Usage
 
-### Start up Server
-```bash
-uvicorn server:app --reload
+```shell
+ellar --help
 ```
-
-### Interactive API docs
-
-Now go to <a href="http://localhost:8000/docs/" target="_blank">http://localhost:8000/docs/</a>
-
-You will see the automatic interactive API documentation (provided by <a href="https://github.com/swagger-api/swagger-ui" target="_blank">Swagger UI</a>):
-
-![Swagger UI](img/ellar_demo.gif)
-
-## Status
-
-Project is still in development
-
-- Documentation - in progress
-- Database Plugin with [Encode/ORM](https://github.com/encode/orm)
-- Caching 
-- API Throttling

docs/new-command.md

@@ -0,0 +1,49 @@
+
+This command will help you kickstart your new Ellar project by creating a new project with a directory structure and other required files necessary for ellar to properly manage your project.
+
+```shell
+ellar new my-project
+```
+
+will create a folder as follows:
+```angular2html
+my-package
+├── pyproject.toml
+├── README.md
+├── my_project
+|    ├── apps
+|    |   └── __init__.py
+|    ├── core
+|    ├── domain
+|    └── __init__.py
+|    └── config.py
+|    └── root_module.py
+|    └── server.py
+└── tests
+    └── __init__.py
+```
+If you want to name your project differently than the folder, you can pass the `--project-name` option:
+
+```shell
+ellar new my-project --project-name john-doe
+```
+will create a folder as follows:
+```angular2html
+my-package
+├── pyproject.toml
+├── README.md
+├── john_doe
+|    ├── apps
+|    |   └── __init__.py
+|    ├── core
+|    ├── domain
+|    └── __init__.py
+|    └── config.py
+|    └── root_module.py
+|    └── server.py
+└── tests
+    └── __init__.py
+```
+
+### New Command CLI Options
+- `--project-name` Set the resulting project module name. Defaults to folder-name is not provided.

docs/runserver-command.md

@@ -0,0 +1,23 @@
+
+This is command is a wrapper around `uvicorn` ASGI server. it helps to create a link necessary for `uvicorn` to run your ellar application properly.
+```shell
+ellar runserver --reload
+```
+will product the following output:
+```shell
+INFO:     Will watch for changes in these directories: ['/home/user/working-directory']
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [2934815] using WatchFiles
+INFO:     APP SETTINGS MODULE: john_doe.config:DevelopmentConfig
+INFO:     Started server process [2934818]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+### Runserver CLI Options
+```shell
+ellar runserver --help
+```
+OR
+
+Please check `Uvicorn` CLI [Options](https://uvicorn.org/#command-line-options)

ellar_cli/__init__.py

@@ -1,3 +1,3 @@
 """Ellar CLI Tool for Scaffolding Ellar Projects, Modules and also running Ellar Commands"""
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"

ellar_cli/constants.py

@@ -0,0 +1 @@
+ELLAR_META = "ELLAR_META"