microdot — minimal HTTP framework

Microdot, MicroPython için küçük, Flask’ten esinlenmiş bir HTTP framework’üdür. asyncio üzerinde çalışır, iş parçacıkları olmadan birden fazla eşzamanlı istemciyi yönetir ve tanıdık bir rota-dekoratör API’si sunar. Minimal bir uygulama şöyle görünü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

Bir HTTP uygulama örneği. Bir örnek, betiğin üst kısmında oluşturulur ve rota işleyicileriyle dekore edilir; run() çağrılması veya start_server() beklenmesi (await) sunmaya başlar.

Rota kaydı

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

Listelenen HTTP metotları altında url_pattern için bir işleyici kaydeden dekoratör (varsayılan ['GET']). Bir fonksiyona uygulandığında onu işleyici olarak kaydeden ve fonksiyonu değiştirmeden döndüren dekoratörü döndürür.

url_pattern

Bir yol deseni. Statik segmentleri (/users) ve < / > içine alınmış dinamik segmentleri destekler. Dinamik segmentler, : ile ayrılan isteğe bağlı bir tür ön eki kabul eder – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Varsayılan tür string şeklindedir.

methods

HTTP metot adlarının listesi. Atlanırsa, yalnızca GET eşleştirilir.

İşleyici önce request nesnesiyle, ardından yakalanan herhangi bir dinamik segment ile anahtar kelime argümanları olarak çağrılır. İşleyicinin dönüş değeri HTTP yanıtı olur: bir Response, bir dize, bir (body, status_code[, headers]) demeti veya bir dict / list (JSON olarak gönderilir).

get(url_pattern: str) → Callable

route(url_pattern, methods=['GET']) için kolaylık takma adı – dekore edilen fonksiyonu url_pattern için bir GET işleyicisi olarak kaydeder. Dekoratörü döndürür.

post(url_pattern: str) → Callable

route(url_pattern, methods=['POST']) için kolaylık takma adı – dekore edilen fonksiyonu url_pattern için bir POST işleyicisi olarak kaydeder. Dekoratörü döndürür.

put(url_pattern: str) → Callable

route(url_pattern, methods=['PUT']) için kolaylık takma adı – dekore edilen fonksiyonu url_pattern için bir PUT işleyicisi olarak kaydeder. Dekoratörü döndürür.

patch(url_pattern: str) → Callable

route(url_pattern, methods=['PATCH']) için kolaylık takma adı – dekore edilen fonksiyonu url_pattern için bir PATCH işleyicisi olarak kaydeder. Dekoratörü döndürür.

delete(url_pattern: str) → Callable

route(url_pattern, methods=['DELETE']) için kolaylık takma adı – dekore edilen fonksiyonu url_pattern için bir DELETE işleyicisi olarak kaydeder. Dekoratörü döndürür.

Yaşam döngüsü kancaları

before_request(f: Callable) → Callable

f‘nin her istekten önce çalışmasını kaydeden dekoratör. f request nesnesini alır; dönüş değeri normalde yok sayılır. İsteği kısa devre yaptırmak için bir Response (veya bir tanesine dönüştürülen bir değer) döndürün – bu durumda işlem hattının geri kalanı atlanır ve o yanıt gönderilir. f‘yi değiştirmeden döndürür.

after_request(f: Callable) → Callable

f‘nin her başarılı istekten sonra çalışmasını kaydeden dekoratör. f (request, response) alır ve (muhtemelen değiştirilmiş) response nesnesini döndürmelidir. f‘yi değiştirmeden döndürür.

after_error_request(f: Callable) → Callable

Microdot bir hata yanıtı (404, 500, fırlatılan istisna vb.) ürettikten sonra f‘nin çalışmasını kaydeden dekoratör. f (request, response) alır ve (muhtemelen değiştirilmiş) response nesnesini döndürmelidir. f‘yi değiştirmeden döndürür.

errorhandler(status_code_or_exception_class) → Callable

Bir HTTP durum kodu veya bir Python istisna sınıfı için özel bir işleyici kaydeden dekoratör. Durum kodları için işleyici yalnızca request’i alır; istisna sınıfları için (request, exception) alır. Dekoratörü döndürür.

Bağlama ve iptal etme

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

