microdot — minimális HTTP keretrendszer

A Microdot egy kicsi, Flask által inspirált HTTP keretrendszer MicroPythonhoz. Az asyncio tetején fut, szálak nélkül kezel több egyidejű klienst, és ismerős route-dekorátor API-t kínál. Egy minimális alkalmazás így néz ki:

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

Egy HTTP alkalmazáspéldány. Egy példányt a szkript elején hozunk létre, és route-kezelőkkel látunk el; a run() hívása vagy a start_server() bevárása indítja el a kiszolgálást.

Route-regisztráció

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

Dekorátor, amely a url_pattern mintához regisztrál egy kezelőt a felsorolt HTTP metódusok alatt (alapértelmezés ['GET']). Visszaadja azt a dekorátort, amely egy függvényre alkalmazva azt kezelőként regisztrálja, és változatlanul visszaadja a függvényt.

url_pattern

Egy útvonalminta. Támogat statikus szegmenseket (/users) és < / > közé zárt dinamikus szegmenseket. A dinamikus szegmensek elfogadnak egy opcionális típus-előtagot, amelyet : választ el – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Az alapértelmezett típus a string.

methods

HTTP metódusnevek listája. Ha kimarad, csak a GET illeszkedik.

A kezelő először a kérésobjektummal hívódik meg, majd az elkapott dinamikus szegmensekkel kulcsszó-argumentumként. A kezelő visszatérési értéke lesz a HTTP-válasz: egy Response, egy karakterlánc, egy (body, status_code[, headers]) tuple, vagy egy dict / list (JSON-ként elküldve).

get(url_pattern: str) → Callable

Kényelmi alias a route(url_pattern, methods=['GET']) számára – a dekorált függvényt a url_pattern GET kezelőjeként regisztrálja. Visszaadja a dekorátort.

post(url_pattern: str) → Callable

Kényelmi alias a route(url_pattern, methods=['POST']) számára – a dekorált függvényt a url_pattern POST kezelőjeként regisztrálja. Visszaadja a dekorátort.

put(url_pattern: str) → Callable

Kényelmi alias a route(url_pattern, methods=['PUT']) számára – a dekorált függvényt a url_pattern PUT kezelőjeként regisztrálja. Visszaadja a dekorátort.

patch(url_pattern: str) → Callable

Kényelmi alias a route(url_pattern, methods=['PATCH']) számára – a dekorált függvényt a url_pattern PATCH kezelőjeként regisztrálja. Visszaadja a dekorátort.

delete(url_pattern: str) → Callable

Kényelmi alias a route(url_pattern, methods=['DELETE']) számára – a dekorált függvényt a url_pattern DELETE kezelőjeként regisztrálja. Visszaadja a dekorátort.

Életciklus-horgok

before_request(f: Callable) → Callable

Dekorátor, amely az f függvényt minden kérés előtt futtatandóra regisztrálja. Az f a kérésobjektumot kapja meg; a visszatérési értékét általában figyelmen kívül hagyja. A kérés rövidre zárásához adjon vissza egy Response objektumot (vagy olyan értéket, amely azzá alakul) – ekkor a folyamat többi része kimarad, és az a válasz kerül elküldésre. Visszaadja az f függvényt változatlanul.

after_request(f: Callable) → Callable

Dekorátor, amely az f függvényt minden sikeres kérés után futtatandóra regisztrálja. Az f a (request, response) paramétereket kapja, és vissza kell adnia a (esetleg módosított) válaszobjektumot. Visszaadja az f függvényt változatlanul.

after_error_request(f: Callable) → Callable

Dekorátor, amely az f függvényt azután futtatandóra regisztrálja, hogy a Microdot hibaválaszt generál (404, 500, kiváltott kivétel stb.). Az f a (request, response) paramétereket kapja, és vissza kell adnia a (esetleg módosított) válaszobjektumot. Visszaadja az f függvényt változatlanul.

errorhandler(status_code_or_exception_class) → Callable

Dekorátor, amely egyéni kezelőt regisztrál egy HTTP státuszkódhoz vagy egy Python kivételosztályhoz. Státuszkódok esetén a kezelő csak a kérést kapja; kivételosztályok esetén a (request, exception) paramétereket. Visszaadja a dekorátort.

Csatolás és megszakítás

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

