microdot — minimalt HTTP-ramverk

Microdot är ett litet, Flask-inspirerat HTTP-ramverk för MicroPython. Det körs ovanpå asyncio, hanterar flera samtidiga klienter utan trådar och exponerar ett välbekant API med rutt-dekoratorer. En minimal applikation ser ut så här:

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

En HTTP-applikationsinstans. En instans skapas nära toppen av skriptet och dekoreras med rutthanterare; ett anrop till run() eller en await på start_server() påbörjar betjäningen.

Ruttregistrering

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

Dekorator som registrerar en hanterare för url_pattern under de angivna HTTP-metoderna (standard ['GET']). Returnerar dekoratorn som, när den tillämpas på en funktion, registrerar den som hanterare och returnerar funktionen oförändrad.

url_pattern

Ett sökvägsmönster. Stöder statiska segment (/users) och dynamiska segment inneslutna i < / >. Dynamiska segment accepterar ett valfritt typprefix avskilt med : – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Standardtypen är string.

methods

Lista med namn på HTTP-metoder. Om den utelämnas matchas endast GET.

Hanteraren anropas först med begärandeobjektet och sedan med eventuella infångade dynamiska segment som nyckelordsargument. Hanterarens returvärde blir HTTP-svaret: ett Response, en sträng, en tupel (body, status_code[, headers]), eller en dict / list (skickas som JSON).

get(url_pattern: str) → Callable

Bekvämt alias för route(url_pattern, methods=['GET']) – registrerar den dekorerade funktionen som en GET-hanterare för url_pattern. Returnerar dekoratorn.

post(url_pattern: str) → Callable

Bekvämt alias för route(url_pattern, methods=['POST']) – registrerar den dekorerade funktionen som en POST-hanterare för url_pattern. Returnerar dekoratorn.

put(url_pattern: str) → Callable

Bekvämt alias för route(url_pattern, methods=['PUT']) – registrerar den dekorerade funktionen som en PUT-hanterare för url_pattern. Returnerar dekoratorn.

patch(url_pattern: str) → Callable

Bekvämt alias för route(url_pattern, methods=['PATCH']) – registrerar den dekorerade funktionen som en PATCH-hanterare för url_pattern. Returnerar dekoratorn.

delete(url_pattern: str) → Callable

Bekvämt alias för route(url_pattern, methods=['DELETE']) – registrerar den dekorerade funktionen som en DELETE-hanterare för url_pattern. Returnerar dekoratorn.

Livscykelkrokar

before_request(f: Callable) → Callable

Dekorator som registrerar f så att den körs före varje begäran. f tar begärandeobjektet; dess returvärde ignoreras normalt. För att kortsluta begäran, returnera ett Response (eller ett värde som konverteras till ett) – resten av pipelinen hoppas då över och det svaret skickas. Returnerar f oförändrad.

after_request(f: Callable) → Callable

Dekorator som registrerar f så att den körs efter varje lyckad begäran. f tar (request, response) och måste returnera det (eventuellt modifierade) svarsobjektet. Returnerar f oförändrad.

after_error_request(f: Callable) → Callable

Dekorator som registrerar f så att den körs efter att Microdot har genererat ett felsvar (404, 500, kastat undantag etc.). f tar (request, response) och måste returnera det (eventuellt modifierade) svarsobjektet. Returnerar f oförändrad.

errorhandler(status_code_or_exception_class) → Callable

Dekorator som registrerar en anpassad hanterare för en HTTP-statuskod eller en Python-undantagsklass. För statuskoder tar hanteraren endast begäran; för undantagsklasser (request, exception). Returnerar dekoratorn.

Montering och avbrytande

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

Anslut en annan Microdot-instans rutter under url_prefix. När local är False (standard) ansluts delapplikationens before / after / error-hanterare även till föräldern. När True körs dessa hanterare endast för delapplikationens rutter. Returnerar None.

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

Kasta HTTPException för att avbryta den aktuella begäran med den angivna statuskoden. Returnerar aldrig normalt – ramverket fångar undantaget och omvandlar det till motsvarande felsvar. Bekvämt inuti ruttkroppar:

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

Köra servern

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

Blockera den anropande tråden och kör asyncio.run() på start_server(). Returnerar None först efter att shutdown() har anropats och lyssningsloopen avslutas. Det enklaste sättet att starta en fristående applikation:

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

Starta servern som en korutin. Använd detta vid integrering med en befintlig asyncio-händelseloop tillsammans med andra uppgifter. Korutinen returnerar inte förrän shutdown() anropas:

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

Nätverksgränssnitt att lyssna på. '0.0.0.0' (standard) betyder alla gränssnitt; '127.0.0.1' betyder endast loopback.

port

