microdot — framework HTTP minimalista

Microdot es un framework HTTP pequeño, inspirado en Flask, para MicroPython. Se ejecuta sobre asyncio, gestiona múltiples clientes concurrentes sin hilos y expone una API familiar de decoradores de rutas. Una aplicación mínima tiene este aspecto:

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

Una instancia de aplicación HTTP. Se construye una instancia cerca del comienzo del script y se decora con manejadores de rutas; al llamar a run() o esperar a start_server() comienza el servicio.

Registro de rutas

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

Decorador que registra un manejador para url_pattern bajo los métodos HTTP indicados (por defecto ['GET']). Devuelve el decorador que, al aplicarse a una función, la registra como manejador y devuelve la función sin cambios.

url_pattern

Un patrón de ruta. Admite segmentos estáticos (/users) y segmentos dinámicos delimitados por < / >. Los segmentos dinámicos aceptan un prefijo de tipo opcional separado por : – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. El tipo por defecto es string.

methods

Lista de nombres de métodos HTTP. Si se omite, solo se compara GET.

El manejador se llama primero con el objeto de la solicitud y luego con los segmentos dinámicos capturados como argumentos de palabra clave. El valor de retorno del manejador se convierte en la respuesta HTTP: una Response, una cadena, una tupla (body, status_code[, headers]), o un dict / list (enviado como JSON).

get(url_pattern: str) → Callable

Alias de conveniencia para route(url_pattern, methods=['GET']) – registra la función decorada como un manejador GET para url_pattern. Devuelve el decorador.

post(url_pattern: str) → Callable

Alias de conveniencia para route(url_pattern, methods=['POST']) – registra la función decorada como un manejador POST para url_pattern. Devuelve el decorador.

put(url_pattern: str) → Callable

Alias de conveniencia para route(url_pattern, methods=['PUT']) – registra la función decorada como un manejador PUT para url_pattern. Devuelve el decorador.

patch(url_pattern: str) → Callable

Alias de conveniencia para route(url_pattern, methods=['PATCH']) – registra la función decorada como un manejador PATCH para url_pattern. Devuelve el decorador.

delete(url_pattern: str) → Callable

Alias de conveniencia para route(url_pattern, methods=['DELETE']) – registra la función decorada como un manejador DELETE para url_pattern. Devuelve el decorador.

Hooks del ciclo de vida

before_request(f: Callable) → Callable

Decorador que registra f para ejecutarse antes de cada solicitud. f toma el objeto de la solicitud; su valor de retorno normalmente se ignora. Para cortocircuitar la solicitud, devuelve una Response (o un valor que se convierta en una) – el resto del pipeline se omite entonces y se envía esa respuesta. Devuelve f sin cambios.

after_request(f: Callable) → Callable

Decorador que registra f para ejecutarse después de cada solicitud exitosa. f toma (request, response) y debe devolver el objeto de respuesta (posiblemente modificado). Devuelve f sin cambios.

after_error_request(f: Callable) → Callable

Decorador que registra f para ejecutarse después de que Microdot genere una respuesta de error (404, 500, excepción lanzada, etc.). f toma (request, response) y debe devolver el objeto de respuesta (posiblemente modificado). Devuelve f sin cambios.

errorhandler(status_code_or_exception_class) → Callable

Decorador que registra un manejador personalizado para un código de estado HTTP o una clase de excepción de Python. Para los códigos de estado, el manejador toma solo la solicitud; para las clases de excepción, (request, exception). Devuelve el decorador.

Montaje y aborto

mount(subapp: Microdot, url_prefix: str = '', local: bool = False) → None

Adjunta las rutas de otra instancia Microdot bajo url_prefix. Cuando local es False (por defecto), los manejadores before / after / error de la subaplicación también se adjuntan al padre. Cuando es True, esos manejadores se ejecutan solo para las rutas de la subaplicación. Devuelve None.

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

Lanza HTTPException para abortar la solicitud actual con el código de estado dado. Nunca retorna de forma normal – el framework captura la excepción y la convierte en la respuesta de error correspondiente. Cómodo dentro de los cuerpos de las rutas:

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()

Ejecución del servidor

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

Bloquea el hilo que llama, ejecuta asyncio.run() sobre start_server(). Devuelve None solo después de que se haya llamado a shutdown() y el bucle de escucha salga. La forma más sencilla de lanzar una aplicación independiente:

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 el servidor como una corrutina. Usa esto al integrarlo con un bucle de eventos asyncio existente junto con otras tareas. La corrutina no retorna hasta que se llama a shutdown():

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

Interfaz de red en la que escuchar. '0.0.0.0' (por defecto) significa todas las interfaces; '127.0.0.1' significa solo loopback.

port

Puerto TCP en el que escuchar. Por defecto 5000 – elige 80 para HTTP simple, 443 para HTTPS.

debug

Si es True, registra cada solicitud y vuelca los trazados de pila a stdout.

ssl

