GitLocker: The Coding Marketplace

Description:

bravaweb 0.0.21

BravaWeb Framework for ASGI Server
Framework para aplicações WEB baseada em Python3 ASGI (Asynchronous Server Gateway Interfac em Uvicorn), com possibilidade de utilização de Template em Html (Mako Templates).
Veja Documentação em:
Uvicorn: https://www.uvicorn.org/
Mako Templates: https://www.makotemplates.org/
Instalação
Instalação utilizando Pip
pip install bravaweb

Git/Clone
git clone https://github.com/robertons/bravaweb
cd bravaweb
pip install -r requirements.txt
python setup.py install

Primeiros Passos
Inicie seu projeto conforme estrutura abaixo
app
├── ...
├── configuration
│ ├── __init__.py
│ └── api.py
└── server.py

O arquivo de configurações deve conter os seguintes dados:

variável
tipo
obrigatório
descrição

directory
string
sim
Caminho Projeto

encoding
string
sim
Codificação

date_format
string
sim
Formato data

short_date_format
string
sim
Formato data curta

token
string
sim
Token codificação Authorization Header

domains
array
sim
Domínios autorizados a acessar

access_exceptions
array
sim
Rotas e Exceções de acesso

routes
array
sim
Rotas do Projeto

configuration/__init__.py

# -*- coding: utf-8 -*-

from configuration import api

configuration/api.py

# -*- coding: utf-8 -*-

import os

# Directory
directory = os.path.abspath(os.path.join(os.path.dirname(os.path.realpath(__file__)), os.pardir))

# Api Encoding
encoding = "utf-8"

# Date Format
date_format = "%d/%m/%Y %H:%M:%S"
short_date_format = "%d/%m/%Y"

# Token Authorization
token = "JWT-Token-Project"

# Authorized Domains Origin/Referrer
domains = [
"https://www.dominio.com.br",
"https://alias.dominio.com.br",
]

# Exceptions Routes
access_exceptions = [

{'path': '(^/default/)','referer': '*'},

{'path': '(/rota/especifica/)','referer': '(^https://dominio.especifico.com.br/)'},

{'path': '*', 'referer': "(^https://outro.dominio.com.br/)|(^https://adicional.dominio.com.br/)"},
]

