microdot — minimaalinen HTTP-kehys

Microdot on pieni, Flaskista inspiroitunut HTTP-kehys MicroPythonille. Se toimii asyncio-kirjaston päällä, käsittelee useita samanaikaisia asiakkaita ilman säikeitä ja tarjoaa tutun reittikoristelijoiden (route decorator) API:n. Minimaalinen sovellus näyttää tältä:

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

HTTP-sovellusinstanssi. Yksi instanssi muodostetaan lähellä skriptin alkua ja koristellaan reittikäsittelijöillä; run()-metodin kutsuminen tai start_server()-metodin odottaminen aloittaa palvelemisen.

Reittien rekisteröinti

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

Koristelija, joka rekisteröi käsittelijän url_pattern-osoitteelle lueteltujen HTTP-metodien alle (oletus ['GET']). Palauttaa koristelijan, joka funktioon sovellettaessa rekisteröi sen käsittelijäksi ja palauttaa funktion muuttumattomana.

url_pattern

Polkukaava. Tukee staattisia segmenttejä (/users) ja dynaamisia segmenttejä, jotka on ympäröity merkeillä < / >. Dynaamiset segmentit hyväksyvät valinnaisen tyyppietuliitteen, joka erotetaan merkillä : – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Oletustyyppi on string.

methods

Lista HTTP-metodien nimistä. Jos jätetään pois, vain GET täsmää.

Käsittelijää kutsutaan ensin request-objektilla, sitten mahdollisilla siepatuilla dynaamisilla segmenteillä avainsana-argumentteina. Käsittelijän paluuarvosta tulee HTTP-vastaus: Response, merkkijono, monikko (body, status_code[, headers]) tai dict / list (lähetetään JSON-muodossa).

get(url_pattern: str) → Callable

Käytännöllinen alias ilmaukselle route(url_pattern, methods=['GET']) – rekisteröi koristellun funktion GET-käsittelijäksi url_pattern-osoitteelle. Palauttaa koristelijan.

post(url_pattern: str) → Callable

Käytännöllinen alias ilmaukselle route(url_pattern, methods=['POST']) – rekisteröi koristellun funktion POST-käsittelijäksi url_pattern-osoitteelle. Palauttaa koristelijan.

put(url_pattern: str) → Callable

Käytännöllinen alias ilmaukselle route(url_pattern, methods=['PUT']) – rekisteröi koristellun funktion PUT-käsittelijäksi url_pattern-osoitteelle. Palauttaa koristelijan.

patch(url_pattern: str) → Callable

Käytännöllinen alias ilmaukselle route(url_pattern, methods=['PATCH']) – rekisteröi koristellun funktion PATCH-käsittelijäksi url_pattern-osoitteelle. Palauttaa koristelijan.

delete(url_pattern: str) → Callable

Käytännöllinen alias ilmaukselle route(url_pattern, methods=['DELETE']) – rekisteröi koristellun funktion DELETE-käsittelijäksi url_pattern-osoitteelle. Palauttaa koristelijan.

Elinkaaren koukut

before_request(f: Callable) → Callable

Koristelija, joka rekisteröi funktion f suoritettavaksi ennen jokaista pyyntöä. f ottaa request-objektin; sen paluuarvo yleensä jätetään huomiotta. Pyynnön oikosulkemiseksi palauta Response (tai arvo, joka muuntuu sellaiseksi) – loput putkesta ohitetaan tällöin ja kyseinen vastaus lähetetään. Palauttaa funktion f muuttumattomana.

after_request(f: Callable) → Callable

Koristelija, joka rekisteröi funktion f suoritettavaksi jokaisen onnistuneen pyynnön jälkeen. f ottaa parametrit (request, response) ja sen on palautettava (mahdollisesti muokattu) vastausobjekti. Palauttaa funktion f muuttumattomana.

after_error_request(f: Callable) → Callable

Koristelija, joka rekisteröi funktion f suoritettavaksi sen jälkeen, kun Microdot on generoinut virhevastauksen (404, 500, nostettu poikkeus jne.). f ottaa parametrit (request, response) ja sen on palautettava (mahdollisesti muokattu) vastausobjekti. Palauttaa funktion f muuttumattomana.

errorhandler(status_code_or_exception_class) → Callable

Koristelija, joka rekisteröi mukautetun käsittelijän HTTP-tilakoodille tai Python-poikkeusluokalle. Tilakoodien tapauksessa käsittelijä ottaa vain request-objektin; poikkeusluokkien tapauksessa parametrit (request, exception). Palauttaa koristelijan.