Un ssl.SSLContext para envolver las conexiones entrantes en TLS. None (por defecto) significa HTTP simple.

start_serving

Solo relevante en CPython; se ignora en MicroPython.

shutdown() → None

Solicita un apagado ordenado del servidor. Es seguro llamarlo desde un manejador de ruta – la solicitud actual se completa antes de que el bucle salga. Retorna de inmediato; el apagado real ocurre una vez que termina la solicitud en curso.

Atributos

url_map: list

Lista de rutas registradas como tuplas (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list

Lista de invocables registrados con before_request(), en orden de registro. Cada uno se ejecuta con el objeto de la solicitud antes del manejador de ruta. Mutar la lista directamente funciona pero rara vez es necesario – es preferible el decorador.

after_request_handlers: list

Lista de invocables registrados con after_request(), en orden de registro. Cada uno se ejecuta con (request, response) después de una solicitud exitosa y debe devolver la respuesta (posiblemente modificada).

after_error_request_handlers: list

Lista de invocables registrados con after_error_request(), en orden de registro. Cada uno se ejecuta con (request, response) después de que se genera una respuesta de error (por el framework o por un manejador de errores de la aplicación) y debe devolver la respuesta.

error_handlers: dict

Mapeo de claves de error a invocables manejadores, poblado por errorhandler(). Las claves son códigos de estado HTTP (int) o clases de excepción de Python; los valores son los manejadores registrados. Los manejadores de códigos de estado toman (request); los manejadores de clases de excepción toman (request, exception).

debug: bool

True mientras el servidor se ejecuta con debug=True.

class Request

class microdot.Request

Una solicitud HTTP entrante. Las instancias se pasan a los manejadores de ruta como primer argumento posicional. Las aplicaciones no construyen Request directamente.

Atributos de clase

max_content_length: int

Rechaza con una respuesta 413 las solicitudes cuyo Content-Length supere esta cantidad de bytes. Por defecto 16 KB.

max_body_length: int

El cuerpo más grande que se almacena en memoria y se expone a través de body. Los cuerpos más grandes (hasta max_content_length) permanecen en el socket y deben leerse a través de stream. Por defecto 16 KB.

max_readline: int

Longitud máxima de una sola línea de solicitud / línea de cabecera en bytes. Por defecto 2 KB.

Atributos de instancia

app: Microdot

La instancia Microdot que gestiona la solicitud.

client_addr: tuple

La dirección del cliente como (host, port).

method: str

Cadena del método HTTP ('GET', 'POST', …).

scheme: str

'http' o 'https'.

url: str

La ruta y cadena de consulta completas de la URL de la solicitud (todo lo que va después del host).

path: str

Solo la porción de la ruta.

query_string: str | None

La porción cruda de la cadena de consulta, o None.

args: MultiDict

Cadena de consulta analizada como un MultiDict.

headers: NoCaseDict

Cabeceras de la solicitud como un NoCaseDict (búsqueda sin distinción de mayúsculas/minúsculas).

cookies: dict

Cabecera Cookie analizada como un dict.

content_length: int

El valor entero de Content-Length, o 0 si está ausente.

content_type: str | None

El valor de la cabecera Content-Type, o None.

g: object

Un contenedor de formato libre por solicitud (un objeto vacío). Asigna atributos a él para pasar valores entre los hooks y los manejadores (request.g.user = ...).

route: Callable

La función manejadora que coincidió con esta solicitud.

url_prefix: str

Prefijo bajo el que se montó la ruta, o ''.

subapp: Microdot | None

La instancia de la subaplicación montada, o None.

Acceso al cuerpo

body: bytes

El cuerpo completo de la solicitud como bytes. Vacío cuando el cuerpo se está transmitiendo en streaming (ver stream).

stream: object

Un objeto de stream asíncrono que expone read() sobre el cuerpo. Úsalo para cuerpos más grandes que max_body_length.

json: dict | list | str | int | float | bool | None

El cuerpo analizado como JSON (un dict, list, str, int, float o bool – lo que codifique la carga útil), o None si el Content-Type no es application/json.

form: MultiDict | None

Campos de formulario codificados en URL como un MultiDict, o None. Para multipart/form-data, decora la ruta con microdot.multipart.with_form_data().

files: dict | None

Archivos subidos como {name: FileUpload}, poblado por microdot.multipart.with_form_data(). Es None hasta que se ejecuta ese decorador.

after_request(f: Callable) → Callable

Registra un hook after-request local a la solicitud – se ejecuta después de los manejadores after-request a nivel de aplicación, solo en caso de éxito. f toma (request, response) y debe devolver el objeto de respuesta (posiblemente modificado). Devuelve f sin cambios.

class Response

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

Una respuesta HTTP. La mayoría de los manejadores devuelven valores que Microdot convierte automáticamente en una Response; constrúyela directamente cuando necesites cabeceras personalizadas o un código de estado específico.

body

Cuerpo de la respuesta. str se codifica en UTF-8; dict / list se codifica como JSON y el Content-Type se establece en consecuencia; bytes se envía tal cual; un objeto tipo archivo o un generador asíncrono se transmiten en streaming.

status_code

Estado HTTP numérico. Por defecto 200.

headers

Dict de cabeceras de respuesta (sin distinción de mayúsculas/minúsculas).

reason

Frase de motivo personalizada. Por defecto es "OK" para 200 y "N/A" en caso contrario.

Atributos de clase

default_content_type: str

Content-Type usado cuando no se establece ninguno explícitamente. Por defecto 'text/plain'.

default_send_file_max_age: int | None

Valor de Cache-Control: max-age para send_file() cuando no se proporciona max_age. None (por defecto) significa sin cabecera Cache-Control.

send_file_buffer_size: int

Tamaño de fragmento para el streaming de send_file(). Por defecto 1024.

already_handled: None

Centinela devuelto por los manejadores que ya han escrito la respuesta directamente (usado por las actualizaciones a WebSocket). Siempre None; lo que importa es la identidad.

types_map: dict

Mapa de extensión a tipo MIME usado por send_file() para inferir el tipo de contenido. Mapea css, gif, html, jpg, js, json, png, txt, svg.

Métodos

Añade una cabecera Set-Cookie. expires puede ser una cadena ya formateada o un objeto similar a datetime con timetuple(). Devuelve None; la cabecera se añade a esta respuesta en el sitio.

Establece un Set-Cookie que expira inmediatamente la cookie dada. kwargs acepta las mismas opciones que set_cookie() (path, domain, secure, http_only, partitioned); expires y max_age se ignoran. Devuelve None; la cabecera se añade a esta respuesta en el sitio.

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

Devuelve una respuesta de redirección:

@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 en streaming un archivo del sistema de archivos como cuerpo de la respuesta. content_type se infiere de la extensión a través de types_map si no se proporciona. compressed=True establece Content-Encoding: gzip (el archivo ya debe estar comprimido).

Advertencia

filename se abre directamente. Nunca pases una ruta proporcionada por el usuario sin sanear – hacerlo permite la divulgación arbitraria de archivos.

Excepciones

exception microdot.HTTPException

Lanzada por abort() para cortocircuitar una solicitud con un código de estado específico. Microdot la captura y la convierte en la respuesta de error correspondiente.

status_code: int

Código de estado HTTP numérico a devolver – el valor pasado a abort().

reason: str

Frase de motivo a incluir en la respuesta de error. Si no se proporciona a abort(), por defecto es "<status_code> error" (p. ej. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

La forma compilada del patrón de URL de una ruta. Construida automáticamente por Microdot.route(); las aplicaciones rara vez instancian una directamente.

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

Registra un nuevo tipo de segmento dinámico para usar en los patrones de ruta. Devuelve None; el tipo se añade al registro de tipos a nivel de clase. Por ejemplo, para añadir un tipo <uuid:...>:

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

parser es un invocable opcional que convierte la cadena capturada antes de que llegue al manejador.

match(path: str) → dict | None

Compara path con el patrón y devuelve un dict de los grupos capturados, o None si no hay coincidencia.

Clases auxiliares

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

Una subclase de dict que almacena múltiples valores por clave. Se usa para las cadenas de consulta y los cuerpos de formulario codificados en URL donde la misma clave puede aparecer más de una vez (?tag=a&tag=b).

get(key, default=None, type: Callable | None = None)

Devuelve el primer valor para key, opcionalmente convertido con type (un invocable). Devuelve default si la clave falta o la conversión falla; en caso contrario devuelve el valor (opcionalmente convertido).

getlist(key, type: Callable | None = None) → list

Devuelve todos los valores para key como una lista, opcionalmente con cada valor convertido por type. Devuelve una lista vacía si key no está presente.

class microdot.NoCaseDict

Una subclase de dict con claves de cadena sin distinción de mayúsculas/minúsculas. Se usa para Request.headers y Response.headers.

Funciones a nivel de módulo

microdot.abort(status_code: int, reason: str | None = None) → None

Atajo para Microdot.abort(). Nunca retorna de forma normal – lanza HTTPException. Importable como from microdot import abort.

microdot.redirect(location: str, status_code: int = 302) → Response

Atajo para Response.redirect(). Importable como from microdot import redirect.

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

Atajo para Response.send_file().

microdot.urlencode(s: str) → str

Codifica en porcentaje un componente de URL. Reemplaza los caracteres que tienen un significado reservado en una URL (/, ?, &, =, #, espacio, …) con sus escapes hexadecimales %xx para que el resultado pueda situarse de forma segura dentro de un segmento de ruta o un valor de consulta. Devuelve el str codificado.

microdot.urldecode(s: str) → str

Decodifica en porcentaje un componente de URL – el inverso de urlencode(). Los escapes %xx se reemplazan por el byte que codifican, y + se convierte en un espacio (la convención histórica de las cadenas de consulta). Devuelve el str decodificado.

Submódulos