`microdot` --- إطار عمل HTTP بسيط#

Microdot هو إطار عمل HTTP صغير مستوحى من Flask لأجل MicroPython. يعمل فوق asyncio، ويتعامل مع عملاء متزامنين متعددين دون استخدام خيوط، ويوفر واجهة مألوفة قائمة على مزينات المسارات. يبدو التطبيق البسيط هكذا:

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])، أو قاموس / قائمة (تُرسل بصيغة 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 (أو قيمة تتحول إليها) -- عندئذ يُتخطى باقي خط المعالجة وتُرسل تلك الاستجابة. تُرجع 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#

يبدأ الخادم كروتين متزامن (coroutine). استخدم هذا عند الدمج مع حلقة أحداث 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، فسجِّل كل طلب وأخرِج تتبعات المكدس إلى 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#: قائمة بالكائنات القابلة للاستدعاء المسجلة بـ before_request()، بترتيب التسجيل. يُنفَّذ كل منها مع كائن الطلب قبل معالج المسار. يعمل تعديل القائمة مباشرةً لكنه نادرًا ما يُحتاج إليه -- يُفضَّل استخدام المزيِّن.

after_request_handlers: list#: قائمة بالكائنات القابلة للاستدعاء المسجلة بـ after_request()، بترتيب التسجيل. يُنفَّذ كل منها مع (request, response) بعد طلب ناجح ويجب أن يُرجع الاستجابة (ربما بعد تعديلها).

after_error_request_handlers: list#: قائمة بالكائنات القابلة للاستدعاء المسجلة بـ after_error_request()، بترتيب التسجيل. يُنفَّذ كل منها مع (request, response) بعد توليد استجابة خطأ (بواسطة الإطار أو بواسطة معالج خطأ في التطبيق) ويجب أن يُرجع الاستجابة.

error_handlers: dict#: تعيين (mapping) لمفاتيح الأخطاء إلى كائنات معالجة قابلة للاستدعاء، تُملأ بواسطة 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 كيلوبايت.

max_body_length: int#: أكبر جسم يُخزَّن مؤقتًا في الذاكرة ويُعرَض عبر body. تبقى الأجسام الأكبر (حتى max_content_length) على المقبس (socket) ويجب قراءتها عبر stream. الافتراضي 16 كيلوبايت.

max_readline: int#: أقصى طول لسطر طلب / سطر ترويسة واحد بالبايتات. الافتراضي 2 كيلوبايت.

سمات المثيل

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#: يسجل خطاف ما بعد الطلب محليًا للطلب -- يُنفَّذ بعد معالجات ما بعد الطلب على مستوى التطبيق، عند النجاح فقط. تأخذ 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: قاموس بترويسات الاستجابة (غير حساس لحالة الأحرف).
reason: عبارة سبب مخصصة. القيمة الافتراضية "OK" لأجل 200 و "N/A" فيما عدا ذلك.

سمات الصنف

default_content_type: str#: نوع المحتوى المستخدم عندما لا يُضبَط أي نوع صراحةً. الافتراضي '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#: حجم القطعة لأجل بث 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#

يُرجع استجابة إعادة توجيه:

@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 هو كائن قابل للاستدعاء اختياري يحوِّل السلسلة الملتقطة قبل أن تصل إلى المعالج.

match(path: str) → dict | None#: يطابق path مع النمط ويُرجع قاموسًا بالمجموعات الملتقطة، أو 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#: يشفِّر مكوِّن عنوان URL بترميز النسبة المئوية (percent-encode). يستبدل الأحرف ذات المعنى المحجوز في عنوان URL (/ و ? و & و = و # ومسافة ...) بهرَوبها الست عشري %xx بحيث يمكن أن توضع النتيجة بأمان داخل مقطع مسار أو قيمة استعلام. يُرجع str المشفرة.

microdot.urldecode(s: str) → str#: يفك تشفير مكوِّن عنوان URL من ترميز النسبة المئوية -- معكوس urlencode(). تُستبدَل هرَوبات %xx بالبايت الذي تشفره، وتُحوَّل + إلى مسافة (وفق العرف التاريخي لسلسلة الاستعلام). يُرجع str المفكوكة.

microdot --- إطار عمل HTTP بسيط#

class Microdot#

class Request#

class Response#

الاستثناءات#

class URLPattern#

أصناف مساعِدة#

دوال على مستوى الوحدة#

الوحدات الفرعية#

`microdot` --- إطار عمل HTTP بسيط#