`microdot` — מסגרת HTTP מינימלית#

Microdot היא מסגרת HTTP קטנה בהשראת Flask עבור MicroPython. היא פועלת מעל asyncio, מטפלת בלקוחות מקבילים מרובים ללא תהליכונים, וחושפת API מוכר של מעטרי נתיב (route decorator). יישום מינימלי נראה כך:

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. מופע אחד נבנה בראש הסקריפט ומעוטר במטפלי נתיב; קריאה ל-run() או המתנה ל-start_server() מתחילה את ההגשה.

רישום נתיבים

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

מעטר הרושם מטפל עבור url_pattern תחת מתודות ה-HTTP המופיעות (ברירת מחדל ['GET']). מחזיר את המעטר אשר, בעת החלתו על פונקציה, רושם אותה כמטפל ומחזיר את הפונקציה ללא שינוי.

url_pattern: תבנית נתיב. תומכת במקטעים סטטיים (/users) ובמקטעים דינמיים המוקפים ב-< / >. מקטעים דינמיים מקבלים קידומת סוג אופציונלית המופרדת ב-: – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. סוג ברירת המחדל הוא string.
methods: רשימת שמות מתודות HTTP. אם מושמטת, רק GET מותאם.

המטפל נקרא תחילה עם אובייקט הבקשה, ולאחר מכן עם כל המקטעים הדינמיים שנלכדו כארגומנטי מילת מפתח. ערך ההחזרה של המטפל הופך לתגובת ה-HTTP: Response, מחרוזת, טאפל (body, status_code[, headers]), או dict / list (הנשלחים כ-JSON).

get(url_pattern: str) → Callable#: כינוי נוחות עבור route(url_pattern, methods=['GET']) – רושם את הפונקציה המעוטרת כמטפל GET עבור url_pattern. מחזיר את המעטר.

post(url_pattern: str) → Callable#: כינוי נוחות עבור route(url_pattern, methods=['POST']) – רושם את הפונקציה המעוטרת כמטפל POST עבור url_pattern. מחזיר את המעטר.

put(url_pattern: str) → Callable#: כינוי נוחות עבור route(url_pattern, methods=['PUT']) – רושם את הפונקציה המעוטרת כמטפל PUT עבור url_pattern. מחזיר את המעטר.

patch(url_pattern: str) → Callable#: כינוי נוחות עבור route(url_pattern, methods=['PATCH']) – רושם את הפונקציה המעוטרת כמטפל PATCH עבור url_pattern. מחזיר את המעטר.

delete(url_pattern: str) → Callable#: כינוי נוחות עבור route(url_pattern, methods=['DELETE']) – רושם את הפונקציה המעוטרת כמטפל DELETE עבור url_pattern. מחזיר את המעטר.

ווי מחזור חיים

before_request(f: Callable) → Callable#: מעטר הרושם את f לריצה לפני כל בקשה. f מקבל את אובייקט הבקשה; ערך ההחזרה שלו בדרך כלל מתעלמים ממנו. כדי לקצר את הבקשה, החזר Response (או ערך המומר לכזה) – שאר הצינור (pipeline) מדולג אז ותגובה זו נשלחת. מחזיר את f ללא שינוי.

after_request(f: Callable) → Callable#: מעטר הרושם את f לריצה לאחר כל בקשה מוצלחת. f מקבל (request, response) וחייב להחזיר את אובייקט התגובה (שיתכן ושונה). מחזיר את f ללא שינוי.

after_error_request(f: Callable) → Callable#: מעטר הרושם את f לריצה לאחר ש-Microdot מייצרת תגובת שגיאה (404, 500, חריגה שהורמה וכו«). f מקבל (request, response) וחייב להחזיר את אובייקט התגובה (שיתכן ושונה). מחזיר את f ללא שינוי.

errorhandler(status_code_or_exception_class) → Callable#: מעטר הרושם מטפל מותאם אישית עבור קוד מצב HTTP או מחלקת חריגה של Python. עבור קודי מצב, המטפל מקבל רק את הבקשה; עבור מחלקות חריגה, (request, exception). מחזיר את המעטר.

הרכבה וביטול

mount(subapp: Microdot, url_prefix: str = '', local: bool = False) → None#: מצרף את הנתיבים של מופע Microdot אחר תחת url_prefix. כאשר local הוא False (ברירת מחדל), מטפלי ה-before / after / error של תת-היישום מצורפים גם להורה. כאשר True, מטפלים אלה פועלים רק עבור נתיבי תת-היישום. מחזיר None.

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