Egy másik Microdot példány route-jainak csatolása a url_prefix alá. Ha a local értéke False (alapértelmezés), az al-alkalmazás before / after / error kezelői a szülőhöz is csatolásra kerülnek. Ha True, ezek a kezelők csak az al-alkalmazás route-jaira futnak. Visszaadja a None értéket.

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

Váltson ki HTTPException kivételt az aktuális kérés megszakításához a megadott státuszkóddal. Soha nem tér vissza normálisan – a keretrendszer elkapja a kivételt, és a megfelelő hibaválasszá alakítja. Kényelmes a route-törzseken belül:

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

A kiszolgáló futtatása

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

Blokkolja a hívó szálat, és lefuttatja az asyncio.run() függvényt a start_server() metóduson. Csak a shutdown() meghívása és a figyelő ciklus kilépése után ad vissza None értéket. A legegyszerűbb mód egy önálló alkalmazás elindítására:

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

Indítsa el a kiszolgálót korutinként. Ezt akkor használja, amikor egy meglévő asyncio eseményhurokba integrálja más feladatok mellé. A korutin csak a shutdown() meghívásáig nem tér vissza:

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

A hálózati interfész, amelyen figyelni kell. A '0.0.0.0' (alapértelmezés) az összes interfészt jelenti; a '127.0.0.1' csak a loopbacket.

port

A figyelendő TCP port. Alapértelmezés 5000 – válassza a 80 portot egyszerű HTTP-hez, a 443 portot HTTPS-hez.

debug

Ha True, minden kérést naplóz, és a hibakövetéseket a stdoutra írja.

ssl

Egy ssl.SSLContext, amely a beérkező kapcsolatokat TLS-be csomagolja. A None (alapértelmezés) egyszerű HTTP-t jelent.

start_serving

Csak CPythonon releváns; MicroPythonon figyelmen kívül marad.

shutdown() → None

Kérje a kiszolgáló elegáns leállítását. Biztonságosan hívható route-kezelőből – az aktuális kérés befejeződik, mielőtt a hurok kilép. Azonnal visszatér; a tényleges leállás akkor történik, amikor a folyamatban lévő kérés befejeződik.

Attribútumok

url_map: list

A regisztrált route-ok listája (methods, URLPattern, handler, url_prefix, subapp) tuple-ökként.

before_request_handlers: list

A before_request() segítségével regisztrált hívhatók listája regisztrációs sorrendben. Mindegyik a kérésobjektummal fut le a route-kezelő előtt. A lista közvetlen módosítása működik, de ritkán szükséges – inkább a dekorátort használja.

after_request_handlers: list

A after_request() segítségével regisztrált hívhatók listája regisztrációs sorrendben. Mindegyik a (request, response) paraméterekkel fut egy sikeres kérés után, és vissza kell adnia a (esetleg módosított) választ.

after_error_request_handlers: list

A after_error_request() segítségével regisztrált hívhatók listája regisztrációs sorrendben. Mindegyik a (request, response) paraméterekkel fut, miután egy hibaválasz generálódik (a keretrendszer vagy egy alkalmazás-hibakezelő által), és vissza kell adnia a választ.

error_handlers: dict

Hibakulcsok hozzárendelése kezelő hívhatókhoz, amelyet az errorhandler() tölt fel. A kulcsok vagy HTTP státuszkódok (int), vagy Python kivételosztályok; az értékek a regisztrált kezelők. A státuszkód-kezelők a (request) paramétert kapják; a kivételosztály-kezelők a (request, exception) paramétereket.

debug: bool

True, amíg a kiszolgáló debug=True beállítással fut.

class Request

class microdot.Request

Egy beérkező HTTP kérés. A példányok a route-kezelőknek az első pozícionális argumentumként kerülnek átadásra. Az alkalmazások nem hozzák létre közvetlenül a Request objektumot.

Osztályattribútumok

max_content_length: int

Az olyan kérések elutasítása 413-as válasszal, amelyek Content-Length értéke meghaladja ezt a bájtszámot. Alapértelmezés 16 KB.

max_body_length: int

A legnagyobb törzs, amely a memóriába kerül pufferelésre, és a body attribútumon keresztül érhető el. A nagyobb törzsek (a max_content_length értékéig) a socketen maradnak, és a stream attribútumon keresztül kell beolvasni. Alapértelmezés 16 KB.

max_readline: int

Egyetlen kérés-sor / fejléc-sor maximális hossza bájtban. Alapértelmezés 2 KB.

