Metadata-Version: 2.1
Name: tinyrouter
Version: 0.1.4
Summary: UNKNOWN
Home-page: https://github.com/tcantalice/tiny-router
Author: Tarcisio Cantalice
Author-email: tarcisiocantalice@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Framework :: Flask
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
Requires-Dist: flask

# Tiny Router
Tiny Router Ã© um roteador de caminhos para aplicaÃ§Ãµes [Flask](https://github.com/pallets/flask). A biblioteca centraliza a definiÃ§Ã£o e gerenciamento das rotas utilizadas na aplicaÃ§Ã£o, criar, editar, remover ou trocar controladores facilmente evitando conflitos.

- [Criando rotas](#criando-rotas)
- [Registrando rotas](#registrando-rotas)
- [FunÃ§Ãµes Helper](#funÃ§Ãµes-helper)
    - [MÃ©todos HTTP](#mÃ©todos-http)
    - [PrÃ©fixos](#prÃ©fixos)
- [Dicas de uso](#dicas-de-uso)

## Criando rotas

Uma rota Ã© representada pela classe ```Route```. Ela possui os seguinte atributos:

* **endpoint** - Nome utilizado para identificar a rota. Em caso de endpoints com mÃºltiplos termos, recomendado separÃ¡-los por ponto ou sublinhado.
* **rule** - Caminho para um recurso especÃ­fico
* **view** - FunÃ§Ã£o ou classe que irÃ¡ manipular a requisiÃ§Ã£o
* **methods** - MÃ©todos HTTP para chamada da rota (Default: ```{'GET'}```)
* **parameters** - ParÃ¢metros que podem ser passados na url.

Ao criar uma rota apenas sÃ£o obrigatÃ³rios ```endpoint```, ```rule``` e ```view```.

Exemplo de uma rota simples:
```python
from tinyrouter import Route
from views import user_index

Route('user.index', '/user', user_index)
```
Por padrÃ£o, as rotas sÃ£o definidas para aceitas apenas o mÃ©todo ```GET```. Entretanto outros mÃ©todos podem ser definidos, ou atÃ© mais de um.
```python
from tinyrouter import Route
from views import user_index

# DefiniÃ§Ã£o dos mÃ©todos
methods = ['GET', 'POST']

Route('user.index', '/user', user_index, methods)
```
## Registrando as rotas

Primeiro cria-se uma instÃ¢ncia do roteador
```python
from flask import Flask
from tinyrouter import Router

app = Flask(__name__)
router = Router(app)
```

E invoca o mÃ©todo ```register``` passando a lista de rotas que deseja registrar na aplicaÃ§Ã£o
```python
'''
ImportaÃ§Ã£oes anteriores
'''
from my_app.routes import routes

'''
 InstÃ¢ncia da aplicaÃ§Ã£o e do roteador
'''
router.register(routes)
```

Pronto! As rotas agora estÃ£o registradas na aplicaÃ§Ã£o.

Ã‰ possÃ­vel registrar vÃ¡rios grupos de rotas.
```python
from webapp.routes import routes as web_routes
from api.routes import routes as api_routes

router.register(web_routes)
router.register(api_routes)
```
Ou ainda...
```python
router.register(web_routes, api_routes)
```

## FunÃ§Ãµes Helper
### **MÃ©todos HTTP**
Criar uma rota que aceite apenas uma mÃ©todo HTTP utilizando Route fica da seguinte forma:
```python
# ImportaÃ§Ã£o da view...
from tinyrouter import Route


Route('cliente.create', '/cliente', cliente_create, ['POST'])
```
Entretanto esse processo pode ser encurtado com os helpers de mÃ©todos.
Utilizando os helpers, o exemplo acima ficaria assim:
```python
# ImportaÃ§Ã£o da view...
from tinyrouter.helpers import route_post as post

post('cliente.create', '/cliente', cliente_create)
```
O resultado serÃ¡ exatamente o mesmo. Os mÃ©todos suportados sÃ£o:
- GET
- POST
- PUT
- DELETE


### **PrÃ©fixos**
Agrupar rotas de acordo com o recurso ou contexto utilizando o Route pode ser um pouco verboso, como por exemplo, rotas associadas ao recurso Cliente.

**[GET] - /cliente/** (Lista todos os Clientes)<br>
**[POST] - /cliente/** (Cria um novo registro de Cliente)<br>
**[GET] - /cliente/{id}** (Recupera um registro especÃ­fico de Cliente)<br>
**[PUT] - /cliente/{id}** (Atualiza um registro especÃ­fico de Cliente)<br>
**[DELETE] - /cliente/{id}** (Deleta um registro especÃ­fico de Cliente )

Ã‰ possÃ­vel notar que para cada um dos endpoints foi necessÃ¡rio pÃ´r o nome do recurso (Cliente) como prÃ©fixo. Utilizando o helper de prÃ©fixo esse trabalho nÃ£o serÃ¡ mais necessÃ¡rio. A funÃ§Ã£o recebe o prÃ©fixo a ser adicionado e as rotas que receberÃ£o o mesmo. Exemplo:

```python
# ImportaÃ§Ã£o das views
from tinyrouter.helpers import route_prefix as prefix
from tinyrouter.helpers import (route_get as get,\
                                route_post as post,\
                                route_put as put,\
                                route_delete as delete)

*prefix('cliente', 
        get('cliente.all', '/', cliente_all),
        post('cliente.create', '/', cliente_create),
        put('cliente.udpate', '/<id>', cliente_update),
        get('cliente.show'), '/<id>', cliente_show),
        delete('cliente.delete', '/<id>', cliente_delete)
    )
```
NOTA: *Ao utilizar o route_prefix Ã© necessÃ¡rio pÃ´r um * na frente da funÃ§Ã£o pois Ã© retornado uma coleÃ§Ã£o de rotas alteradas, e este artifÃ­cio garante que as rotas serÃ£o "desempacotadas". Entretanto nÃ£o impede que as novas rotas sejam armazenadas em uma variÃ¡vel.*

Ã‰ possÃ­vel tambÃ©m utilizar aninhamentos do ```route_prefix```
```python
# ImportaÃ§Ãµes...

*prefix('sistema', 
    *prefix('cliente',
        ...
    )
)
```
Com isso Ã© possÃ­vel agrupar diversos contextos com um mesmo prÃ©fixo sem a necessidade de definir por extenso um a um.

## Dicas de Uso
1. Utilizar um arquivo de rotas para cada parte da aplicaÃ§Ã£o. Exemplo:
```python
# ./clientes/routes.py
from tinyrouter import Route
from .views

routes = [
    *route_prefix('/cliente',
        Route('cliente.index', '/', views.index),
        Route('cliente.show', '/<int:id>', views.show),
        Route('cliente.create', '/create', views.create, ['GET', 'POST'])
    )
]
```
```python
# ./app.py
from flask import Flask
from tinyrouter import Router
from clientes.routes import routes as rotas_clientes

app = Flask(__name__)
router = Router(app)
router.register(rotas_clientes)
```

