`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

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

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

microdot — minimal HTTP framework#

class Microdot#

class Request#

class Response#

İstisnalar#

class URLPattern#

Yardımcı sınıflar#

Modül düzeyindeki fonksiyonlar#

Alt modüller#

`microdot` — minimal HTTP framework#