`microdot` — framework HTTP minimalista#

O Microdot é um pequeno framework HTTP para MicroPython inspirado no Flask. É executado sobre asyncio, gere múltiplos clientes concorrentes sem utilizar threads, e expõe uma API familiar baseada em decoradores de rotas. Uma aplicação mínima tem o seguinte aspeto:

from microdot import Microdot

app = Microdot()

@app.route('/')
async def index(request):
    return 'Hello, world!'

app.run(host='0.0.0.0', port=80)

class Microdot#

class microdot.Microdot#

Uma instância de aplicação HTTP. Constrói-se uma instância perto do início do script e decora-se com handlers de rotas; chamar run() ou aguardar start_server() inicia o serviço.

Registo de rotas

route(url_pattern: str, methods: list | None = None) → Callable#

Decorador que regista um handler para url_pattern sob os métodos HTTP indicados (predefinição ['GET']). Devolve o decorador que, quando aplicado a uma função, a regista como handler e devolve a função inalterada.

url_pattern: Um padrão de caminho. Suporta segmentos estáticos (/users) e segmentos dinâmicos delimitados por < / >. Os segmentos dinâmicos aceitam um prefixo de tipo opcional separado por : – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. O tipo predefinido é string.
methods: Lista de nomes de métodos HTTP. Se omitida, apenas GET é correspondido.

O handler é chamado com o objeto de pedido em primeiro lugar, seguido de quaisquer segmentos dinâmicos capturados como argumentos de palavra-chave. O valor de retorno do handler torna-se a resposta HTTP: um Response, uma string, um tuplo (body, status_code[, headers]), ou um dict / lista (enviado como JSON).

get(url_pattern: str) → Callable#: Alias de conveniência para route(url_pattern, methods=['GET']) – regista a função decorada como handler GET para url_pattern. Devolve o decorador.

post(url_pattern: str) → Callable#: Alias de conveniência para route(url_pattern, methods=['POST']) – regista a função decorada como handler POST para url_pattern. Devolve o decorador.

put(url_pattern: str) → Callable#: Alias de conveniência para route(url_pattern, methods=['PUT']) – regista a função decorada como handler PUT para url_pattern. Devolve o decorador.

patch(url_pattern: str) → Callable#: Alias de conveniência para route(url_pattern, methods=['PATCH']) – regista a função decorada como handler PATCH para url_pattern. Devolve o decorador.

delete(url_pattern: str) → Callable#: Alias de conveniência para route(url_pattern, methods=['DELETE']) – regista a função decorada como handler DELETE para url_pattern. Devolve o decorador.

Hooks de ciclo de vida

before_request(f: Callable) → Callable#: Decorador que regista f para ser executada antes de cada pedido. f recebe o objeto de pedido; o seu valor de retorno é normalmente ignorado. Para curto-circuitar o pedido, retorne um Response (ou um valor que seja convertível para um) – o restante pipeline é então ignorado e essa resposta é enviada. Devolve f inalterada.

after_request(f: Callable) → Callable#: Decorador que regista f para ser executada após cada pedido bem-sucedido. f recebe (request, response) e deve devolver o objeto de resposta (possivelmente modificado). Devolve f inalterada.

after_error_request(f: Callable) → Callable#: Decorador que regista f para ser executada após o Microdot gerar uma resposta de erro (404, 500, exceção lançada, etc.). f recebe (request, response) e deve devolver o objeto de resposta (possivelmente modificado). Devolve f inalterada.

errorhandler(status_code_or_exception_class) → Callable#: Decorador que regista um handler personalizado para um código de estado HTTP ou uma classe de exceção Python. Para códigos de estado, o handler recebe apenas o pedido; para classes de exceção, (request, exception). Devolve o decorador.

Montagem e abortar

mount(subapp: Microdot, url_prefix: str = '', local: bool = False) → None#: Associa as rotas de outra instância Microdot sob url_prefix. Quando local é False (predefinição), os handlers before / after / error da sub-aplicação também são associados ao pai. Quando True, esses handlers são executados apenas para as rotas da sub-aplicação. Devolve None.

static abort(status_code: int, reason: str | None = None) → None#