הרם HTTPException כדי לבטל את הבקשה הנוכחית עם קוד המצב הנתון. לעולם לא מחזיר באופן רגיל – המסגרת לוכדת את החריגה והופכת אותה לתגובת השגיאה המתאימה. נוח בתוך גופי נתיב:

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

הרצת השרת

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

חוסם את התהליכון הקורא, מריץ asyncio.run() על start_server(). מחזיר None רק לאחר ש-shutdown() נקראה ולולאת ההאזנה יוצאת. הדרך הפשוטה ביותר להפעיל יישום עצמאי:

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#

מתחיל את השרת כקורוטינה. השתמש בכך בעת שילוב עם לולאת אירועים קיימת של asyncio לצד משימות אחרות. הקורוטינה אינה מחזירה עד ש-shutdown() נקראת:

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

host: ממשק הרשת להאזנה. '0.0.0.0' (ברירת מחדל) משמעו כל הממשקים; '127.0.0.1' משמעו loopback בלבד.
port: פורט TCP להאזנה. ברירת מחדל 5000 – בחר 80 עבור HTTP רגיל, 443 עבור HTTPS.
debug: אם True, רשום ביומן כל בקשה והדפס traceback ל-stdout.
ssl: ssl.SSLContext לעטיפת חיבורים נכנסים ב-TLS. None (ברירת מחדל) משמעו HTTP רגיל.
start_serving: רלוונטי רק ב-CPython; מתעלמים ממנו ב-MicroPython.

shutdown() → None#: מבקש כיבוי חינני של השרת. בטוח לקריאה ממטפל נתיב – הבקשה הנוכחית מסתיימת לפני שהלולאה יוצאת. מחזיר מיד; הכיבוי בפועל מתרחש לאחר שהבקשה שבטיפול מסתיימת.

תכונות

url_map: list#: רשימת הנתיבים הרשומים כטאפלים (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list#: רשימת הניתנים-לקריאה (callables) הרשומים עם before_request(), בסדר הרישום. כל אחד פועל עם אובייקט הבקשה לפני מטפל הנתיב. שינוי הרשימה ישירות עובד אך נדרש לעיתים רחוקות – העדף את המעטר.

after_request_handlers: list#: רשימת הניתנים-לקריאה (callables) הרשומים עם after_request(), בסדר הרישום. כל אחד פועל עם (request, response) לאחר בקשה מוצלחת וחייב להחזיר את התגובה (שיתכן ושונתה).

after_error_request_handlers: list#: רשימת הניתנים-לקריאה (callables) הרשומים עם after_error_request(), בסדר הרישום. כל אחד פועל עם (request, response) לאחר שתגובת שגיאה נוצרת (על ידי המסגרת או על ידי מטפל שגיאות של היישום) וחייב להחזיר את התגובה.

error_handlers: dict#: מיפוי של מפתחות שגיאה לניתנים-לקריאה של מטפלים, המאוכלס על ידי errorhandler(). המפתחות הם או קודי מצב HTTP (int) או מחלקות חריגה של Python; הערכים הם המטפלים הרשומים. מטפלי קודי מצב מקבלים (request); מטפלי מחלקות חריגה מקבלים (request, exception).

debug: bool#: True כל עוד השרת פועל עם debug=True.

class Request#

class microdot.Request#

בקשת HTTP נכנסת. מופעים מועברים למטפלי נתיב כארגומנט המיקומי הראשון. יישומים אינם בונים Request ישירות.

תכונות מחלקה

max_content_length: int#: דחה בקשות שה-Content-Length שלהן חורג ממספר בתים זה עם תגובת 413. ברירת מחדל 16 KB.

max_body_length: int#: הגוף הגדול ביותר המאוחסן בחוצץ בזיכרון ונחשף דרך body. גופים גדולים יותר (עד max_content_length) נשארים בשקע (socket) וחייבים להיקרא דרך stream. ברירת מחדל 16 KB.

max_readline: int#: האורך המרבי של שורת בקשה / שורת כותרת בודדת בבתים. ברירת מחדל 2 KB.

תכונות מופע

app: Microdot#: מופע ה-Microdot המטפל בבקשה.

client_addr: tuple#: כתובת הלקוח כ-(host, port).

method: str#: מחרוזת מתודת HTTP ('GET', 'POST', …).

scheme: str#: 'http' או 'https'.

url: str#: נתיב כתובת ה-URL המלא של הבקשה ומחרוזת השאילתה (כל מה שאחרי המארח).

