microdot — minimales HTTP-Framework

Microdot ist ein kleines, von Flask inspiriertes HTTP-Framework für MicroPython. Es läuft auf Basis von asyncio, verarbeitet mehrere gleichzeitige Clients ohne Threads und stellt eine vertraute Route-Decorator-API bereit. Eine minimale Anwendung sieht so aus:

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

Eine Instanz einer HTTP-Anwendung. Eine Instanz wird nahe dem Anfang des Skripts erstellt und mit Route-Handlern dekoriert; der Aufruf von run() oder das Awaiten von start_server() startet die Auslieferung.

Routen-Registrierung

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

Decorator, der einen Handler für url_pattern unter den aufgeführten HTTP-Methoden registriert (Standard ['GET']). Gibt den Decorator zurück, der, wenn er auf eine Funktion angewendet wird, diese als Handler registriert und die Funktion unverändert zurückgibt.

url_pattern

Ein Pfadmuster. Unterstützt statische Segmente (/users) und dynamische Segmente, die in < / > eingeschlossen sind. Dynamische Segmente akzeptieren ein optionales Typpräfix, das durch : getrennt wird – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Der Standardtyp ist string.

methods

Liste der HTTP-Methodennamen. Wenn weggelassen, wird nur GET abgeglichen.

Der Handler wird zuerst mit dem Request-Objekt aufgerufen, dann mit allen erfassten dynamischen Segmenten als Schlüsselwortargumente. Der Rückgabewert des Handlers wird zur HTTP-Antwort: eine Response, ein String, ein Tupel (body, status_code[, headers]) oder ein dict / list (als JSON gesendet).

get(url_pattern: str) → Callable

Praktischer Alias für route(url_pattern, methods=['GET']) – registriert die dekorierte Funktion als GET-Handler für url_pattern. Gibt den Decorator zurück.

post(url_pattern: str) → Callable

Praktischer Alias für route(url_pattern, methods=['POST']) – registriert die dekorierte Funktion als POST-Handler für url_pattern. Gibt den Decorator zurück.

put(url_pattern: str) → Callable

Praktischer Alias für route(url_pattern, methods=['PUT']) – registriert die dekorierte Funktion als PUT-Handler für url_pattern. Gibt den Decorator zurück.

patch(url_pattern: str) → Callable

Praktischer Alias für route(url_pattern, methods=['PATCH']) – registriert die dekorierte Funktion als PATCH-Handler für url_pattern. Gibt den Decorator zurück.

delete(url_pattern: str) → Callable

Praktischer Alias für route(url_pattern, methods=['DELETE']) – registriert die dekorierte Funktion als DELETE-Handler für url_pattern. Gibt den Decorator zurück.

Lebenszyklus-Hooks

before_request(f: Callable) → Callable

Decorator, der f registriert, um vor jedem Request ausgeführt zu werden. f nimmt das Request-Objekt entgegen; sein Rückgabewert wird normalerweise ignoriert. Um den Request kurzzuschließen, geben Sie eine Response zurück (oder einen Wert, der in eine solche umgewandelt wird) – der Rest der Pipeline wird dann übersprungen und diese Antwort wird gesendet. Gibt f unverändert zurück.

after_request(f: Callable) → Callable

Decorator, der f registriert, um nach jedem erfolgreichen Request ausgeführt zu werden. f nimmt (request, response) entgegen und muss das (möglicherweise modifizierte) Response-Objekt zurückgeben. Gibt f unverändert zurück.

after_error_request(f: Callable) → Callable

Decorator, der f registriert, um ausgeführt zu werden, nachdem Microdot eine Fehlerantwort generiert hat (404, 500, ausgelöste Ausnahme usw.). f nimmt (request, response) entgegen und muss das (möglicherweise modifizierte) Response-Objekt zurückgeben. Gibt f unverändert zurück.

errorhandler(status_code_or_exception_class) → Callable

Decorator, der einen benutzerdefinierten Handler für einen HTTP-Statuscode oder eine Python-Ausnahmeklasse registriert. Bei Statuscodes nimmt der Handler nur den Request entgegen; bei Ausnahmeklassen (request, exception). Gibt den Decorator zurück.

Einhängen und Abbrechen

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