Lança HTTPException para abortar o pedido atual com o código de estado indicado. Nunca retorna normalmente – o framework captura a exceção e converte-a na resposta de erro correspondente. Conveniente no interior de corpos de rota:

from microdot import abort

@app.get('/users/<int:id>')
def get_user(request, id):
    user = lookup(id)
    if user is None:
        abort(404)
    return user.to_dict()

Executar o servidor

run(host: str = '0.0.0.0', port: int = 5000, debug: bool = False, ssl=None) → None#

Bloqueia a thread de chamada, executa asyncio.run() sobre start_server(). Devolve None apenas após shutdown() ter sido chamado e o ciclo de escuta terminar. A forma mais simples de lançar uma aplicação autónoma:

app.run(host='0.0.0.0', port=80)

async start_server(host: str = '0.0.0.0', port: int = 5000, debug: bool = False, ssl=None, start_serving: bool = True) → None#

Inicia o servidor como uma corrotina. Use isto ao integrar com um ciclo de eventos asyncio existente juntamente com outras tarefas. A corrotina não retorna até shutdown() ser chamado:

async def main():
    await asyncio.gather(
        app.start_server(port=80),
        capture_loop(),
    )

host: Interface de rede a escutar. '0.0.0.0' (predefinição) significa todas as interfaces; '127.0.0.1' significa apenas loopback.
port: Porta TCP a escutar. Predefinição 5000 – use 80 para HTTP simples, 443 para HTTPS.
debug: Se True, regista cada pedido e imprime tracebacks para stdout.
ssl: Um ssl.SSLContext para envolver as ligações recebidas em TLS. None (predefinição) significa HTTP simples.
start_serving: Relevante apenas no CPython; ignorado no MicroPython.

shutdown() → None#: Solicita um encerramento gracioso do servidor. Seguro para chamar a partir de um handler de rota – o pedido atual é concluído antes do ciclo terminar. Retorna imediatamente; o encerramento efetivo ocorre assim que o pedido em curso terminar.

Atributos

url_map: list#: Lista de rotas registadas como tuplos (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list#: Lista de chamáveis registados com before_request(), por ordem de registo. Cada um é executado com o objeto de pedido antes do handler de rota. Alterar a lista diretamente é possível, mas raramente necessário – prefira o decorador.

after_request_handlers: list#: Lista de chamáveis registados com after_request(), por ordem de registo. Cada um é executado com (request, response) após um pedido bem-sucedido e deve devolver a resposta (possivelmente modificada).

after_error_request_handlers: list#: Lista de chamáveis registados com after_error_request(), por ordem de registo. Cada um é executado com (request, response) após ser gerada uma resposta de erro (pelo framework ou por um handler de erro da aplicação) e deve devolver a resposta.

error_handlers: dict#: Mapeamento de chaves de erro para chamáveis de handler, preenchido por errorhandler(). As chaves são códigos de estado HTTP (int) ou classes de exceção Python; os valores são os handlers registados. Os handlers de código de estado recebem (request); os handlers de classe de exceção recebem (request, exception).

debug: bool#: True enquanto o servidor está em execução com debug=True.

class Request#

class microdot.Request#

Um pedido HTTP recebido. As instâncias são passadas aos handlers de rota como primeiro argumento posicional. As aplicações não constroem Request diretamente.

Atributos de classe

max_content_length: int#: Rejeita pedidos cujo Content-Length exceda este número de bytes com uma resposta 413. Predefinição 16 KB.

max_body_length: int#: Maior corpo que é armazenado em memória e exposto via body. Corpos maiores (até max_content_length) permanecem no socket e devem ser lidos através de stream. Predefinição 16 KB.

max_readline: int#: Comprimento máximo de uma linha de pedido / linha de cabeçalho em bytes. Predefinição 2 KB.

Atributos de instância

app: Microdot#: A instância Microdot que trata o pedido.

client_addr: tuple#: O endereço do cliente como (host, port).

method: str#: String do método HTTP ('GET', 'POST', …).

scheme: str#: 'http' ou 'https'.

url: str#: O URL completo do pedido, incluindo caminho e query string (tudo após o host).

path: str#: Apenas a parte do caminho.

query_string: str | None#: A parte da query string em bruto, ou None.

args: MultiDict#: Query string analisada como MultiDict.