Başka bir Microdot örneğinin rotalarını url_prefix altında ekler. local False (varsayılan) olduğunda, alt uygulamanın before / after / error işleyicileri de üst uygulamaya eklenir. True olduğunda, bu işleyiciler yalnızca alt uygulama rotaları için çalışır. None döndürür.

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

Geçerli isteği verilen durum koduyla iptal etmek için HTTPException fırlatın. Normal şekilde asla dönmez – framework istisnayı yakalar ve onu karşılık gelen hata yanıtına dönüştürür. Rota gövdelerinin içinde kullanışlıdır:

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

Sunucuyu çalıştırma

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

Çağıran iş parçacığını bloke eder, start_server() üzerinde asyncio.run() çalıştırır. Yalnızca shutdown() çağrıldıktan ve dinleme döngüsü çıktıktan sonra None döndürür. Bağımsız bir uygulamayı başlatmanın en basit yolu:

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

Sunucuyu bir coroutine olarak başlatır. Bunu, diğer görevlerle birlikte mevcut bir asyncio olay döngüsüyle entegre olurken kullanın. Coroutine, shutdown() çağrılana kadar dönmez:

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

Dinlenecek ağ arayüzü. '0.0.0.0' (varsayılan) tüm arayüzler anlamına gelir; '127.0.0.1' yalnızca loopback anlamına gelir.

port

Dinlenecek TCP portu. Varsayılan 5000 – düz HTTP için 80, HTTPS için 443 seçin.

debug

True ise, her isteği günlüğe kaydeder ve geri izlemeleri (traceback) stdout’a döker.

ssl

Gelen bağlantıları TLS ile sarmalamak için bir ssl.SSLContext. None (varsayılan) düz HTTP anlamına gelir.

start_serving

Yalnızca CPython’da geçerlidir; MicroPython’da yok sayılır.

shutdown() → None

Zarif (graceful) bir sunucu kapatması ister. Bir rota işleyicisinden çağrılması güvenlidir – döngü çıkmadan önce geçerli istek tamamlanır. Hemen döner; gerçek kapatma, devam eden istek bittiğinde gerçekleşir.

Öznitelikler

url_map: list

Kayıtlı rotaların (methods, URLPattern, handler, url_prefix, subapp) demetleri olarak listesi.

before_request_handlers: list

before_request() ile kaydedilen çağrılabilirlerin, kayıt sırasına göre listesi. Her biri, rota işleyicisinden önce request nesnesiyle çalışır. Listeyi doğrudan değiştirmek işe yarar ancak nadiren gereklidir – dekoratörü tercih edin.

after_request_handlers: list

after_request() ile kaydedilen çağrılabilirlerin, kayıt sırasına göre listesi. Her biri, başarılı bir istekten sonra (request, response) ile çalışır ve (muhtemelen değiştirilmiş) yanıtı döndürmelidir.

after_error_request_handlers: list

after_error_request() ile kaydedilen çağrılabilirlerin, kayıt sırasına göre listesi. Her biri, (framework tarafından veya bir uygulama hata işleyicisi tarafından) bir hata yanıtı üretildikten sonra (request, response) ile çalışır ve yanıtı döndürmelidir.

error_handlers: dict

errorhandler() tarafından doldurulan, hata anahtarlarının işleyici çağrılabilirlerine eşlemesi. Anahtarlar ya HTTP durum kodları (int) ya da Python istisna sınıflarıdır; değerler kayıtlı işleyicilerdir. Durum kodu işleyicileri (request) alır; istisna sınıfı işleyicileri (request, exception) alır.

debug: bool

Sunucu debug=True ile çalışırken True.

class Request

class microdot.Request

Gelen bir HTTP isteği. Örnekler, rota işleyicilerine ilk konumsal argüman olarak iletilir. Uygulamalar Request‘i doğrudan oluşturmaz.

Sınıf öznitelikleri

max_content_length: int

Content-Length değeri bu kadar baytı aşan istekleri 413 yanıtıyla reddeder. Varsayılan 16 KB.

max_body_length: int

Belleğe arabelleğe alınan ve body aracılığıyla sunulan en büyük gövde. Daha büyük gövdeler (max_content_length değerine kadar) soket üzerinde kalır ve stream aracılığıyla okunmalıdır. Varsayılan 16 KB.

max_readline: int

Tek bir istek satırının / başlık satırının bayt cinsinden maksimum uzunluğu. Varsayılan 2 KB.

