`microdot` — framework HTTP mínimo#

Microdot é um framework HTTP pequeno, inspirado no Flask, para o MicroPython. Ele roda sobre o asyncio, lida com múltiplos clientes simultâneos sem usar threads e expõe uma API familiar baseada em decoradores de rota. Uma aplicação mínima se parece com:

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. Uma instância é construída próximo ao topo do script e decorada com os manipuladores de rota; chamar run() ou aguardar start_server() inicia o atendimento das requisições.

Registro de rotas

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

Decorador que registra um manipulador para url_pattern sob os métodos HTTP listados (padrão ['GET']). Retorna o decorador que, quando aplicado a uma função, a registra como manipulador e retorna a função inalterada.

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

O manipulador é chamado primeiro com o objeto de requisição e, em seguida, com quaisquer segmentos dinâmicos capturados como argumentos nomeados. O valor de retorno do manipulador torna-se a resposta HTTP: um Response, uma string, uma tupla (body, status_code[, headers]) ou um dict / list (enviado como JSON).

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

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

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

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

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

Hooks de ciclo de vida

before_request(f: Callable) → Callable#: Decorador que registra f para ser executada antes de cada requisição. f recebe o objeto de requisição; seu valor de retorno normalmente é ignorado. Para interromper a requisição antecipadamente, retorne um Response (ou um valor que se converta em um) – o restante do pipeline é então ignorado e essa resposta é enviada. Retorna f inalterada.

after_request(f: Callable) → Callable#: Decorador que registra f para ser executada após cada requisição bem-sucedida. f recebe (request, response) e deve retornar o objeto de resposta (possivelmente modificado). Retorna f inalterada.

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

errorhandler(status_code_or_exception_class) → Callable#: Decorador que registra um manipulador personalizado para um código de status HTTP ou uma classe de exceção do Python. Para códigos de status, o manipulador recebe apenas a requisição; para classes de exceção, (request, exception). Retorna o decorador.

Montagem e aborto

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

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

Levante HTTPException para abortar a requisição atual com o código de status fornecido. Nunca retorna normalmente – o framework captura a exceção e a transforma na resposta de erro correspondente. Conveniente dentro dos 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()

Executando o servidor

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

Bloqueia a thread chamadora, executa asyncio.run() em start_server(). Retorna None somente depois que shutdown() tiver sido chamado e o laço de escuta encerrar. A forma mais simples de iniciar 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 laço de eventos asyncio existente junto a outras tarefas. A corrotina não retorna até que shutdown() seja chamado:

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

host: Interface de rede na qual escutar. '0.0.0.0' (padrão) significa todas as interfaces; '127.0.0.1' significa apenas loopback.
port: Porta TCP na qual escutar. Padrão 5000 – escolha 80 para HTTP simples, 443 para HTTPS.
debug: Se True, registra cada requisição e despeja os tracebacks na saída padrão.
ssl: Um ssl.SSLContext para envolver as conexões recebidas em TLS. None (padrão) significa HTTP simples.
start_serving: Relevante apenas no CPython; ignorado no MicroPython.

shutdown() → None#: Solicita um desligamento gracioso do servidor. É seguro chamar a partir de um manipulador de rota – a requisição atual é concluída antes de o laço encerrar. Retorna imediatamente; o desligamento de fato ocorre assim que a requisição em andamento termina.

Atributos

url_map: list#: Lista das rotas registradas como tuplas (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list#: Lista de chamáveis registrados com before_request(), na ordem de registro. Cada um é executado com o objeto de requisição antes do manipulador de rota. Modificar a lista diretamente funciona, mas raramente é necessário – prefira o decorador.

after_request_handlers: list#: Lista de chamáveis registrados com after_request(), na ordem de registro. Cada um é executado com (request, response) após uma requisição bem-sucedida e deve retornar a resposta (possivelmente modificada).

after_error_request_handlers: list#: Lista de chamáveis registrados com after_error_request(), na ordem de registro. Cada um é executado com (request, response) após a geração de uma resposta de erro (pelo framework ou por um manipulador de erro da aplicação) e deve retornar a resposta.

error_handlers: dict#: Mapeamento de chaves de erro para chamáveis manipuladores, populado por errorhandler(). As chaves são códigos de status HTTP (int) ou classes de exceção do Python; os valores são os manipuladores registrados. Manipuladores de código de status recebem (request); manipuladores de classe de exceção recebem (request, exception).

debug: bool#: True enquanto o servidor estiver rodando com debug=True.

class Request#

class microdot.Request#

Uma requisição HTTP recebida. As instâncias são passadas aos manipuladores de rota como o primeiro argumento posicional. As aplicações não constroem Request diretamente.

Atributos de classe

max_content_length: int#: Rejeita requisições cujo Content-Length excede esta quantidade de bytes com uma resposta 413. Padrão 16 KB.

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