Hängt die Routen einer anderen Microdot-Instanz unter url_prefix ein. Wenn local False ist (Standard), werden die before- / after- / error-Handler der Sub-App ebenfalls an die übergeordnete App angehängt. Wenn True, laufen diese Handler nur für Sub-App-Routen. Gibt None zurück.

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

Lösen Sie HTTPException aus, um den aktuellen Request mit dem angegebenen Statuscode abzubrechen. Kehrt niemals normal zurück – das Framework fängt die Ausnahme ab und wandelt sie in die entsprechende Fehlerantwort um. Praktisch innerhalb von Route-Bodies:

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

Den Server ausführen

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

Blockiert den aufrufenden Thread und führt asyncio.run() auf start_server() aus. Gibt None erst zurück, nachdem shutdown() aufgerufen wurde und die Lausch-Schleife beendet ist. Der einfachste Weg, eine eigenständige App zu starten:

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

Startet den Server als Coroutine. Verwenden Sie dies bei der Integration mit einer bestehenden asyncio-Event-Loop neben anderen Tasks. Die Coroutine kehrt erst zurück, wenn shutdown() aufgerufen wird:

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

Netzwerkschnittstelle, auf der gelauscht werden soll. '0.0.0.0' (Standard) bedeutet alle Schnittstellen; '127.0.0.1' bedeutet nur Loopback.

port

TCP-Port, auf dem gelauscht werden soll. Standard 5000 – wählen Sie 80 für reines HTTP, 443 für HTTPS.

debug

Wenn True, wird jeder Request protokolliert und Tracebacks werden nach stdout ausgegeben.

ssl

Ein ssl.SSLContext, um eingehende Verbindungen in TLS einzuwickeln. None (Standard) bedeutet reines HTTP.

start_serving

Nur relevant unter CPython; wird unter MicroPython ignoriert.

shutdown() → None

Fordert ein ordnungsgemäßes Herunterfahren des Servers an. Kann sicher aus einem Route-Handler heraus aufgerufen werden – der aktuelle Request wird abgeschlossen, bevor die Schleife beendet wird. Kehrt sofort zurück; das eigentliche Herunterfahren erfolgt, sobald der laufende Request abgeschlossen ist.

Attribute

url_map: list

Liste der registrierten Routen als (methods, URLPattern, handler, url_prefix, subapp)-Tupel.

before_request_handlers: list

Liste der mit before_request() registrierten Callables, in der Reihenfolge der Registrierung. Jedes wird mit dem Request-Objekt vor dem Route-Handler ausgeführt. Das direkte Verändern der Liste funktioniert, ist aber selten nötig – bevorzugen Sie den Decorator.

after_request_handlers: list

Liste der mit after_request() registrierten Callables, in der Reihenfolge der Registrierung. Jedes wird mit (request, response) nach einem erfolgreichen Request ausgeführt und muss die (möglicherweise modifizierte) Antwort zurückgeben.

after_error_request_handlers: list

Liste der mit after_error_request() registrierten Callables, in der Reihenfolge der Registrierung. Jedes wird mit (request, response) ausgeführt, nachdem eine Fehlerantwort generiert wurde (durch das Framework oder durch einen Anwendungs-Fehlerhandler), und muss die Antwort zurückgeben.

error_handlers: dict

Zuordnung von Fehler-Schlüsseln zu Handler-Callables, befüllt durch errorhandler(). Schlüssel sind entweder HTTP-Statuscodes (int) oder Python-Ausnahmeklassen; Werte sind die registrierten Handler. Statuscode-Handler nehmen (request) entgegen; Ausnahmeklassen-Handler nehmen (request, exception) entgegen.

debug: bool

True, während der Server mit debug=True läuft.

class Request

class microdot.Request

Ein eingehender HTTP-Request. Instanzen werden Route-Handlern als erstes positionsbezogenes Argument übergeben. Anwendungen erstellen Request nicht direkt.

Klassenattribute

max_content_length: int

Lehnt Requests, deren Content-Length diese Anzahl an Bytes überschreitet, mit einer 413-Antwort ab. Standard 16 KB.

max_body_length: int

Größter Body, der in den Speicher gepuffert und über body bereitgestellt wird. Größere Bodies (bis zu max_content_length) verbleiben auf dem Socket und müssen über stream gelesen werden. Standard 16 KB.

max_readline: int