Példányattribútumok

app: Microdot

A kérést kezelő Microdot példány.

client_addr: tuple

A kliens címe (host, port) formában.

method: str

A HTTP metódus karakterlánca ('GET', 'POST', …).

scheme: str

'http' vagy 'https'.

url: str

A teljes kérés URL-útvonala és lekérdezési karakterlánca (minden a host után).

path: str

Csak az útvonal-rész.

query_string: str | None

A nyers lekérdezési karakterlánc rész, vagy None.

args: MultiDict

Az elemzett lekérdezési karakterlánc MultiDict formában.

headers: NoCaseDict

A kérés fejlécei NoCaseDict formában (kis- és nagybetűre érzéketlen keresés).

cookies: dict

Az elemzett Cookie fejléc dict formában.

content_length: int

A Content-Length egész értéke, vagy 0, ha hiányzik.

content_type: str | None

A Content-Type fejléc értéke, vagy None.

g: object

Egy szabad formátumú, kérésenkénti tároló (egy üres objektum). Rendeljen hozzá attribútumokat, hogy értékeket adjon át a horgok és kezelők között (request.g.user = ...).

route: Callable

A kezelőfüggvény, amely illeszkedett erre a kérésre.

url_prefix: str

Az előtag, amely alá a route csatolásra került, vagy ''.

subapp: Microdot | None

A csatolt al-alkalmazás példánya, vagy None.

Törzs-hozzáférés

body: bytes

A teljes kéréstörzs bytes formában. Üres, amikor a törzs streamelve van (lásd stream).

stream: object

Egy aszinkron stream-objektum, amely read() műveletet kínál a törzs felett. Ezt használja a max_body_length értéknél nagyobb törzsekhez.

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

A JSON-ként elemzett törzs (egy dict, list, str, int, float vagy bool – bármi, amit a payload kódol), vagy None, ha a Content-Type nem application/json.

form: MultiDict | None

URL-kódolt űrlapmezők MultiDict formában, vagy None. A multipart/form-data esetén lássa el a route-ot a microdot.multipart.with_form_data() dekorátorral.

files: dict | None

Feltöltött fájlok {name: FileUpload} formában, amelyet a microdot.multipart.with_form_data() tölt fel. None, amíg az a dekorátor le nem fut.

after_request(f: Callable) → Callable

Egy kérés-lokális after-request horog regisztrálása – az alkalmazásszintű after-request kezelők után fut, csak siker esetén. Az f a (request, response) paramétereket kapja, és vissza kell adnia a (esetleg módosított) válaszobjektumot. Visszaadja az f függvényt változatlanul.

class Response

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

Egy HTTP válasz. A legtöbb kezelő olyan értékeket ad vissza, amelyeket a Microdot automatikusan Response objektummá alakít; közvetlenül akkor hozzon létre egyet, ha egyéni fejlécekre vagy konkrét státuszkódra van szüksége.

body

Válasz törzse. A str UTF-8 kódolású; a dict / list JSON-kódolású, és a Content-Type ennek megfelelően van beállítva; a bytes változatlanul kerül elküldésre; egy fájlszerű objektum vagy aszinkron generátor streamel.

status_code

Numerikus HTTP státusz. Alapértelmezés 200.

headers

A válasz fejléceinek dict-je (kis- és nagybetűre érzéketlen).

reason

Egyéni indokló szöveg. Alapértelmezés "OK" a 200 esetén, egyébként "N/A".

Osztályattribútumok

default_content_type: str

Az alapértelmezett Content-Type, amikor egy sincs explicit módon beállítva. Alapértelmezés 'text/plain'.

default_send_file_max_age: int | None

A Cache-Control: max-age érték a send_file() számára, amikor a max_age nincs megadva. A None (alapértelmezés) azt jelenti, hogy nincs Cache-Control fejléc.

send_file_buffer_size: int

A darabméret a send_file() streameléséhez. Alapértelmezés 1024.

already_handled: None

Az olyan kezelőkből visszaadott jelzőérték, amelyek már közvetlenül megírták a választ (WebSocket-frissítések használják). Mindig None; az identitása számít.

types_map: dict

A kiterjesztés-mime-típus leképezés, amelyet a send_file() használ a tartalomtípus következtetéséhez. A css, gif, html, jpg, js, json, png, txt, svg kiterjesztéseket képezi le.

Metódusok