Liittäminen ja keskeyttäminen

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

Liittää toisen Microdot-instanssin reitit url_prefix-etuliitteen alle. Kun local on False (oletus), aliosovelluksen before- / after- / error-käsittelijät liitetään myös vanhempaan. Kun True, nämä käsittelijät suoritetaan vain aliosovelluksen reiteille. Palauttaa None.

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

Nosta HTTPException keskeyttääksesi nykyisen pyynnön annetulla tilakoodilla. Ei koskaan palaa normaalisti – kehys sieppaa poikkeuksen ja muuntaa sen vastaavaksi virhevastaukseksi. Käytännöllinen reittien rungoissa:

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

Palvelimen käynnistäminen

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

Estää kutsuvan säikeen, suorittaa asyncio.run()-kutsun start_server()-metodille. Palauttaa None vasta sen jälkeen, kun shutdown() on kutsuttu ja kuuntelusilmukka päättyy. Yksinkertaisin tapa käynnistää itsenäinen sovellus:

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

Käynnistää palvelimen korutiinina. Käytä tätä, kun integroit olemassa olevaan asyncio-tapahtumasilmukkaan muiden tehtävien rinnalla. Korutiini ei palaa ennen kuin shutdown() kutsutaan:

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

Verkkoliitäntä, jota kuunnellaan. '0.0.0.0' (oletus) tarkoittaa kaikkia liitäntöjä; '127.0.0.1' tarkoittaa vain takaisinkytkentää (loopback).

port

TCP-portti, jota kuunnellaan. Oletus 5000 – valitse 80 tavalliselle HTTP:lle, 443 HTTPS:lle.

debug

Jos True, kirjaa jokaisen pyynnön ja tulostaa pinojäljet stdout-virtaan.

ssl

Objekti ssl.SSLContext, joka kääräisee saapuvat yhteydet TLS:ään. None (oletus) tarkoittaa tavallista HTTP:tä.

start_serving

Relevantti vain CPythonissa; jätetään huomiotta MicroPythonissa.

shutdown() → None

Pyytää palvelimen siistiä alasajoa. Turvallinen kutsua reittikäsittelijästä – nykyinen pyyntö valmistuu ennen kuin silmukka päättyy. Palaa välittömästi; varsinainen alasajo tapahtuu, kun käynnissä oleva pyyntö valmistuu.

Attribuutit

url_map: list

