microdot — minimalni HTTP okvir

Microdot je mali HTTP okvir za MicroPython nadahnut Flaskom. Radi povrh asyncio, opslužuje više istovremenih klijenata bez dretvi i nudi poznati API s dekoratorima ruta. Minimalna aplikacija izgleda ovako:

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

Instanca HTTP aplikacije. Jedna se instanca stvara pri vrhu skripte i ukrašava se rukovateljima ruta; pozivanje run() ili čekanje start_server() pokreće opsluživanje.

Registracija ruta

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

Dekorator koji registrira rukovatelja za url_pattern pod navedenim HTTP metodama (zadano ['GET']). Vraća dekorator koji, kada se primijeni na funkciju, registrira je kao rukovatelja i vraća funkciju nepromijenjenu.

url_pattern

Uzorak putanje. Podržava statičke segmente (/users) i dinamičke segmente ograđene znakovima < / >. Dinamički segmenti prihvaćaju opcionalni prefiks tipa odvojen znakom : – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Zadani tip je string.

methods

Popis naziva HTTP metoda. Ako se izostavi, podudara se samo GET.

Rukovatelj se poziva najprije s objektom zahtjeva, zatim sa svim uhvaćenim dinamičkim segmentima kao imenovanim argumentima. Povratna vrijednost rukovatelja postaje HTTP odgovor: Response, niz znakova, n-torka (body, status_code[, headers]) ili rječnik / popis (poslan kao JSON).

get(url_pattern: str) → Callable

Praktični alias za route(url_pattern, methods=['GET']) – registrira ukrašenu funkciju kao GET rukovatelja za url_pattern. Vraća dekorator.

post(url_pattern: str) → Callable

Praktični alias za route(url_pattern, methods=['POST']) – registrira ukrašenu funkciju kao POST rukovatelja za url_pattern. Vraća dekorator.

put(url_pattern: str) → Callable

Praktični alias za route(url_pattern, methods=['PUT']) – registrira ukrašenu funkciju kao PUT rukovatelja za url_pattern. Vraća dekorator.

patch(url_pattern: str) → Callable

Praktični alias za route(url_pattern, methods=['PATCH']) – registrira ukrašenu funkciju kao PATCH rukovatelja za url_pattern. Vraća dekorator.

delete(url_pattern: str) → Callable

Praktični alias za route(url_pattern, methods=['DELETE']) – registrira ukrašenu funkciju kao DELETE rukovatelja za url_pattern. Vraća dekorator.

Kuke životnog ciklusa

before_request(f: Callable) → Callable

Dekorator koji registrira f da se izvrši prije svakog zahtjeva. f prima objekt zahtjeva; njegova povratna vrijednost obično se zanemaruje. Da biste prekratili zahtjev, vratite Response (ili vrijednost koja se u njega pretvara) – ostatak cjevovoda se tada preskače i taj se odgovor šalje. Vraća f nepromijenjen.

after_request(f: Callable) → Callable

Dekorator koji registrira f da se izvrši nakon svakog uspješnog zahtjeva. f prima (request, response) i mora vratiti (eventualno izmijenjeni) objekt odgovora. Vraća f nepromijenjen.

after_error_request(f: Callable) → Callable

Dekorator koji registrira f da se izvrši nakon što Microdot generira odgovor s greškom (404, 500, podignuta iznimka itd.). f prima (request, response) i mora vratiti (eventualno izmijenjeni) objekt odgovora. Vraća f nepromijenjen.

errorhandler(status_code_or_exception_class) → Callable

Dekorator koji registrira prilagođenog rukovatelja za HTTP statusni kod ili Python klasu iznimke. Za statusne kodove rukovatelj prima samo zahtjev; za klase iznimki, (request, exception). Vraća dekorator.

Montiranje i prekidanje

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

