`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

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#: 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.

delete_cookie(cookie: str, **kwargs) → None#: 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.

microdot — minimalt HTTP-ramverk#

class Microdot#

class Request#

class Response#

Undantag#

class URLPattern#

Hjälpklasser#

Funktioner på modulnivå#

Undermoduler#

`microdot` — minimalt HTTP-ramverk#