Örnek öznitelikleri

app: Microdot

İsteği işleyen Microdot örneği.

client_addr: tuple

İstemcinin (host, port) olarak adresi.

method: str

HTTP metot dizesi ('GET', 'POST', …).

scheme: str

'http' veya 'https'.

url: str

Tam istek URL yolu ve sorgu dizesi (host’tan sonraki her şey).

path: str

Yalnızca yol kısmı.

query_string: str | None

Ham sorgu dizesi kısmı veya None.

args: MultiDict

Bir MultiDict olarak ayrıştırılmış sorgu dizesi.

headers: NoCaseDict

Bir NoCaseDict olarak istek başlıkları (büyük/küçük harf duyarsız arama).

cookies: dict

Bir dict olarak ayrıştırılmış Cookie başlığı.

content_length: int

Tam sayı Content-Length değeri veya yoksa 0.

content_type: str | None

Content-Type başlık değeri veya None.

g: object

Serbest biçimli, isteğe özgü bir kapsayıcı (boş bir nesne). Kancalar ve işleyiciler arasında değer aktarmak için ona öznitelikler atayın (request.g.user = ...).

route: Callable

Bu istekle eşleşen işleyici fonksiyon.

url_prefix: str

Rotanın altına bağlandığı ön ek veya ''.

subapp: Microdot | None

Bağlı alt uygulama örneği veya None.

Gövdeye erişim

body: bytes

Tam istek gövdesi bytes olarak. Gövde akışla aktarılırken boştur (bkz. stream).

stream: object

Gövde üzerinde read() sunan bir asenkron akış nesnesi. Bunu max_body_length değerinden büyük gövdeler için kullanın.

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

JSON olarak ayrıştırılmış gövde (bir dict, list, str, int, float veya bool – yükün kodladığı her ne ise) veya Content-Type application/json değilse None.

form: MultiDict | None

Bir MultiDict olarak URL-kodlu form alanları veya None. multipart/form-data için rotayı microdot.multipart.with_form_data() ile dekore edin.

files: dict | None

microdot.multipart.with_form_data() tarafından doldurulan, {name: FileUpload} olarak yüklenen dosyalar. O dekoratör çalışana kadar None.

after_request(f: Callable) → Callable

İsteğe özgü bir after-request kancası kaydeder – uygulama düzeyindeki after-request işleyicilerinden sonra, yalnızca başarı durumunda çalışır. f (request, response) alır ve (muhtemelen değiştirilmiş) response nesnesini döndürmelidir. f‘yi değiştirmeden döndürür.

class Response

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

Bir HTTP yanıtı. Çoğu işleyici, Microdot’un otomatik olarak bir Response‘a dönüştürdüğü değerler döndürür; özel başlıklara veya belirli bir durum koduna ihtiyacınız olduğunda doğrudan bir tane oluşturun.

body

Yanıt gövdesi. str UTF-8 ile kodlanır; dict / list JSON olarak kodlanır ve Content-Type buna göre ayarlanır; bytes olduğu gibi gönderilir; dosya benzeri bir nesne veya asenkron üreteç akışla aktarılır.

status_code

Sayısal HTTP durumu. Varsayılan 200.

headers

Yanıt başlıklarının sözlüğü (büyük/küçük harf duyarsız).

reason

Özel neden ifadesi. 200 için varsayılan "OK", aksi takdirde "N/A" şeklindedir.

Sınıf öznitelikleri

default_content_type: str

Hiçbiri açıkça ayarlanmadığında kullanılan Content-Type. Varsayılan 'text/plain'.

default_send_file_max_age: int | None

max_age verilmediğinde send_file() için Cache-Control: max-age değeri. None (varsayılan) Cache-Control başlığı olmaması anlamına gelir.

send_file_buffer_size: int

send_file() akışı için yığın boyutu. Varsayılan 1024.

already_handled: None

Yanıtı doğrudan kendisi yazmış olan işleyicilerden döndürülen nöbetçi değer (WebSocket yükseltmeleri tarafından kullanılır). Her zaman None‘dır; önemli olan kimliğidir.

types_map: dict

İçerik türü çıkarımı için send_file() tarafından kullanılan uzantıdan mime türüne eşleme. css, gif, html, jpg, js, json, png, txt, svg eşler.

Metotlar