path: str#: רק חלק הנתיב.

query_string: str | None#: חלק מחרוזת השאילתה הגולמי, או None.

args: MultiDict#: מחרוזת השאילתה המנותחת כ-MultiDict.

headers: NoCaseDict#: כותרות הבקשה כ-NoCaseDict (חיפוש שאינו תלוי-רישיות).

cookies: dict#: כותרת ה-Cookie המנותחת כ-dict.

content_length: int#: ערך ה-Content-Length כמספר שלם, או 0 אם נעדר.

content_type: str | None#: ערך כותרת ה-Content-Type, או None.

g: object#: מכל חופשי לכל בקשה (אובייקט ריק). הקצה לו תכונות כדי להעביר ערכים בין ווים למטפלים (request.g.user = ...).

route: Callable#: פונקציית המטפל שהתאימה לבקשה זו.

url_prefix: str#: הקידומת שתחתיה הורכב הנתיב, או ''.

subapp: Microdot | None#: מופע תת-היישום המורכב, או None.

גישה לגוף

body: bytes#: גוף הבקשה המלא כ-bytes. ריק כאשר הגוף מוזרם (ראה stream).

stream: object#: אובייקט זרם אסינכרוני החושף read() על הגוף. השתמש בכך עבור גופים גדולים מ-max_body_length.

json: dict | list | str | int | float | bool | None#: הגוף המנותח כ-JSON (dict, list, str, int, float או bool – מה שהמטען מקודד), או None אם ה-Content-Type אינו application/json.

form: MultiDict | None#: שדות טופס מקודדי-URL כ-MultiDict, או None. עבור multipart/form-data, עטר את הנתיב עם microdot.multipart.with_form_data().

files: dict | None#: קבצים שהועלו כ-{name: FileUpload}, המאוכלסים על ידי microdot.multipart.with_form_data(). None עד שמעטר זה פועל.

after_request(f: Callable) → Callable#: רשום וו after-request מקומי לבקשה – פועל לאחר מטפלי ה-after-request ברמת היישום, רק בהצלחה. f מקבל (request, response) וחייב להחזיר את אובייקט התגובה (שיתכן ושונה). מחזיר את f ללא שינוי.

class Response#

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

תגובת HTTP. רוב המטפלים מחזירים ערכים ש-Microdot ממירה ל-Response באופן אוטומטי; בנה אחת ישירות כאשר אתה זקוק לכותרות מותאמות אישית או לקוד מצב מסוים.

body: גוף התגובה. str מקודד ב-UTF-8; dict / list מקודד כ-JSON וה-Content-Type נקבע בהתאם; bytes נשלח כמות שהוא; אובייקט דמוי-קובץ או מחולל אסינכרוני מוזרם.
status_code: מצב HTTP מספרי. ברירת מחדל 200.
headers: Dict של כותרות תגובה (שאינו תלוי-רישיות).
reason: ביטוי סיבה מותאם אישית. ברירת מחדל "OK" עבור 200 ו-"N/A" אחרת.

תכונות מחלקה

default_content_type: str#: Content-Type המשמש כאשר אף אחד לא נקבע במפורש. ברירת מחדל 'text/plain'.

default_send_file_max_age: int | None#: ערך ה-Cache-Control: max-age עבור send_file() כאשר max_age אינו ניתן. None (ברירת מחדל) משמעו ללא כותרת Cache-Control.

send_file_buffer_size: int#: גודל מקטע (chunk) עבור הזרמת send_file(). ברירת מחדל 1024.

already_handled: None#: ערך מאזכר (sentinel) המוחזר ממטפלים שכבר כתבו את התגובה ישירות (משמש לשדרוגי WebSocket). תמיד None; הזהות היא מה שחשוב.

types_map: dict#: מפת סיומת-לטיפוס-mime המשמשת את send_file() להסקת טיפוס תוכן. ממפה css, gif, html, jpg, js, json, png, txt, svg.

מתודות

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#: מוסיף כותרת Set-Cookie. expires יכול להיות מחרוזת מעוצבת מראש או אובייקט דמוי-datetime עם timetuple(). מחזיר None; הכותרת מצורפת לתגובה זו במקום.

delete_cookie(cookie: str, **kwargs) → None#: קובע Set-Cookie שגורם לעוגייה הנתונה לפוג מיד. kwargs מקבל את אותן אפשרויות כמו set_cookie() (path, domain, secure, http_only, partitioned); מתעלמים מ-expires ו-max_age. מחזיר None; הכותרת מצורפת לתגובה זו במקום.

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