Maximale Länge einer einzelnen Request-Zeile / Header-Zeile in Bytes. Standard 2 KB.

Instanzattribute

app: Microdot

Die Microdot-Instanz, die den Request verarbeitet.

client_addr: tuple

Die Adresse des Clients als (host, port).

method: str

HTTP-Methoden-String ('GET', 'POST', …).

scheme: str

'http' oder 'https'.

url: str

Der vollständige Request-URL-Pfad und die Query-String (alles nach dem Host).

path: str

Nur der Pfadanteil.

query_string: str | None

Der rohe Query-String-Anteil oder None.

args: MultiDict

Geparster Query-String als MultiDict.

headers: NoCaseDict

Request-Header als NoCaseDict (Groß-/Kleinschreibung-unabhängige Suche).

cookies: dict

Geparster Cookie-Header als dict.

content_length: int

Der ganzzahlige Content-Length-Wert oder 0, falls nicht vorhanden.

content_type: str | None

Der Content-Type-Header-Wert oder None.

g: object

Ein freiformatiger Container pro Request (ein nacktes Objekt). Weisen Sie ihm Attribute zu, um Werte zwischen Hooks und Handlern weiterzugeben (request.g.user = ...).

route: Callable

Die Handler-Funktion, die diesem Request entsprach.

url_prefix: str

Präfix, unter dem die Route eingehängt wurde, oder ''.

subapp: Microdot | None

Die eingehängte Sub-App-Instanz oder None.

Body-Zugriff

body: bytes

Der vollständige Request-Body als bytes. Leer, wenn der Body gestreamt wird (siehe stream).

stream: object

Ein asynchrones Stream-Objekt, das read() über den Body bereitstellt. Verwenden Sie dies für Bodies, die größer als max_body_length sind.

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

Der als JSON geparste Body (ein dict, list, str, int, float oder bool – je nachdem, was die Nutzlast codiert) oder None, wenn der Content-Type nicht application/json ist.

form: MultiDict | None

URL-codierte Formularfelder als MultiDict oder None. Für multipart/form-data dekorieren Sie die Route mit microdot.multipart.with_form_data().

files: dict | None

Hochgeladene Dateien als {name: FileUpload}, befüllt durch microdot.multipart.with_form_data(). None, bis dieser Decorator ausgeführt wird.

after_request(f: Callable) → Callable

Registriert einen request-lokalen After-Request-Hook – wird nach den anwendungsweiten After-Request-Handlern ausgeführt, nur bei Erfolg. f nimmt (request, response) entgegen und muss das (möglicherweise modifizierte) Response-Objekt zurückgeben. Gibt f unverändert zurück.

class Response

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

Eine HTTP-Antwort. Die meisten Handler geben Werte zurück, die Microdot automatisch in eine Response umwandelt; erstellen Sie eine direkt, wenn Sie benutzerdefinierte Header oder einen bestimmten Statuscode benötigen.

body

Antwort-Body. str wird als UTF-8 codiert; dict / list wird als JSON codiert und der Content-Type entsprechend gesetzt; bytes wird unverändert gesendet; ein dateiähnliches Objekt oder ein asynchroner Generator wird gestreamt.

status_code

Numerischer HTTP-Status. Standard 200.

headers

Dict der Antwort-Header (Groß-/Kleinschreibung-unabhängig).

reason

Benutzerdefinierte Begründungsphrase. Standardmäßig "OK" für 200 und ansonsten "N/A".

Klassenattribute

default_content_type: str

Content-Type, der verwendet wird, wenn keiner explizit gesetzt ist. Standard 'text/plain'.

default_send_file_max_age: int | None

Cache-Control: max-age-Wert für send_file(), wenn max_age nicht angegeben ist. None (Standard) bedeutet kein Cache-Control-Header.

send_file_buffer_size: int

Chunk-Größe für das Streaming von send_file(). Standard 1024.

already_handled: None

Sentinel, der von Handlern zurückgegeben wird, die die Antwort bereits direkt geschrieben haben (verwendet von WebSocket-Upgrades). Immer None; entscheidend ist die Identität.

types_map: dict

Erweiterung-zu-MIME-Typ-Zuordnung, die von send_file() zur Inferenz des Content-Type verwendet wird. Ordnet css, gif, html, jpg, js, json, png, txt, svg zu.

Methoden