headers: NoCaseDict#: Cabeçalhos do pedido como NoCaseDict (pesquisa insensível a maiúsculas/minúsculas).

cookies: dict#: Cabeçalho Cookie analisado como dict.

content_length: int#: O valor inteiro de Content-Length, ou 0 se ausente.

content_type: str | None#: O valor do cabeçalho Content-Type, ou None.

g: object#: Um contentor de livre forma por pedido (um objeto simples). Atribua-lhe atributos para passar valores entre hooks e handlers (request.g.user = ...).

route: Callable#: A função de handler que correspondeu a este pedido.

url_prefix: str#: Prefixo sob o qual a rota foi montada, ou ''.

subapp: Microdot | None#: A instância da sub-aplicação montada, ou None.

Acesso ao corpo

body: bytes#: O corpo completo do pedido como bytes. Vazio quando o corpo está a ser transmitido em stream (ver stream).

stream: object#: Um objeto de stream assíncrono que expõe read() sobre o corpo. Use isto para corpos maiores que max_body_length.

json: dict | list | str | int | float | bool | None#: O corpo analisado como JSON (um dict, list, str, int, float, ou bool – o que o payload codificar), ou None se o Content-Type não for application/json.

form: MultiDict | None#: Campos de formulário com codificação URL como MultiDict, ou None. Para multipart/form-data, decore a rota com microdot.multipart.with_form_data().

files: dict | None#: Ficheiros carregados como {name: FileUpload}, preenchido por microdot.multipart.with_form_data(). None até o decorador ser executado.

after_request(f: Callable) → Callable#: Regista um hook after-request local ao pedido – executado após os handlers after-request ao nível da aplicação, apenas em caso de sucesso. f recebe (request, response) e deve devolver o objeto de resposta (possivelmente modificado). Devolve f inalterada.

class Response#

class microdot.Response(body=b'', status_code: int = 200, headers: dict | None = None, reason: str | None = None)#

Uma resposta HTTP. A maioria dos handlers devolve valores que o Microdot converte automaticamente para Response; construa um diretamente quando precisar de cabeçalhos personalizados ou de um código de estado específico.

body: Corpo da resposta. str é codificado em UTF-8; dict / list é codificado como JSON e o Content-Type é definido em conformidade; bytes é enviado tal como está; um objeto do tipo ficheiro ou um gerador assíncrono transmite em stream.
status_code: Estado HTTP numérico. Predefinição 200.
headers: Dict de cabeçalhos de resposta (insensível a maiúsculas/minúsculas).
reason: Frase de razão personalizada. Predefinição "OK" para 200 e "N/A" caso contrário.

Atributos de classe

default_content_type: str#: Content-Type utilizado quando nenhum é definido explicitamente. Predefinição 'text/plain'.

default_send_file_max_age: int | None#: Valor de Cache-Control: max-age para send_file() quando max_age não é fornecido. None (predefinição) significa sem cabeçalho Cache-Control.

send_file_buffer_size: int#: Tamanho do bloco para streaming em send_file(). Predefinição 1024.

already_handled: None#: Sentinela devolvido por handlers que já escreveram a resposta diretamente (utilizado por upgrades WebSocket). Sempre None; é a identidade que importa.

types_map: dict#: Mapa de extensão para tipo MIME utilizado por send_file() para inferência de tipo de conteúdo. Mapeia css, gif, html, jpg, js, json, png, txt, svg.

Métodos

set_cookie(cookie: str, value: str, path: str | None = None, domain: str | None = None, expires=None, max_age: int | None = None, secure: bool = False, http_only: bool = False, partitioned: bool = False) → None#: Adiciona um cabeçalho Set-Cookie. expires pode ser uma string pré-formatada ou um objeto semelhante a datetime com timetuple(). Devolve None; o cabeçalho é acrescentado a esta resposta no local.

delete_cookie(cookie: str, **kwargs) → None#: Define um Set-Cookie que expira o cookie indicado imediatamente. kwargs aceita as mesmas opções que set_cookie() (path, domain, secure, http_only, partitioned); expires e max_age são ignorados. Devolve None; o cabeçalho é acrescentado a esta resposta no local.