מחזיר תגובת הפניה (redirect):

@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#: מזרים קובץ ממערכת הקבצים כגוף התגובה. content_type מוסק מהסיומת דרך types_map אם אינו ניתן. compressed=True קובע Content-Encoding: gzip (הקובץ חייב להיות דחוס כבר).

אזהרה
filename נפתח ישירות. לעולם אל תעביר נתיב שסיפק המשתמש שלא עבר חיטוי – הדבר מאפשר חשיפת קבצים שרירותיים.

חריגות#

exception microdot.HTTPException#

מורם על ידי abort() כדי לקצר בקשה עם קוד מצב מסוים. Microdot לוכדת זאת והופכת זאת לתגובת השגיאה המתאימה.

status_code: int#: קוד מצב HTTP מספרי להחזרה – הערך שהועבר ל-abort().

reason: str#: ביטוי סיבה לכלילה בתגובת השגיאה. אם אינו ניתן ל-abort(), ברירת המחדל היא "<status_code> error" (למשל "404 error").

class URLPattern#

class microdot.URLPattern(url_pattern: str)#

הצורה המהודרת של תבנית ה-URL של נתיב. נבנית באופן אוטומטי על ידי Microdot.route(); יישומים נדיר שיוצרים מופע ישירות.

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

רושם סוג מקטע-דינמי חדש לשימוש בתבניות נתיב. מחזיר None; הסוג מתווסף לרישום הסוגים ברמת המחלקה. לדוגמה, כדי להוסיף סוג <uuid:...>

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

parser הוא ניתן-לקריאה (callable) אופציונלי הממיר את המחרוזת שנלכדה לפני שהיא מגיעה למטפל.

match(path: str) → dict | None#: התאם את path לתבנית והחזר dict של הקבוצות שנלכדו, או None בהיעדר התאמה.

מחלקות עזר#

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

תת-מחלקה של dict המאחסנת מספר ערכים לכל מפתח. משמשת עבור מחרוזות שאילתה וגופי טופס מקודדי-URL שבהם אותו מפתח יכול להופיע יותר מפעם אחת (?tag=a&tag=b).

get(key, default=None, type: Callable | None = None)#: מחזיר את הערך הראשון עבור key, אופציונלית מומר עם type (ניתן-לקריאה). מחזיר את default אם המפתח חסר או שההמרה נכשלת; אחרת מחזיר את הערך (המומר אופציונלית).

getlist(key, type: Callable | None = None) → list#: מחזיר את כל הערכים עבור key כרשימה, אופציונלית כשכל ערך מומר על ידי type. מחזיר רשימה ריקה אם key אינו קיים.

class microdot.NoCaseDict#: תת-מחלקה של dict עם מפתחות מחרוזת שאינם תלויי-רישיות. משמשת עבור Request.headers ו-Response.headers.

פונקציות ברמת המודול#

microdot.abort(status_code: int, reason: str | None = None) → None#: קיצור עבור Microdot.abort(). לעולם לא מחזיר באופן רגיל – מרים HTTPException. ניתן לייבא כ-from microdot import abort.

microdot.redirect(location: str, status_code: int = 302) → Response#: קיצור עבור Response.redirect(). ניתן לייבא כ-from microdot import redirect.

microdot.send_file(filename: str, **kwargs) → Response#: קיצור עבור Response.send_file().

microdot.urlencode(s: str) → str#: מקודד באחוזים (percent-encode) רכיב URL. מחליף תווים בעלי משמעות שמורה ב-URL (/, ?, &, =, #, רווח, …) בבריחות (escapes) ההקסדצימליות שלהם %xx כך שהתוצאה יכולה לשבת בבטחה בתוך מקטע נתיב או ערך שאילתה. מחזיר את ה-str המקודד.

microdot.urldecode(s: str) → str#: מפענח באחוזים (percent-decode) רכיב URL – ההפך מ-urlencode(). בריחות %xx מוחלפות בבית שהן מקודדות, ו-+ מומר לרווח (מוסכמת מחרוזת השאילתה ההיסטורית). מחזיר את ה-str המפוענח.

microdot — מסגרת HTTP מינימלית#

class Microdot#

class Request#

class Response#

חריגות#

class URLPattern#

מחלקות עזר#

פונקציות ברמת המודול#

תת-מודולים#

`microdot` — מסגרת HTTP מינימלית#