Lista rekisteröidyistä reiteistä monikkoina (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list

Lista before_request()-metodilla rekisteröidyistä kutsuttavista, rekisteröintijärjestyksessä. Kukin suoritetaan request-objektilla ennen reittikäsittelijää. Listan suora muuttaminen toimii, mutta on harvoin tarpeen – suosi koristelijaa.

after_request_handlers: list

Lista after_request()-metodilla rekisteröidyistä kutsuttavista, rekisteröintijärjestyksessä. Kukin suoritetaan parametreilla (request, response) onnistuneen pyynnön jälkeen ja sen on palautettava (mahdollisesti muokattu) vastaus.

after_error_request_handlers: list

Lista after_error_request()-metodilla rekisteröidyistä kutsuttavista, rekisteröintijärjestyksessä. Kukin suoritetaan parametreilla (request, response) virhevastauksen generoinnin jälkeen (kehyksen tai sovelluksen virhekäsittelijän toimesta) ja sen on palautettava vastaus.

error_handlers: dict

Kuvaus virheavaimista käsittelijäkutsuttaviin, jonka täyttää errorhandler(). Avaimet ovat joko HTTP-tilakoodeja (int) tai Python-poikkeusluokkia; arvot ovat rekisteröityjä käsittelijöitä. Tilakoodikäsittelijät ottavat (request); poikkeusluokkakäsittelijät ottavat (request, exception).

debug: bool

True niin kauan kuin palvelin on käynnissä asetuksella debug=True.

class Request

class microdot.Request

Saapuva HTTP-pyyntö. Instanssit välitetään reittikäsittelijöille ensimmäisenä positionaalisena argumenttina. Sovellukset eivät muodosta Request-objekteja suoraan.

Luokka-attribuutit

max_content_length: int

Hylkää pyynnöt, joiden Content-Length ylittää tämän tavumäärän, 413-vastauksella. Oletus 16 KB.

max_body_length: int

Suurin runko, joka puskuroidaan muistiin ja paljastetaan body-attribuutin kautta. Suuremmat rungot (aina arvoon max_content_length asti) jäävät socketille ja ne on luettava stream-attribuutin kautta. Oletus 16 KB.

max_readline: int

Yksittäisen pyyntörivin / otsikkorivin enimmäispituus tavuina. Oletus 2 KB.

Instanssin attribuutit

app: Microdot

Pyyntöä käsittelevä Microdot-instanssi.

client_addr: tuple

Asiakkaan osoite muodossa (host, port).

method: str

HTTP-metodin merkkijono ('GET', 'POST', …).

scheme: str

'http' tai 'https'.

url: str

Täydellinen pyynnön URL-polku ja kyselymerkkijono (kaikki isännän jälkeen).

path: str

Pelkkä polkuosa.

query_string: str | None

Raaka kyselymerkkijono-osa, tai None.

args: MultiDict

Jäsennetty kyselymerkkijono MultiDict-objektina.

headers: NoCaseDict

Pyynnön otsikot NoCaseDict-objektina (kirjainkoosta riippumaton haku).

cookies: dict

Jäsennetty Cookie-otsikko dict-objektina.

content_length: int

Kokonaislukuarvo Content-Length, tai 0 jos puuttuu.

content_type: str | None

Content-Type-otsikon arvo, tai None.

g: object

Vapaamuotoinen pyyntökohtainen säiliö (paljas objekti). Aseta siihen attribuutteja välittääksesi arvoja koukkujen ja käsittelijöiden välillä (request.g.user = ...).

route: Callable

Käsittelijäfunktio, joka täsmäsi tähän pyyntöön.

url_prefix: str

Etuliite, jonka alle reitti liitettiin, tai ''.

subapp: Microdot | None

Liitetty aliosovellusinstanssi, tai None.

Rungon käyttö

body: bytes

Täydellinen pyynnön runko bytes-muodossa. Tyhjä, kun runkoa virtautetaan (katso stream).

stream: object

Asynkroninen virtaobjekti, joka tarjoaa read()-metodin rungon yli. Käytä tätä rungoille, jotka ovat suurempia kuin max_body_length.

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

JSON-muodossa jäsennetty runko (dict, list, str, int, float tai bool – mitä tahansa hyötykuorma koodaa), tai None jos Content-Type ei ole application/json.

form: MultiDict | None

URL-koodatut lomakekentät MultiDict-objektina, tai None. Tyypille multipart/form-data koristele reitti funktiolla microdot.multipart.with_form_data().

files: dict | None

Ladatut tiedostot muodossa {name: FileUpload}, jonka täyttää microdot.multipart.with_form_data(). None, kunnes kyseinen koristelija suoritetaan.

after_request(f: Callable) → Callable

Rekisteröi pyyntökohtaisen after-request-koukun – suoritetaan sovellustason after-request-käsittelijöiden jälkeen, vain onnistuessa. f ottaa parametrit (request, response) ja sen on palautettava (mahdollisesti muokattu) vastausobjekti. Palauttaa funktion f muuttumattomana.

class Response

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

HTTP-vastaus. Useimmat käsittelijät palauttavat arvoja, jotka Microdot muuntaa Response-objektiksi automaattisesti; muodosta sellainen suoraan, kun tarvitset mukautettuja otsikoita tai tietyn tilakoodin.

body

Vastauksen runko. str koodataan UTF-8:lla; dict / list koodataan JSON:ksi ja Content-Type asetetaan sen mukaisesti; bytes lähetetään sellaisenaan; tiedostonkaltainen objekti tai asynkroninen generaattori virtautetaan.

status_code

Numeerinen HTTP-tilakoodi. Oletus 200.

headers

Vastausotsikoiden dict (kirjainkoosta riippumaton).

reason

Mukautettu syylause. Oletuksena "OK" koodille 200 ja muutoin "N/A".

Luokka-attribuutit

default_content_type: str

Content-Type, jota käytetään, kun mitään ei ole asetettu eksplisiittisesti. Oletus 'text/plain'.

default_send_file_max_age: int | None

Arvo Cache-Control: max-age metodille send_file(), kun max_age ei ole annettu. None (oletus) tarkoittaa, ettei Cache-Control-otsikkoa ole.

send_file_buffer_size: int

Lohkokoko send_file()-virtautukselle. Oletus 1024.

already_handled: None

Vartiomerkki (sentinel), jonka palauttavat käsittelijät, jotka ovat jo kirjoittaneet vastauksen suoraan (käytetään WebSocket-päivityksissä). Aina None; merkitsevää on identiteetti.

types_map: dict

Laajennus-MIME-tyyppi-kartta, jota send_file() käyttää sisältötyypin päättelyyn. Kartoittaa arvot css, gif, html, jpg, js, json, png, txt, svg.

Metodit

Lisää Set-Cookie-otsikon. expires voi olla valmiiksi muotoiltu merkkijono tai datetime-tyyppinen objekti, jolla on timetuple(). Palauttaa None; otsikko lisätään tähän vastaukseen paikan päällä.

Asettaa Set-Cookie-otsikon, joka vanhentaa annetun evästeen välittömästi. kwargs hyväksyy samat asetukset kuin set_cookie() (path, domain, secure, http_only, partitioned); expires ja max_age jätetään huomiotta. Palauttaa None; otsikko lisätään tähän vastaukseen paikan päällä.

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

Palauttaa uudelleenohjausvastauksen:

@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

Virtauttaa tiedoston tiedostojärjestelmästä vastauksen rungoksi. content_type päätellään laajennuksesta types_map-kartan kautta, jos sitä ei anneta. compressed=True asettaa Content-Encoding: gzip (tiedoston on jo oltava pakattu).

Varoitus

filename avataan suoraan. Älä koskaan välitä puhdistamatonta käyttäjän antamaa polkua – sen tekeminen mahdollistaa mielivaltaisten tiedostojen paljastamisen.

Poikkeukset

exception microdot.HTTPException

Nostaa abort(), jotta pyyntö oikosuljetaan tietyllä tilakoodilla. Microdot sieppaa tämän ja muuntaa sen vastaavaksi virhevastaukseksi.

status_code: int

Numeerinen HTTP-tilakoodi, joka palautetaan – arvo, joka välitettiin funktiolle abort().

reason: str

Syylause, joka sisällytetään virhevastaukseen. Jos sitä ei anneta funktiolle abort(), oletuksena on "<status_code> error" (esim. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Reitin URL-kaavan käännetty muoto. Sen muodostaa automaattisesti Microdot.route(); sovellukset harvoin instantioivat sellaisen suoraan.

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

Rekisteröi uuden dynaamisen segmentin tyypin käytettäväksi reittikaavoissa. Palauttaa None; tyyppi lisätään luokkatason tyyppirekisteriin. Esimerkiksi <uuid:...>-tyypin lisäämiseksi:

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

parser on valinnainen kutsuttava, joka muuntaa siepatun merkkijonon ennen kuin se saapuu käsittelijälle.

match(path: str) → dict | None

Täsmää path kaavaa vastaan ja palauttaa dict-objektin siepatuista ryhmistä, tai None jos ei täsmää.

Apuluokat

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

dict-aliluokka, joka tallentaa useita arvoja avainta kohti. Käytetään kyselymerkkijonoihin ja URL-koodattuihin lomakerunkoihin, joissa sama avain voi esiintyä useammin kuin kerran (?tag=a&tag=b).

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

Palauttaa ensimmäisen arvon avaimelle key, valinnaisesti muunnettuna type-parametrilla (kutsuttava). Palauttaa default, jos avain puuttuu tai muunnos epäonnistuu; muutoin palauttaa (valinnaisesti muunnetun) arvon.

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

Palauttaa kaikki arvot avaimelle key listana, valinnaisesti kukin arvo muunnettuna type-parametrilla. Palauttaa tyhjän listan, jos key ei ole läsnä.

class microdot.NoCaseDict

dict-aliluokka, jonka merkkijonoavaimet ovat kirjainkoosta riippumattomia. Käytetään Request.headers- ja Response.headers-attribuuteille.

Moduulitason funktiot

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

Pikakuvake metodille Microdot.abort(). Ei koskaan palaa normaalisti – nostaa HTTPException. Tuotavissa muodossa from microdot import abort.

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

Pikakuvake metodille Response.redirect(). Tuotavissa muodossa from microdot import redirect.

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

Pikakuvake metodille Response.send_file().

microdot.urlencode(s: str) → str

Prosenttikoodaa URL-komponentin. Korvaa merkit, joilla on varattu merkitys URL:ssä (/, ?, &, =, #, välilyönti, …), niiden %xx-heksaesckaussekvensseillä, jotta tulos voi turvallisesti sijaita polkusegmentin tai kyselyarvon sisällä. Palauttaa koodatun str-merkkijonon.

microdot.urldecode(s: str) → str

Prosenttidekoodaa URL-komponentin – funktion urlencode() käänteisoperaatio. %xx-eskaussekvenssit korvataan tavulla, jonka ne koodaavat, ja + muunnetaan välilyönniksi (historiallinen kyselymerkkijonokäytäntö). Palauttaa dekoodatun str-merkkijonon.

Alimoduulit