Fügt einen Set-Cookie-Header hinzu. expires kann ein vorformatierter String oder ein datetime-ähnliches Objekt mit timetuple() sein. Gibt None zurück; der Header wird dieser Antwort direkt angehängt.

Setzt ein Set-Cookie, das das angegebene Cookie sofort verfallen lässt. kwargs akzeptiert dieselben Optionen wie set_cookie() (path, domain, secure, http_only, partitioned); expires und max_age werden ignoriert. Gibt None zurück; der Header wird dieser Antwort direkt angehängt.

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

Gibt eine Weiterleitungsantwort zurück:

@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

Streamt eine Datei aus dem Dateisystem als Antwort-Body. content_type wird über types_map aus der Erweiterung abgeleitet, falls nicht angegeben. compressed=True setzt Content-Encoding: gzip (die Datei muss bereits komprimiert sein).

Warnung

filename wird direkt geöffnet. Übergeben Sie niemals einen nicht bereinigten, vom Benutzer bereitgestellten Pfad – dies ermöglicht die Offenlegung beliebiger Dateien.

Ausnahmen

exception microdot.HTTPException

Wird von abort() ausgelöst, um einen Request mit einem bestimmten Statuscode kurzzuschließen. Microdot fängt dies ab und wandelt es in die entsprechende Fehlerantwort um.

status_code: int

Numerischer HTTP-Statuscode, der zurückgegeben werden soll – der an abort() übergebene Wert.

reason: str

Begründungsphrase, die in die Fehlerantwort aufgenommen werden soll. Wenn nicht an abort() übergeben, standardmäßig "<status_code> error" (z. B. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Die kompilierte Form des URL-Musters einer Route. Wird automatisch von Microdot.route() erstellt; Anwendungen instanziieren eine solche selten direkt.

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

Registriert einen neuen Typ für dynamische Segmente zur Verwendung in Route-Mustern. Gibt None zurück; der Typ wird der klassenweiten Typ-Registry hinzugefügt. Zum Beispiel, um einen <uuid:...>-Typ hinzuzufügen:

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

parser ist ein optionales Callable, das den erfassten String umwandelt, bevor er den Handler erreicht.

match(path: str) → dict | None

Gleicht path gegen das Muster ab und gibt ein dict der erfassten Gruppen zurück oder None bei keiner Übereinstimmung.

Hilfsklassen

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

Eine dict-Unterklasse, die mehrere Werte pro Schlüssel speichert. Wird für Query-Strings und URL-codierte Formular-Bodies verwendet, bei denen derselbe Schlüssel mehr als einmal auftreten kann (?tag=a&tag=b).

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

Gibt den ersten Wert für key zurück, optional umgewandelt mit type (einem Callable). Gibt default zurück, wenn der Schlüssel fehlt oder die Umwandlung fehlschlägt; andernfalls wird der (optional umgewandelte) Wert zurückgegeben.

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

Gibt alle Werte für key als Liste zurück, optional mit jedem Wert umgewandelt durch type. Gibt eine leere Liste zurück, wenn key nicht vorhanden ist.

class microdot.NoCaseDict

Eine dict-Unterklasse mit Groß-/Kleinschreibung-unabhängigen String-Schlüsseln. Wird für Request.headers und Response.headers verwendet.

Funktionen auf Modulebene

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

Kurzform für Microdot.abort(). Kehrt niemals normal zurück – löst HTTPException aus. Importierbar als from microdot import abort.

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

Kurzform für Response.redirect(). Importierbar als from microdot import redirect.

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

Kurzform für Response.send_file().

microdot.urlencode(s: str) → str

Prozent-codiert eine URL-Komponente. Ersetzt Zeichen, die in einer URL eine reservierte Bedeutung haben (/, ?, &, =, #, Leerzeichen, …), durch ihre %xx-Hex-Escapes, sodass das Ergebnis sicher in einem Pfadsegment oder Query-Wert platziert werden kann. Gibt den codierten str zurück.

microdot.urldecode(s: str) → str

Prozent-decodiert eine URL-Komponente – die Umkehrung von urlencode(). %xx-Escapes werden durch das Byte ersetzt, das sie codieren, und + wird in ein Leerzeichen umgewandelt (die historische Query-String-Konvention). Gibt den decodierten str zurück.

Submodule