`microdot.multipart` --- تحليل multipart/form-data#

يحلل أجسام الطلبات من نوع Content-Type: multipart/form-data -- وهو الترميز الذي تستخدمه المتصفحات للنماذج التي تتضمن حقول <input type="file">. نكهتان من واجهة API:

‏FormDataIter تدفقية تُنتج الحقول واحداً تلو الآخر -- مفيدة عندما يتعين على التطبيق معالجة عمليات رفع ضخمة جداً جزءاً جزءاً على جهاز محدود الذاكرة.
مزخرف with_form_data() يخزّن كل شيء مؤقتاً ويملأ request.form / request.files -- وهو واجهة API الملائمة لعمليات الرفع ذات الحجم العادي.

class FormDataIter#

class microdot.multipart.FormDataIter(request)#

مكرِّر غير متزامن على أجزاء جسم request متعدد الأجزاء. القيم المُنتَجة هي أزواج (name, value)؛ تكون value من نوع str للحقول العادية و FileUpload لحقول الملفات.

يُستخدم مباشرة عندما تكون الذاكرة أهم من سهولة الاستخدام:

from microdot.multipart import FormDataIter, FileUpload

@app.post('/upload')
async def upload(request):
    async for name, value in FormDataIter(request):
        if isinstance(value, FileUpload):
            await value.save('/sdcard/' + value.filename)
        else:
            print(name, '=', value)
    return 'ok'

ملاحظة

عند التكرار على حقول الملفات، يجب استهلاك الملف (عبر FileUpload.read() أو FileUpload.save()) قبل تكرار async for التالي -- إذ يصبح التدفق الأساسي غير صالح عند تقدم التكرار.

buffer_size: int#: سمة صنف. حجم الجزء (chunk) المستخدم أثناء القراءة من تدفق الطلب. الافتراضي 256 بايت. زده لإنتاجية أعلى على حساب RAM.

class FileUpload#

class microdot.multipart.FileUpload(filename: str, content_type: str | None, read)#

ملف واحد مرفوع. تُنتَج النسخ بواسطة FormDataIter وتُجمَع في request.files بواسطة with_form_data(). لا تبني التطبيقات عادةً FileUpload مباشرة.

filename: str#: اسم الملف الأصلي كما أرسله العميل (غير موثوق -- لا تمرره إلى open() دون تطهيره).

content_type: str | None#: نوع MIME من ترويسة Content-Type للجزء، أو None إذا لم يُقدَّم.

max_memory_size: int#: سمة صنف. العتبة (بالبايتات) التي يتحول فوقها copy() من التخزين المؤقت في الذاكرة إلى ملف مؤقت. الافتراضي 1024.

async read(n: int = -1)#: قراءة حتى n بايتاً من تدفق الرفع. ‏-1 يقرأ حتى النهاية.

async save(path_or_file)#: حفظ الرفع في path_or_file، الذي يمكن أن يكون مسار نظام ملفات أو كائن ملف مفتوح بالفعل.

async copy(max_memory_size: int | None = None)#: تخزين الرفع مؤقتاً (إما في RAM أو في ملف مؤقت، اعتماداً على max_memory_size) بحيث يمكن تحليل بقية جسم الطلب متعدد الأجزاء دون أن يصبح التدفق الأصلي غير صالح. يستدعي مزخرف with_form_data() هذا تلقائياً.

async close()#: تحرير أي ملف مؤقت أنشأه copy(). يُستدعى تلقائياً عند انتهاء الطلب إذا وصل الرفع إلى request.files عبر with_form_data().

مزخرفات على مستوى الوحدة#

microdot.multipart.with_form_data(f)#

مزخرف يحلل الجسم متعدد الأجزاء مسبقاً ويملأ request.form و request.files قبل تشغيل المعالج:

from microdot import Microdot
from microdot.multipart import with_form_data

app = Microdot()

@app.post('/upload')
@with_form_data
async def upload(request):
    print('fields:', dict(request.form))
    for name, file in request.files.items():
        await file.save('/sdcard/' + sanitize(file.filename))
    return 'ok'

تُخزَّن عمليات رفع الملفات مؤقتاً عبر FileUpload.copy()، لذا يمكن للمعالج التكرار على request.files و request.form بحرية. تُنظَّف الملفات المؤقتة تلقائياً عند انتهاء الطلب.

للعمليات الرفع الأكبر من بضعة ميغابايت، فضّل واجهة FormDataIter التدفقية؛ إذ يجمع with_form_data() الطلب بأكمله في الذاكرة أو على نظام الملفات قبل تشغيل المعالج.

microdot.multipart --- تحليل multipart/form-data#

class FormDataIter#

class FileUpload#

مزخرفات على مستوى الوحدة#

`microdot.multipart` --- تحليل multipart/form-data#