Bir Set-Cookie başlığı ekler. expires, önceden biçimlendirilmiş bir dize veya timetuple() içeren datetime benzeri bir nesne olabilir. None döndürür; başlık bu yanıta yerinde eklenir.

Verilen çerezi hemen sona erdiren bir Set-Cookie ayarlar. kwargs, set_cookie() ile aynı seçenekleri kabul eder (path, domain, secure, http_only, partitioned); expires ve max_age yok sayılır. None döndürür; başlık bu yanıta yerinde eklenir.

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

Bir yönlendirme yanıtı döndürür:

@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

Dosya sisteminden bir dosyayı yanıt gövdesi olarak akışla aktarır. Verilmezse content_type, types_map aracılığıyla uzantıdan çıkarılır. compressed=True, Content-Encoding: gzip ayarlar (dosya zaten sıkıştırılmış olmalıdır).

Uyarı

filename doğrudan açılır. Asla temizlenmemiş, kullanıcı tarafından sağlanan bir yol geçirmeyin – bunu yapmak rastgele dosya ifşasına izin verir.

İstisnalar

exception microdot.HTTPException

Bir isteği belirli bir durum koduyla kısa devre yaptırmak için abort() tarafından fırlatılır. Microdot bunu yakalar ve karşılık gelen hata yanıtına dönüştürür.

status_code: int

Döndürülecek sayısal HTTP durum kodu – abort()‘a geçirilen değer.

reason: str

Hata yanıtına dahil edilecek neden ifadesi. abort()‘a verilmezse, varsayılan olarak "<status_code> error" olur (ör. "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Bir rotanın URL deseninin derlenmiş biçimi. Microdot.route() tarafından otomatik olarak oluşturulur; uygulamalar nadiren doğrudan bir tane örnekler.

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

Rota desenlerinde kullanılmak üzere yeni bir dinamik-segment türü kaydeder. None döndürür; tür, sınıf düzeyindeki tür kayıt defterine eklenir. Örneğin bir <uuid:...> türü eklemek için:

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

parser, yakalanan dizeyi işleyiciye ulaşmadan önce dönüştüren isteğe bağlı bir çağrılabilirdir.

match(path: str) → dict | None

path‘i desene karşı eşleştirir ve yakalanan grupların bir dict’ini veya eşleşme yoksa None döndürür.

Yardımcı sınıflar

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

Anahtar başına birden fazla değer depolayan bir dict alt sınıfı. Aynı anahtarın birden fazla kez görünebildiği sorgu dizeleri ve URL-kodlu form gövdeleri için kullanılır (?tag=a&tag=b).

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

key için ilk değeri döndürür, isteğe bağlı olarak type (bir çağrılabilir) ile dönüştürülür. Anahtar eksikse veya dönüştürme başarısız olursa default döndürür; aksi takdirde (isteğe bağlı olarak dönüştürülmüş) değeri döndürür.

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

key için tüm değerleri bir liste olarak döndürür, isteğe bağlı olarak her değer type ile dönüştürülür. key mevcut değilse boş bir liste döndürür.

class microdot.NoCaseDict

Büyük/küçük harf duyarsız dize anahtarlarına sahip bir dict alt sınıfı. Request.headers ve Response.headers için kullanılır.

Modül düzeyindeki fonksiyonlar

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

Microdot.abort() için kısayol. Normal şekilde asla dönmez – HTTPException fırlatır. from microdot import abort olarak içe aktarılabilir.

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

Response.redirect() için kısayol. from microdot import redirect olarak içe aktarılabilir.

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

Response.send_file() için kısayol.

microdot.urlencode(s: str) → str

Bir URL bileşenini yüzde-kodlar. Bir URL’de ayrılmış anlamı olan karakterleri (/, ?, &, =, #, boşluk, …) %xx onaltılık kaçış dizileriyle değiştirir, böylece sonuç güvenli bir şekilde bir yol segmentinin veya sorgu değerinin içinde yer alabilir. Kodlanmış str‘yi döndürür.

microdot.urldecode(s: str) → str

Bir URL bileşenini yüzde-çözer – urlencode()‘un tersi. %xx kaçış dizileri kodladıkları baytla değiştirilir ve + bir boşluğa dönüştürülür (tarihsel sorgu dizesi geleneği). Çözülmüş str‘yi döndürür.

Alt modüller