Pridružuje rute druge Microdot instance pod url_prefix. Kada je local False (zadano), rukovatelji before / after / error podaplikacije također se pridružuju roditelju. Kada je True, ti se rukovatelji izvršavaju samo za rute podaplikacije. Vraća None.

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

Podignite HTTPException kako biste prekinuli trenutni zahtjev s navedenim statusnim kodom. Nikada ne vraća normalno – okvir hvata iznimku i pretvara je u odgovarajući odgovor s greškom. Praktično unutar tijela ruta:

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

Pokretanje poslužitelja

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

Blokira pozivajuću dretvu, pokreće asyncio.run() na start_server(). Vraća None tek nakon što je pozvana shutdown() i petlja osluškivanja izađe. Najjednostavniji način za pokretanje samostalne aplikacije:

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

Pokreće poslužitelj kao korutinu. Koristite ovo pri integraciji s postojećom asyncio petljom događaja uz druge zadatke. Korutina ne vraća dok se ne pozove shutdown()

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

Mrežno sučelje na kojem se osluškuje. '0.0.0.0' (zadano) znači sva sučelja; '127.0.0.1' znači samo povratnu petlju.

port

TCP priključak na kojem se osluškuje. Zadano 5000 – odaberite 80 za običan HTTP, 443 za HTTPS.

debug

Ako je True, bilježi svaki zahtjev i ispisuje tragove poziva na stdout.

ssl

Objekt ssl.SSLContext za omatanje dolaznih veza u TLS. None (zadano) znači običan HTTP.

start_serving

Relevantno samo na CPython; zanemareno na MicroPython.

shutdown() → None

Zahtijeva uredno gašenje poslužitelja. Sigurno za pozivanje iz rukovatelja rute – trenutni zahtjev se dovršava prije nego što petlja izađe. Vraća odmah; stvarno gašenje događa se nakon što završi zahtjev u tijeku.

Atributi

url_map: list