Egy Set-Cookie fejléc hozzáadása. Az expires lehet egy előre formázott karakterlánc vagy egy datetime-szerű objektum timetuple() metódussal. Visszaadja a None értéket; a fejléc helyben hozzáfűződik ehhez a válaszhoz.

Egy Set-Cookie beállítása, amely a megadott sütit azonnal lejáratja. A kwargs ugyanazokat az opciókat fogadja el, mint a set_cookie() (path, domain, secure, http_only, partitioned); az expires és a max_age figyelmen kívül marad. Visszaadja a None értéket; a fejléc helyben hozzáfűződik ehhez a válaszhoz.

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

Egy átirányítási válasz visszaadása:

@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

Egy fájl streamelése a fájlrendszerből a válasz törzseként. A content_type a kiterjesztésből kerül következtetésre a types_map segítségével, ha nincs megadva. A compressed=True beállítja a Content-Encoding: gzip fejlécet (a fájlnak már tömörítettnek kell lennie).

Figyelem

A filename közvetlenül kerül megnyitásra. Soha ne adjon át fertőtlenítetlen, felhasználó által megadott útvonalat – ez tetszőleges fájl felfedését teszi lehetővé.

Kivételek

exception microdot.HTTPException

Az abort() által kiváltva egy kérés rövidre zárásához egy adott státuszkóddal. A Microdot elkapja ezt, és a megfelelő hibaválasszá alakítja.

status_code: int

A visszaadandó numerikus HTTP státuszkód – az abort() függvénynek átadott érték.

reason: str

A hibaválaszba foglalandó indokló szöveg. Ha nincs megadva az abort() függvénynek, alapértelmezése "<status_code> error" (pl. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Egy route URL-mintájának fordított formája. Automatikusan jön létre a Microdot.route() által; az alkalmazások ritkán példányosítanak egyet közvetlenül.

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

Egy új dinamikus-szegmens típus regisztrálása route-mintákban való használatra. Visszaadja a None értéket; a típus hozzáadódik az osztályszintű típusnyilvántartáshoz. Például egy <uuid:...> típus hozzáadásához:

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

A parser egy opcionális hívható, amely az elkapott karakterláncot átalakítja, mielőtt az eléri a kezelőt.

match(path: str) → dict | None

Illessze a path értéket a mintához, és adja vissza az elkapott csoportok dict-jét, vagy None értéket, ha nincs illeszkedés.

Segédosztályok

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

Egy dict alosztály, amely kulcsonként több értéket tárol. Lekérdezési karakterláncokhoz és URL-kódolt űrlaptörzsekhez használatos, ahol ugyanaz a kulcs egynél többször is megjelenhet (?tag=a&tag=b).

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

Adja vissza a key első értékét, opcionálisan a type (egy hívható) segítségével átalakítva. A default értéket adja vissza, ha a kulcs hiányzik vagy az átalakítás sikertelen; egyébként a (opcionálisan átalakított) értéket adja vissza.

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

Adja vissza a key összes értékét listaként, opcionálisan minden értéket a type segítségével átalakítva. Üres listát ad vissza, ha a key nincs jelen.

class microdot.NoCaseDict

Egy dict alosztály kis- és nagybetűre érzéketlen karakterlánc-kulcsokkal. A Request.headers és a Response.headers használja.

Modulszintű függvények

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

Gyorsbillentyű a Microdot.abort() számára. Soha nem tér vissza normálisan – HTTPException kivételt vált ki. Importálható from microdot import abort formában.

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

Gyorsbillentyű a Response.redirect() számára. Importálható from microdot import redirect formában.

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

Gyorsbillentyű a Response.send_file() számára.

microdot.urlencode(s: str) → str

Egy URL-komponens százalék-kódolása. Az URL-ben fenntartott jelentéssel bíró karaktereket (/, ?, &, =, #, szóköz, …) lecseréli a %xx hexadecimális escape-jeikre, hogy az eredmény biztonságosan elférjen egy útvonal-szegmensen vagy lekérdezési értéken belül. Visszaadja a kódolt str értéket.

microdot.urldecode(s: str) → str

Egy URL-komponens százalék-dekódolása – az urlencode() inverze. A %xx escape-ek lecserélődnek az általuk kódolt bájtra, és a + szóközre alakul (a régi lekérdezési karakterlánc konvenció). Visszaadja a dekódolt str értéket.

Almodulok