max_readline: int#: Comprimento máximo de uma única linha de requisição / linha de cabeçalho em bytes. Padrão 2 KB.

Atributos de instância

app: Microdot#: A instância de Microdot que está tratando a requisição.

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 caminho completo da URL da requisição e a query string (tudo após o host).

path: str#: Apenas a parte do caminho.

query_string: str | None#: A query string bruta, ou None.

args: MultiDict#: A query string analisada como um MultiDict.

headers: NoCaseDict#: Os cabeçalhos da requisição como um NoCaseDict (busca sem distinção entre maiúsculas e minúsculas).

cookies: dict#: O cabeçalho Cookie analisado como um 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 contêiner de formato livre por requisição (um objeto vazio). Atribua atributos a ele para passar valores entre hooks e manipuladores (request.g.user = ...).

route: Callable#: A função manipuladora que correspondeu a esta requisição.

url_prefix: str#: O 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 da requisição como bytes. Vazio quando o corpo está sendo transmitido em stream (veja 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 quer que o payload codifique), ou None se o Content-Type não for application/json.

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

files: dict | None#: Arquivos enviados como {name: FileUpload}, populado por microdot.multipart.with_form_data(). None até que esse decorador seja executado.

after_request(f: Callable) → Callable#: Registra um hook after-request local à requisição – executado após os manipuladores after-request de nível de aplicação, apenas em caso de sucesso. f recebe (request, response) e deve retornar o objeto de resposta (possivelmente modificado). Retorna 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 manipuladores retorna valores que o Microdot converte automaticamente em um Response; construa um diretamente quando precisar de cabeçalhos personalizados ou de um código de status específico.

body: Corpo da resposta. str é codificado em UTF-8; dict / list é codificado em JSON e o Content-Type é definido de acordo; bytes é enviado como está; um objeto semelhante a arquivo ou um gerador assíncrono é transmitido em stream.
status_code: Status HTTP numérico. Padrão 200.
headers: Dict de cabeçalhos da resposta (sem distinção entre maiúsculas e minúsculas).
reason: Frase de motivo personalizada. O padrão é "OK" para 200 e "N/A" caso contrário.

Atributos de classe

default_content_type: str#: Content-Type usado quando nenhum é definido explicitamente. Padrã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 (padrão) significa nenhum cabeçalho Cache-Control.

send_file_buffer_size: int#: Tamanho do bloco para o streaming de send_file(). Padrão 1024.

already_handled: None#: Sentinela retornado por manipuladores que já escreveram a resposta diretamente (usado por upgrades de WebSocket). Sempre None; o que importa é a identidade.

types_map: dict#: Mapa de extensão para tipo mime usado por send_file() para inferência do 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(). Retorna None; o cabeçalho é anexado 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. Retorna None; o cabeçalho é anexado a esta resposta no local.

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

Retorna 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 um arquivo do sistema de arquivos como o 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 arquivo já deve estar comprimido).

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

Exceções#

exception microdot.HTTPException#

Levantada por abort() para interromper antecipadamente uma requisição com um código de status específico. O Microdot captura isso e a transforma na resposta de erro correspondente.

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

reason: str#: Frase de motivo a incluir na resposta de erro. Se não for fornecida a abort(), o padrã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ída automaticamente por Microdot.route(); as aplicações raramente instanciam uma diretamente.

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

Registra um novo tipo de segmento dinâmico para uso em padrões de rota. Retorna None; o tipo é adicionado ao registro de tipos de nível de 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 que ela chegue ao manipulador.

match(path: str) → dict | None#: Corresponde path ao padrão e retorna um dict dos 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. Usada para query strings e corpos de formulário codificados em URL, onde a mesma chave pode aparecer mais de uma vez (?tag=a&tag=b).

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

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

class microdot.NoCaseDict#: Uma subclasse de dict com chaves de string sem distinção entre maiúsculas e minúsculas. Usada para Request.headers e Response.headers.

Funções de nível de módulo#

microdot.abort(status_code: int, reason: str | None = None) → None#: Atalho para Microdot.abort(). Nunca retorna normalmente – levanta 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 percent-encoding um componente de URL. Substitui os caracteres que têm significado reservado em uma URL (/, ?, &, =, #, espaço, …) por seus escapes hexadecimais %xx, de modo que o resultado possa ser usado com segurança dentro de um segmento de caminho ou de um valor de query. Retorna a str codificada.

microdot.urldecode(s: str) → str#: Decodifica de percent-encoding 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 de query string). Retorna a str decodificada.

microdot — framework HTTP mínimo#

class Microdot#

class Request#

class Response#

Exceções#

class URLPattern#

Classes auxiliares#

Funções de nível de módulo#

Submódulos#

`microdot` — framework HTTP mínimo#