Popis registriranih ruta kao n-torke (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list

Popis pozivnih objekata registriranih s before_request(), redoslijedom registracije. Svaki se izvršava s objektom zahtjeva prije rukovatelja rute. Izravno mijenjanje popisa radi, ali rijetko je potrebno – radije koristite dekorator.

after_request_handlers: list

Popis pozivnih objekata registriranih s after_request(), redoslijedom registracije. Svaki se izvršava s (request, response) nakon uspješnog zahtjeva i mora vratiti (eventualno izmijenjeni) odgovor.

after_error_request_handlers: list

Popis pozivnih objekata registriranih s after_error_request(), redoslijedom registracije. Svaki se izvršava s (request, response) nakon što se generira odgovor s greškom (od strane okvira ili aplikacijskog rukovatelja greškama) i mora vratiti odgovor.

error_handlers: dict

Mapiranje ključeva grešaka na pozivne objekte rukovatelja, popunjeno metodom errorhandler(). Ključevi su ili HTTP statusni kodovi (int) ili Python klase iznimki; vrijednosti su registrirani rukovatelji. Rukovatelji statusnih kodova primaju (request); rukovatelji klasa iznimki primaju (request, exception).

debug: bool

True dok poslužitelj radi s debug=True.

class Request

class microdot.Request

Dolazni HTTP zahtjev. Instance se prosljeđuju rukovateljima ruta kao prvi pozicijski argument. Aplikacije ne stvaraju Request izravno.

Atributi klase

max_content_length: int

Odbija zahtjeve čiji Content-Length premašuje ovaj broj bajtova s odgovorom 413. Zadano 16 KB.

max_body_length: int

Najveće tijelo koje se međuspremnikom učitava u memoriju i izlaže putem body. Veća tijela (do max_content_length) ostaju na utičnici i moraju se čitati putem stream. Zadano 16 KB.

max_readline: int

Najveća duljina pojedinog retka zahtjeva / retka zaglavlja u bajtovima. Zadano 2 KB.

Atributi instance

app: Microdot

Instanca Microdot koja obrađuje zahtjev.

client_addr: tuple

Adresa klijenta kao (host, port).

method: str

Niz HTTP metode ('GET', 'POST', …).

scheme: str

'http' ili 'https'.

url: str

Puna putanja URL-a zahtjeva i niz upita (sve nakon hosta).

path: str

Samo dio s putanjom.

query_string: str | None

Sirovi dio niza upita ili None.

args: MultiDict

Raščlanjeni niz upita kao MultiDict.

headers: NoCaseDict

Zaglavlja zahtjeva kao NoCaseDict (pretraživanje neovisno o velikim i malim slovima).

cookies: dict

Raščlanjeno Cookie zaglavlje kao dict.

content_length: int

Cjelobrojna vrijednost Content-Length ili 0 ako je odsutna.

content_type: str | None

Vrijednost Content-Type zaglavlja ili None.

g: object

Slobodan spremnik po zahtjevu (goli objekt). Dodijelite mu atribute za prosljeđivanje vrijednosti između kuka i rukovatelja (request.g.user = ...).

route: Callable

Funkcija rukovatelja koja se podudarala s ovim zahtjevom.

url_prefix: str

Prefiks pod kojim je ruta montirana ili ''.

subapp: Microdot | None

Instanca montirane podaplikacije ili None.

Pristup tijelu

body: bytes

Puno tijelo zahtjeva kao bytes. Prazno kada se tijelo prenosi tokom (vidi stream).

stream: object

Asinkroni objekt toka koji izlaže read() nad tijelom. Koristite ovo za tijela veća od max_body_length.

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

Tijelo raščlanjeno kao JSON (dict, list, str, int, float ili bool – što god sadržaj kodira) ili None ako Content-Type nije application/json.

form: MultiDict | None

URL-kodirana polja obrasca kao MultiDict ili None. Za multipart/form-data ukrasite rutu s microdot.multipart.with_form_data().

files: dict | None

Učitane datoteke kao {name: FileUpload}, popunjeno s microdot.multipart.with_form_data(). None dok se taj dekorator ne izvrši.

after_request(f: Callable) → Callable

Registrira kuku after-request lokalnu za zahtjev – izvršava se nakon after-request rukovatelja na razini aplikacije, samo pri uspjehu. f prima (request, response) i mora vratiti (eventualno izmijenjeni) objekt odgovora. Vraća f nepromijenjen.

class Response

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

HTTP odgovor. Većina rukovatelja vraća vrijednosti koje Microdot automatski pretvara u Response; izgradite ga izravno kada vam trebaju prilagođena zaglavlja ili određeni statusni kod.

body

Tijelo odgovora. str se kodira u UTF-8; dict / list se kodira u JSON i Content-Type se postavlja u skladu s tim; bytes se šalje kakav jest; objekt nalik datoteci ili asinkroni generator se prenosi tokom.

status_code

Brojčani HTTP status. Zadano 200.

headers

Rječnik zaglavlja odgovora (neovisno o velikim i malim slovima).

reason

Prilagođeni razlog. Zadano "OK" za 200 i "N/A" inače.

Atributi klase

default_content_type: str

Content-Type koji se koristi kada nijedan nije izričito postavljen. Zadano 'text/plain'.

default_send_file_max_age: int | None

Vrijednost Cache-Control: max-age za send_file() kada max_age nije zadan. None (zadano) znači bez Cache-Control zaglavlja.

send_file_buffer_size: int

Veličina dijela za prijenos tokom kod send_file(). Zadano 1024.

already_handled: None

Stražar koji vraćaju rukovatelji koji su već izravno zapisali odgovor (koristi se kod WebSocket nadogradnji). Uvijek None; bitan je identitet.

types_map: dict

Mapa ekstenzija u MIME tipove koju send_file() koristi za zaključivanje tipa sadržaja. Mapira css, gif, html, jpg, js, json, png, txt, svg.

Metode

Dodaje Set-Cookie zaglavlje. expires može biti unaprijed oblikovani niz ili objekt nalik datetime s timetuple(). Vraća None; zaglavlje se dodaje na ovaj odgovor na mjestu.

Postavlja Set-Cookie koji odmah istječe zadani kolačić. kwargs prihvaća iste opcije kao set_cookie() (path, domain, secure, http_only, partitioned); expires i max_age se zanemaruju. Vraća None; zaglavlje se dodaje na ovaj odgovor na mjestu.

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

Vraća odgovor s preusmjeravanjem:

@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

Prenosi tokom datoteku iz datotečnog sustava kao tijelo odgovora. content_type se zaključuje iz ekstenzije putem types_map ako nije zadan. compressed=True postavlja Content-Encoding: gzip (datoteka već mora biti komprimirana).

Upozorenje

filename se otvara izravno. Nikada ne prosljeđujte neprovjerenu putanju koju je dao korisnik – to omogućuje proizvoljno otkrivanje datoteka.

Iznimke

exception microdot.HTTPException

Podiže je abort() kako bi prekratila zahtjev s određenim statusnim kodom. Microdot je hvata i pretvara u odgovarajući odgovor s greškom.

status_code: int

Brojčani HTTP statusni kod koji se vraća – vrijednost proslijeđena abort().

reason: str

Razlog koji se uključuje u odgovor s greškom. Ako nije zadan funkciji abort(), zadano je "<status_code> error" (npr. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Kompilirani oblik URL uzorka rute. Stvara ga automatski Microdot.route(); aplikacije ga rijetko izravno instanciraju.

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

Registrira novi tip dinamičkog segmenta za uporabu u uzorcima ruta. Vraća None; tip se dodaje u registar tipova na razini klase. Na primjer, za dodavanje <uuid:...> tipa:

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

parser je opcionalni pozivni objekt koji pretvara uhvaćeni niz prije nego što dođe do rukovatelja.

match(path: str) → dict | None

Podudara path s uzorkom i vraća rječnik uhvaćenih grupa ili None ako nema podudaranja.

Pomoćne klase

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

Podklasa rječnika koja pohranjuje više vrijednosti po ključu. Koristi se za nizove upita i URL-kodirana tijela obrazaca gdje se isti ključ može pojaviti više puta (?tag=a&tag=b).

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

Vraća prvu vrijednost za key, opcionalno pretvorenu s type (pozivni objekt). Vraća default ako ključ nedostaje ili pretvorba ne uspije; inače vraća (eventualno pretvorenu) vrijednost.

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

Vraća sve vrijednosti za key kao popis, opcionalno sa svakom vrijednošću pretvorenom s type. Vraća prazan popis ako key nije prisutan.

class microdot.NoCaseDict

Podklasa rječnika s ključevima neovisnim o velikim i malim slovima. Koristi se za Request.headers i Response.headers.

Funkcije na razini modula

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

Prečac za Microdot.abort(). Nikada ne vraća normalno – podiže HTTPException. Može se uvesti kao from microdot import abort.

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

Prečac za Response.redirect(). Može se uvesti kao from microdot import redirect.

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

Prečac za Response.send_file().

microdot.urlencode(s: str) → str

Postotno kodira komponentu URL-a. Zamjenjuje znakove koji imaju rezervirano značenje u URL-u (/, ?, &, =, #, razmak, …) njihovim %xx heksadecimalnim izlaznim oznakama tako da rezultat može sigurno stajati unutar segmenta putanje ili vrijednosti upita. Vraća kodirani str.

microdot.urldecode(s: str) → str

Postotno dekodira komponentu URL-a – inverz funkcije urlencode(). %xx izlazne oznake zamjenjuju se bajtom koji kodiraju, a + se pretvara u razmak (povijesna konvencija nizova upita). Vraća dekodirani str.

Podmoduli