TCP-port att lyssna på. Standard 5000 – välj 80 för vanlig HTTP, 443 för HTTPS.

debug

Om True, logga varje begäran och dumpa stackspårningar till stdout.

ssl

Ett ssl.SSLContext för att inkapsla inkommande anslutningar i TLS. None (standard) betyder vanlig HTTP.

start_serving

Endast relevant på CPython; ignoreras på MicroPython.

shutdown() → None

Begär en kontrollerad serveravstängning. Säkert att anropa från en rutthanterare – den aktuella begäran slutförs innan loopen avslutas. Returnerar omedelbart; den faktiska avstängningen sker när den pågående begäran är klar.

Attribut

url_map: list

Lista över registrerade rutter som tupler (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list

Lista över anropbara objekt registrerade med before_request(), i registreringsordning. Varje körs med begärandeobjektet innan rutthanteraren. Att mutera listan direkt fungerar men behövs sällan – föredra dekoratorn.

after_request_handlers: list

Lista över anropbara objekt registrerade med after_request(), i registreringsordning. Varje körs med (request, response) efter en lyckad begäran och måste returnera det (eventuellt modifierade) svaret.

after_error_request_handlers: list

Lista över anropbara objekt registrerade med after_error_request(), i registreringsordning. Varje körs med (request, response) efter att ett felsvar har genererats (av ramverket eller av en applikationsfelhanterare) och måste returnera svaret.

error_handlers: dict

Mappning av felnycklar till anropbara hanterare, fylld av errorhandler(). Nycklar är antingen HTTP-statuskoder (int) eller Python-undantagsklasser; värden är de registrerade hanterarna. Statuskodshanterare tar (request); undantagsklasshanterare tar (request, exception).

debug: bool

True medan servern körs med debug=True.

class Request

class microdot.Request

En inkommande HTTP-begäran. Instanser skickas till rutthanterare som det första positionsargumentet. Applikationer konstruerar inte Request direkt.

Klassattribut

max_content_length: int

Avvisa begäranden vars Content-Length överstiger detta antal byte med ett 413-svar. Standard 16 KB.

max_body_length: int

Den största kropp som buffras i minnet och exponeras via body. Större kroppar (upp till max_content_length) stannar kvar på socketen och måste läsas via stream. Standard 16 KB.

max_readline: int

Maximal längd för en enskild begäranderad / headerrad i byte. Standard 2 KB.

Instansattribut

app: Microdot

Den Microdot-instans som hanterar begäran.

client_addr: tuple

Klientens adress som (host, port).

method: str

Sträng med HTTP-metoden ('GET', 'POST', …).

scheme: str

'http' eller 'https'.

url: str

Den fullständiga sökvägen och frågesträngen i begärande-URL:en (allt efter värden).

path: str

Endast sökvägsdelen.

query_string: str | None

Den råa frågesträngsdelen, eller None.

args: MultiDict

Tolkad frågesträng som en MultiDict.

headers: NoCaseDict

Begärandehuvuden som en NoCaseDict (skiftlägesokänslig uppslagning).

cookies: dict

Tolkat Cookie-huvud som en dict.

content_length: int

Heltalsvärdet för Content-Length, eller 0 om det saknas.

content_type: str | None

Värdet för Content-Type-huvudet, eller None.

g: object

En friformad behållare per begäran (ett kalt objekt). Tilldela attribut till den för att skicka värden mellan krokar och hanterare (request.g.user = ...).

route: Callable

Den hanterarfunktion som matchade denna begäran.

url_prefix: str

Prefixet som rutten monterades under, eller ''.

subapp: Microdot | None

Den monterade delapplikationsinstansen, eller None.

Åtkomst till kropp

body: bytes

Den fullständiga begärandekroppen som bytes. Tom när kroppen strömmas (se stream).

stream: object

Ett asynkront strömobjekt som exponerar read() över kroppen. Använd detta för kroppar större än max_body_length.

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

Kroppen tolkad som JSON (en dict, list, str, int, float eller bool – vad än nyttolasten kodar), eller None om Content-Type inte är application/json.

form: MultiDict | None

URL-kodade formulärfält som en MultiDict, eller None. För multipart/form-data, dekorera rutten med microdot.multipart.with_form_data().

files: dict | None

Uppladdade filer som {name: FileUpload}, fylls av microdot.multipart.with_form_data(). None tills den dekoratorn körs.

after_request(f: Callable) → Callable

Registrera en begärandelokal after-request-krok – körs efter after-request-hanterarna på applikationsnivå, endast vid framgång. f tar (request, response) och måste returnera det (eventuellt modifierade) svarsobjektet. Returnerar f oförändrad.

class Response

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

Ett HTTP-svar. De flesta hanterare returnerar värden som Microdot automatiskt konverterar till ett Response; konstruera ett direkt när du behöver anpassade huvuden eller en specifik statuskod.

body

Svarskropp. str UTF-8-kodas; dict / list JSON-kodas och Content-Type ställs in därefter; bytes skickas som det är; ett filliknande objekt eller en asynkron generator strömmas.

status_code

Numerisk HTTP-status. Standard 200.

headers

Dict med svarshuvuden (skiftlägesokänslig).

reason

Anpassad orsaksfras. Standardvärdet är "OK" för 200 och "N/A" annars.

Klassattribut

default_content_type: str

Content-Type som används när ingen anges explicit. Standard 'text/plain'.

default_send_file_max_age: int | None

Värdet Cache-Control: max-age för send_file() när max_age inte anges. None (standard) betyder inget Cache-Control-huvud.

send_file_buffer_size: int

Blockstorlek för strömning med send_file(). Standard 1024.

already_handled: None

Vaktvärde som returneras från hanterare som redan har skrivit svaret direkt (används av WebSocket-uppgraderingar). Alltid None; det är identiteten som spelar roll.

types_map: dict

Karta från filändelse till mime-typ som används av send_file() för härledning av content-type. Mappar css, gif, html, jpg, js, json, png, txt, svg.

Metoder

Lägg till ett Set-Cookie-huvud. expires kan vara en förformaterad sträng eller ett datetime-liknande objekt med timetuple(). Returnerar None; huvudet läggs till i detta svar på plats.

Ställ in en Set-Cookie som omedelbart låter den angivna cookien upphöra. kwargs accepterar samma alternativ som set_cookie() (path, domain, secure, http_only, partitioned); expires och max_age ignoreras. Returnerar None; huvudet läggs till i detta svar på plats.

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

Returnera ett omdirigeringssvar:

@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

Strömma en fil från filsystemet som svarskropp. content_type härleds från filändelsen via types_map om det inte anges. compressed=True ställer in Content-Encoding: gzip (filen måste redan vara komprimerad).

Varning

filename öppnas direkt. Skicka aldrig en osanerad användartillförd sökväg – att göra det möjliggör godtycklig filröjning.

Undantag

exception microdot.HTTPException

Kastas av abort() för att kortsluta en begäran med en specifik statuskod. Microdot fångar detta och omvandlar det till motsvarande felsvar.

status_code: int

Numerisk HTTP-statuskod att returnera – värdet som skickas till abort().

reason: str

Orsaksfras att inkludera i felsvaret. Om den inte ges till abort() är standardvärdet "<status_code> error" (t.ex. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Den kompilerade formen av en rutts URL-mönster. Konstrueras automatiskt av Microdot.route(); applikationer instansierar sällan en direkt.

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

Registrera en ny dynamisk-segment-typ för användning i ruttmönster. Returnerar None; typen läggs till i typregistret på klassnivå. Till exempel för att lägga till en <uuid:...>-typ:

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

parser är ett valfritt anropbart objekt som konverterar den infångade strängen innan den når hanteraren.

match(path: str) → dict | None

Matcha path mot mönstret och returnera en dict med infångade grupper, eller None vid ingen matchning.

Hjälpklasser

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

En dict-underklass som lagrar flera värden per nyckel. Används för frågesträngar och URL-kodade formulärkroppar där samma nyckel kan förekomma mer än en gång (?tag=a&tag=b).

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

Returnera det första värdet för key, valfritt konverterat med type (ett anropbart objekt). Returnerar default om nyckeln saknas eller konverteringen misslyckas; annars returneras det (valfritt konverterade) värdet.

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

Returnera alla värden för key som en lista, valfritt med varje värde konverterat av type. Returnerar en tom lista om key inte finns.

class microdot.NoCaseDict

En dict-underklass med skiftlägesokänsliga strängnycklar. Används för Request.headers och Response.headers.

Funktioner på modulnivå

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

Genväg för Microdot.abort(). Returnerar aldrig normalt – kastar HTTPException. Importerbar som from microdot import abort.

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

Genväg för Response.redirect(). Importerbar som from microdot import redirect.

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

Genväg för Response.send_file().

microdot.urlencode(s: str) → str

Procentkoda en URL-komponent. Ersätter tecken som har reserverad betydelse i en URL (/, ?, &, =, #, mellanslag, …) med deras %xx-hexescaper så att resultatet säkert kan placeras i ett sökvägssegment eller frågevärde. Returnerar den kodade str.

microdot.urldecode(s: str) → str

Procentavkoda en URL-komponent – inversen av urlencode(). %xx-escaper ersätts med byten de kodar, och + konverteras till ett mellanslag (den historiska frågesträngskonventionen). Returnerar den avkodade str.

Undermoduler