عرض مصدر Python/FieldStorage

يمكن الوصول إلى البيانات المرسلة إلى المخدّم عن طريق الصنف <code>FieldStorage</code>، وإن كان النموذج يتضمّن حروفًا بترميز غير ترميز ASCII فيمكن استخدام المعامل المفتاحي <code>encoding</code> لتعيين قيمة الترميز المستخدم في الملف الحاوي على النموذج، ويمكن الوصول إلى الترميز المستخدم عادة في الوسم <code>[[HTML/meta|META]]</code> في قسم <code>[[HTML/head|HEAD]]</code> من ملف [[HTML]] أو عن طريق الترويسة <code>Content-Type</code>).

يقرأ الصنف محتويات النموذج من المدخلات القياسية أو من البيئة (بالاعتماد على قيمة عدد من متغيرات البيئة والمعيّنة حسب معايير CGI). قد يستهلك الصنف المدخلات القياسية؛ لذا يجب تهيئته مرة واحدة فقط.

تشبه نسخ الصنف <code>FieldStorage</code> [[Python|قواميس]] بايثون إلى حدّ كبير، إذ يمكن فهرسة الكائن كما هو الحال مع القواميس، ويمكن اختبار وجود عنصر معيّن باستخدام المعامل <code>in</code>، ويدعم الكائن كذلك استخدام التابع <code>[[Python/dict/keys|keys()‎]]</code> الخاصّ بالقواميس إضافة إلى الدالة الداخلية <code>[[Python/len|len()]]</code>‎. لا تظهر حقول النموذج التي تتضمّن سلاسل نصية فارغة في القاموس وسيجري تجاهلها، وللإبقاء على مثل هذه القيم، يجب إعطاء المعامل المفتاحي <code>keep_blank_values</code> القيمة <code>True</code> عند إنشاء نسخة من الصنف <code>FieldStorage</code>.

فعلى سبيل المثال تتحقّق الشيفرة التالية (والتي تفترض أنّ الترويسة <code>Content-Type</code> والسطر الفارغ قد طُبعا مسبقًا) من أن الحقلين <code>name</code> و <code>addr</code> هما حقلان لا يحتويان على سلاسل نصية فارغة:<syntaxhighlight lang="python3">
form = cgi.FieldStorage()
if "name" not in form or "addr" not in form:
    print("<H1>Error</H1>")
    print("Please fill in the name and addr fields.")
    return
print("<p>name:", form["name"].value)
print("<p>addr:", form["addr"].value)
...further form processing here...
</syntaxhighlight>الحقول في هذه الشيفرة والتي تم الوصول إليها باستخدام العبارة <code>form[key]</code>‎ هي بحدّ ذاتها نسخ من الكائن <code>FieldStorage</code> (أو <code>MiniFieldStorage</code> وذلك حسب ترميز النموذج). يمكن الوصول إلى قيمة الحقل النصية باستخدام الخاصية <code>value</code> في نسخ الكائن، ويعيد التابع <code>[[Python/FieldStorage/getvalue|getvalue()]]</code>‎ السلسلة النصية مباشرة، ويستقبل كذلك معاملًا آخر اختياريًا يُستخدم لتعيين القيمة التي يعيدها التابع إن لم يكن المفتاح المطلوب موجودًا.

إن تضمّنت البيانات المرسلة من النموذج على حقول متعددة تحمل الاسم ذاته، فإنّ الكائن المستحصل من العبارة <code>form[key]‎</code> لن يكون كائن <code>FieldStorage</code> أو <code>MiniFieldStorage</code> ولكن قائمة من هذه الكائنات. وكذلك الأمر بالنسبة للتابع <code>form.getvalue(key)</code>‎ إذ سيعيد قائمة من [[Python/str|السلاسل النصية]] في مثل هذه الحالة. إن كنت تتوقع حدوث هذه الحالة (أي عندما يتضمّن [[HTML/form|نموذج HTML]] الخاصّ بك على عدد من الحقول التي تحمل الاسم عينه) فاستخدم التابع <code>getlist()‎</code> والذي يعيد قائمة من القيم دائمًا (وبهذه الصورة لن تضطر إلى التعامل مع الحالات الخاصة التي تتضمّن عنصرًا واحدًا فقط).

تربط الشيفرة التالية أي عدد من الحقول التي تحمل الاسم <code>username</code> ويفصل بين قيمها بفاصلة:<syntaxhighlight lang="python3">

value = form.getlist("username")
usernames = ",".join(value)
</syntaxhighlight>إن كان الحقل يمثّل ملفًّا مرفوعًا، فإنّ الوصول إلى قيمة الحقل باستخدام الخاصية <code>value</code> أو باستخدام التابع <code>getvalue()</code>‎ سيؤدي إلى قراءة الملف بأكمله في الذاكرة على هيئة بايتات، وقد يكون هذا أمرًا غير مرغوب به؛ لذا يمكن التحقّق من رفع الملف إما باختبار الخاصية <code>filename</code> أو الخاصية <code>file</code>، ثم يمكن بعد ذلك قراءة البيانات من الخاصية <code>file</code> قبل إغلاقه تلقائيًا كجزء من عملية التخلص من نسخة الصنف <code>FieldStorage</code> (القيمة المعادة من التابعين <code>read()‎</code> و <code>readline()</code>‎ هي البايتات):<syntaxhighlight lang="python3">

fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while True:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1
</syntaxhighlight>يمكن استخدام كائنات <code>FieldStorage</code> مع عبارات <code>with</code>، والتي ستغلق هذه الكائنات عند انتهاء عمل العبارة.

تعين القيمة ‎-1 للخاصية done في الكائن عند حدوث خطأ أثناء جلب محتويات الملف المرفوع (عندما يقاطع المستخدم عملية إرسال النموذج بضغطه لزر الرجوع أو زر الإلغاء مثلًا).

تتيح مسوّدة معيار رفع عدد من الملفات باستخدام حقل واحد (باستخدام الترميز <code>multipart/*</code>‎)، فإنّ العناصر المستحصلة تكون على هيئة كائن <code>FieldStorage</code> شبيه بالقاموس. ويمكن التحقّق من حدوث هذه الحالة بواسطة الخاصية <code>type</code>، والتي يجب أن تكون <code>multipart/form-data</code> (أو أيّ نوع MIME آخر يطابق العبارة <code>multipart/*</code>‎)، وفي هذه الحالة يمكن المرور على عناصر الكائن تعاوديًا كما هو الحال مع كائن النموذج الأساسي.

إذا أرسل النموذج إلى المخدّم بالأسلوب القديم (كسلسلة استعلام نصية أو كبيانات ذات جزء واحد من نوع <code>application/x-www-form-urlencoded</code>) فإنّ العناصر ستكون نسخًا من الصنف <code>MiniFieldStorage</code>. وفي هذه الحالة تحمل الخصائص <code>list</code> و <code>file</code> و <code>filename</code> القيمة <code>None</code> دائمًا.

يتضمّن النموذج المرسل بطريقة POST والذي يضمّ سلسلة استعلام نصية أيضًا عناصر <code>FieldStorage</code> و <code>MiniFieldStorage</code>.

'''ملاحظات:'''
*تُغلَق الخاصية <code>file</code> تلقائيًا عند التخلص من كائن <code>FieldStorage</code> التابعة له في الإصدار 3.4 من بايثون.
*أصبح الصنف <code>FieldStorage</code> داعمًا لبروتوكول إدارة السياق context management في الإصدار 3.5 من بايثون.
[[تصنيف:Python]]
[[تصنيف:Python Modules]]