routes = [
("{controller}/{area}/{module}/{action}/{id}", '(^/admin/)|(^/panel/)',
("{controller}/{module}/{action}/{id}", ""),
]

Definições:
domains: lista array de strings, com domínios que tem acesso a api, o teste é feito baseado no origin e/ou referrer de cada requisição.
access_exceptions: é possivel que algumas rotas sejam abertas para qualquer requisição, ou mesmo que alguma rota seja especifica para algum domínio. A lista deve conter um dicionário com as chaves path e referer onde:
path: é referente ao caminho da rota
referer: origem da requisição

Ambos os valores aceitam * para todos ou expressão regular para teste de string.
routes: lista com tuplas que definem as rotas padrões do projeto. Bravaweb esta preparado para até 4 níveis de profundidade que definem, Controlador, Area, Modulo, Ação e mais um nível opcional para captação de ID, a prioridade das regras é sequencial, portanto as regras específicas devem vir primeiro. A tupla é definida assim:
0: a captação de cada parte da profundidade para carregamento
1: expressão regular para identificar a regra

Por padrão os valores de rota do ambiente são:
controller = None
area = None
module = "default"
action="index"
id = None

Por fim vamos criar a execução do projeto que vai tratar as requisições e processar as rotas.
O arquivo server.py na raiz deve ficar assim:
#-*- coding: utf-8 -*-
import sys

import configuration

from bravaweb import App as application

Acesse o diretório do seu projeto, e execute o comando de serviço do ASGI, conforme documentação do Uvicorn, no exemplo abaixo ativamos o ambiente virtual onde os pacotes estão instalados:
source ../env/bin/activate

uvicorn server:application --port 8080 --interface=asgi3 --workers 7 --proxy-headers --lifespan off --reload

O Resultado então será:
INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
INFO: Started reloader process [82503] using statreload
INFO: Started server process [82505]
.
.
.

Neste momento sua aplicação estará em execução. Nós configuramos as rotas mas não desenvolvemos nenhuma delas portanto qualquer requisição na url http://127.0.0.1:8080 irá retornar 404.
Hello World
Vamos iniciar aplicando a rota default, a pasta do projeto nesse momento deverá estar assim:
app
├── ...
├── configuration
│ ├── __init__.py
│ └── api.py
├── controllers
│ └── default.py
└── server.py

Conforme exemplificado a rota default(padrão) é
controller = None
area = None
module = "default"
action="index"
id = None

O arquivo ficará assim:
controllers/default.py

# -*- coding: utf-8 -*-
from bravaweb.controller import *

class DefaultController(Controller):

@get
async def index(self) -> Json:
await View(self.enviroment, data={"mensagem": 'Olá Mundo'})

Analisando a rota default:
Nome do Controlador é default, por isso nome da classe é DefaultController, herdando o controlador do framework (Controller)
O metodo de request aceito para esta rota é o GET (@get) , mas POST (@post) , PUT(@put) e DELETE(@delete) também são aceitos. Uma requisição diferente do permitido para rota retorna Erro 405: Method not allowed
O Framwork é baseado em ASGI (Asynchronous Server Gateway Interface) por isso ação index é assíncrona (async) .
A anotação é o tipo de resultado que essa rota irá retornar, posteriormente veremos sobre os tipos, no exemplo acima utilizamos Json.
Todos os dados da requisição, estão na enviroment, veremos mais logo a seguir.
Para melhor compreenção sobre as rotas , vejamos os exemplos abaixo baseado no arquivo de configuração acima:
Criando e Configurando Rotas
Os padrões de rota é configurado no arquivo de configurações em routes. Você provavelmente fará isso somente uma vez, ou quando for necessária a criação de rotas específicas em seu projeto. Abaixo segue alguns exemplos baseado na configuração que apresentamos.
Exemplo 1
GET -> api.dominio.com.br/admin/catalog/products/list

A regra identificada é a primeira da lista, pois o path da request inicia com /admin/ conforme expressão regular da posição [1] da tupla em configuration.api.routes:
("{controller}/{area}/{module}/{action}/{id}", '(^/admin/)|(^/panel/)'

O resultado da captação da rota conforme posição [0] da tupla será:
controller = 'admin'
area = 'catalog'
module = 'products'
action = 'list'

A estrutura para processamento desta rota devera ser:
app
├── ...
├── controllers
│ └── admin
│ │ └── catalog
│ │ | └── products.py

O arquivo :
controllers/admin/catalog/products.py

# -*- coding: utf-8 -*-
from bravaweb.controller import *

class ProductsController(Controller):

@get
async def list(self) -> Json:
await View(self.enviroment, data=[{"prod_nome": 'Exemplo'}])

Exemplo 2
POST -> api.dominio.com.br/site/product/like/110

A regra identificada é a default (segunda da lista), pois o path da request não contempla as expressões regulares anteriores :
("{controller}/{module}/{action}/{id}", "")

O resultado da captação da rota conforme posição [0] da tupla será:
controller = 'site'
area = None
module = 'product'
action = 'like'
id = 110

A estrutura para processamento desta rota devera ser:
app
├── ...
├── controllers
│ └── site
│ │ └── product.py

O arquivo:
controllers/site/products.py

# -*- coding: utf-8 -*-
from bravaweb.controller import *

class ProductController(Controller):

@post
async def like(self) -> Json:
await View(self.enviroment, data=[{"likes": 535}])

Ambiente / Enviroment
A qualquer momento dentro do controlador é possivel acessar os dados da requisição através de self.enviroment os dados disponíves são:

Campo
Tipo
descrição

origin
string
Origem ou Referrer da Requisição

remote_ip
string
Ip do usuário

remote_uuid
string
UUID se informado no header

browser
string
Browser do usuário

accept_encoding
string
tipos de codificação aceito pelo browser

method
string
metodo da requisição (GET, POST, PUT ou DELETE)

response_type
string
tipo de resposta esperada para requisição

authorization
string
Token JWT - Bearer enviado no Header

bearer
string
Token JWT decodificado

content_length
int
Tamanho da requisição

get
dict
Dados enviados por querystring

post
dict
Dados enviados por post

body
bytes
Bytes do corpo da requisição

route
string
rota

controller
string
nome controlador

area
string
nome area do controlador

module
string
nome modulo do controlador

action
string
nome da ação do modulo

id
string
identificador da requisição

Há disponível também, para casos de manipulação específica os dados brutos do ASGI:

Campo
descrição

headers
cabeçalho da requisição

scope
escopo da requisição

send
conexão com navegador

receive
dados recebidos

Entradas e Pré-condições
Para maior segurança no processamento das rotas é possível e recomendável estabelecer as pré-condições daquela rota específica. Caso a requisição não tenha o objeto ou objeto informado seja inválido, haverá erro de resposta com erro 412: Precondition Failed
@post
async def comment(self, id_product:int, comment:string ) -> Json:
sql_query = f"INSERT INTO products_comments (prod_comment, id_product) VALUES ('{comment}',{id_product})";
.
.
.
await View(self.enviroment, data=[{"added": true}])

Caso a request não contenha os parametros acima, a ação não será executada.
É possível requerer objetos específicos, Bravaweb realiza o cast automático dos dados enviados, no caso datetime o parametro de conversão esta estabelecido no arquivo de configuração nos campos date_format e short_date_format.
from datetime import datetime
from decimal import Decimal
.

@post
async def comment(self, id_product:int, comment:string, date:datetime, stars:Decimal) -> Json:
.
.
.
.
.
.
await View(self.enviroment, data=[{"added": true}])

View
Toda rota deve retornar uma view, que será baseada na anotação a action.
await View(self.enviroment, data=_response_data)

Bravaweb possui tratamento específico para respostas Json e HTML, ambos possuem um modelo ou carregamento de template para resposta.
A View possui os seguintes campos de entrada

entrada
obrigatório
tipo
descrição

enviorment
sim
bravaweb.enviroment
ambiente da requisição

data
sim
bytes-like, dict, list, string
dados da resposta de acordo com anotação

success
não
boolean
sucesso na execução da action

token
não
string
auth token, caso não informado, havendo token no enviroment, o mesmo se repetirá

task
não
dict, list, string
dados sobre execução em segundo plano

error
não
dict, list, string
mensagem de erro

Anotações e Tipos de Resposta

tipo
Entrada

Html
dict

Css
bytes-like object

Csv
bytes-like object

JavaScript
bytes-like object

Jpg
bytes-like object

Json
dict, list, string

Mp4
bytes-like object

Pdf
bytes-like object

Png
bytes-like object

TextPlain
bytes-like object

Xml
bytes-like object

Json
O template Json é composto da seguinte forma:
Json = {
"token": "",
"success": True,
"date": "",
"itens": 0,
"data": [],
}
Onde os dados respondidos estarão dentro de "data".
@get
async def index(self) -> Json:
await View(self.enviroment, data=[{"added": true}])

HTML e Template Mako
Para mais informações sobre a criação de templates Mako acesse: https://www.makotemplates.org/
A estrutura das Views HTML desenvolvidas em Mako devem estar assim:
app
├── ...
├── configuration
├── controllers
├── views
│ └── shared
│ | └── default.html
└── server.py

Quando não há uma view definida para rota, o template padrão a ser carregado será o default.
é possível criar views específicas para cada rota conforme exemplo abaixo:
Rota: /product/detail
@get
async def index(self) -> Html:
await View(self.enviroment, data=[{"added": true}])

Template:
app
├── ...
├── configuration
├── controllers
├── views
│ └── product
│ | └── detail
│ | | └── index.html
│ └── shared
└── server.py

Decoradores
Bravaweb é compatível com encapsulamento através de decorador e a criação deve seguir o modelo abaixo:
Decorador de Método Síncrono:
def decorator_example(f):
def example_decorator(cls, **args) -> f:
return f(cls, **args)
return example_decorator

Decorador de Método Assíncrono:
def decorator_example_async(f):
async def example_decorator(cls, **args) -> f:
return await f(cls, **args)
return example_decorator

O uso do decorador em um método síncrono ficaria assim:
@decorator_example
def __init__(self):
.
.

O uso do decorador em uma rota ficaria assim:
@decorator_example_async
async def index(self) -> Html:
await View(self.enviroment, data=_response_data)

É possível também criar decorar para um controlador inteiro, a função "decora" todos os métodos executáveis, observe que os métodos padrões de classe init e del são métodos síncronos e por isso o decorador síncrono, e demais métodos (actions) com decorador assíncrono.
def decorator_example_klass():
def decorate(cls):
for attr in cls.__dict__:
_method = getattr(cls, attr)
if hasattr(_method, '__call__'):
if attr == "__init__" or attr == "__del__":
setattr(cls, attr, example_decorator(_method))
else:
setattr(cls, attr, decorator_example_async(_method))
return cls
return decorate

Erros:
A qualquer momento no processamento da sua rota é possível responder com as seguintes mensagens de erro:

Metoto
Código de Resposta
Mensagem

NoContent
204
204: No Content

Unauthorized
401
401: Unauthorized

NotFound
404
404: Not Found

NotAllowed
405
405: Method not allowed

PreconditionFailed
412
412: Precondition Failed

InternalError
500
500: Internal Error

Exemplo requisição de um arquivo pdf:
import os.path

@get
async def index(self, file_path:str) -> Pdf:
if os.path.exists(file_path):
_file_data = open(file_path,'r')
await View(self.enviroment, data = _file_data.read())
else:
self.NotFound()

License
MIT