classmethod redirect(location: str, status_code: int = 302) → Response#

Devolve uma resposta de redirecionamento:

@app.get('/old')
def old(request):
    return Response.redirect('/new')

classmethod send_file(filename: str, status_code: int = 200, content_type: str | None = None, stream=None, max_age: int | None = None, compressed: bool | str = False, file_extension: str = '') → Response#: Transmite em stream um ficheiro do sistema de ficheiros como corpo da resposta. content_type é inferido a partir da extensão via types_map se não for fornecido. compressed=True define Content-Encoding: gzip (o ficheiro já deve estar comprimido).

Aviso
filename é aberto diretamente. Nunca passe um caminho fornecido pelo utilizador sem sanitização – fazer isso permite a divulgação arbitrária de ficheiros.

Exceções#

exception microdot.HTTPException#

Lançada por abort() para curto-circuitar um pedido com um código de estado específico. O Microdot captura esta exceção e converte-a na resposta de erro correspondente.

status_code: int#: Código de estado HTTP numérico a devolver – o valor passado a abort().

reason: str#: Frase de razão a incluir na resposta de erro. Se não for fornecida a abort(), tem como predefinição "<status_code> error" (por exemplo, "404 error").

class URLPattern#

class microdot.URLPattern(url_pattern: str)#

A forma compilada do padrão de URL de uma rota. Construído automaticamente por Microdot.route(); as aplicações raramente instanciam um diretamente.

classmethod register_type(type_name: str, pattern: str = '[^/]+', parser: Callable | None = None) → None#

Regista um novo tipo de segmento dinâmico para utilização em padrões de rota. Devolve None; o tipo é adicionado ao registo de tipos ao nível da classe. Por exemplo, para adicionar um tipo <uuid:...>

URLPattern.register_type('uuid', '[0-9a-f-]{36}')

parser é um chamável opcional que converte a string capturada antes de esta chegar ao handler.

match(path: str) → dict | None#: Faz a correspondência de path com o padrão e devolve um dict de grupos capturados, ou None se não houver correspondência.

Classes auxiliares#

class microdot.MultiDict(initial_dict: dict | None = None)#

Uma subclasse de dict que armazena múltiplos valores por chave. Utilizada para query strings e corpos de formulário com codificação URL onde a mesma chave pode aparecer mais do que uma vez (?tag=a&tag=b).

get(key, default=None, type: Callable | None = None)#: Devolve o primeiro valor para key, opcionalmente convertido com type (um chamável). Devolve default se a chave estiver ausente ou a conversão falhar; caso contrário, devolve o valor (opcionalmente convertido).

getlist(key, type: Callable | None = None) → list#: Devolve todos os valores para key como uma lista, opcionalmente com cada valor convertido por type. Devolve uma lista vazia se key não estiver presente.

class microdot.NoCaseDict#: Uma subclasse de dict com chaves de string insensíveis a maiúsculas/minúsculas. Utilizada para Request.headers e Response.headers.

Funções ao nível do módulo#

microdot.abort(status_code: int, reason: str | None = None) → None#: Atalho para Microdot.abort(). Nunca retorna normalmente – lança HTTPException. Importável como from microdot import abort.

microdot.redirect(location: str, status_code: int = 302) → Response#: Atalho para Response.redirect(). Importável como from microdot import redirect.

microdot.send_file(filename: str, **kwargs) → Response#: Atalho para Response.send_file().

microdot.urlencode(s: str) → str#: Codifica em percentagem um componente de URL. Substitui caracteres com significado reservado num URL (/, ?, &, =, #, espaço, …) pelos seus escapes hexadecimais %xx, para que o resultado possa ser colocado com segurança dentro de um segmento de caminho ou valor de query. Devolve a str codificada.

microdot.urldecode(s: str) → str#: Descodifica em percentagem um componente de URL – o inverso de urlencode(). Os escapes %xx são substituídos pelo byte que codificam, e + é convertido em espaço (a convenção histórica das query strings). Devolve a str descodificada.

microdot — framework HTTP minimalista#

class Microdot#

class Request#

class Response#

Exceções#

class URLPattern#

Classes auxiliares#

Funções ao nível do módulo#

Submódulos#

`microdot` — framework HTTP minimalista#