الصنف wsgiref.handlers.BaseHandler في بايثون
هذا الصنف هو صنف أساسي مجرّد يستخدم لتشغيل تطبيقات WSGI. تعالج كل نسخة من هذا الصنف طلب HTTP منفردًا، ولكن يمكن إنشاء صنف فرعي بمقدوره التعامل مع طلبات متعددة.
توابع الصنف BaseHandler
تمتلك نسخ BaseHandler تابعًا واحدًا فقط وهو معدّ للاستخدام الخارجي:
التابع run()
يشغّل التابع تطبيق WSGI المعطى.
تنفّذ جميع توابع BaseHandler الأخرى بواسطة هذا التابع أثناء عملية تشغيل التطبيق؛ لذا فإنّ الهدف الرئيسي من هذا التابع هو إتاحة القدرة على تخصيص هذه العملية.
يجب إعادة تعريف التوابع التالية في صنف فرعي:
التابع _write(data)
يخزّن التابع البيانات المعطاة لغرض نقلها إلى العميل؛ لا مشكلة في أن ينقل هذا التابع البيانات؛ إذ يفصل الصنف BaseHandler بين عملية الكتابة والمسح flush لزيادة الكفاءة وذلك عندما يميّز النظام الداخلي بين هاتين العمليتين.
التابع _flush()
ينقل التابع البيانات المخزّنة إلى العميل. لا مشكلة إن لم يؤدّ هذا التابع أي وظيفة (أي عندما يرسل التابع _write() البيانات).
get_stdin()
يعيد التابع كائن تدفق مدخلات والذي يكون ملائمًا لاستخدامه كتدفق مدخلات wsgi.input للطلب الذي تجري معالجته.
get_stderr()
يعيد التابع كائن تدفق مخرجات والذي يكون ملائمًا لاستخدامه كتدفق مخرجات wsgi.output للطلب الذي تجري معالجته.
add_cgi_vars()
يدرج التابع متغير CGI للطب الحالي في الخاصية environ.
الخصائص والتوابع التي تستخدم لتخصيص بيئة WSGI
فيما يلي بعض التوابع والخصائص التي قد ترغب في إعادة تعريفها، ويجدر التنبيه هنا إلى أنّه هذه ليست قائمة كاملة بالتوابع التي يمكن إعادة تعريفها. يجب عليك مراجعة سلاسل التوثيق النصية والشيفرة المصدرية للحصول على المزيد من المعلومات قبل محاولة إنشاء صنف مخصّص ومتفرّع من الصنف BaseHandler.
wsgi_multithread
تحمل هذه الخاصية القيمة التي تُستخدم لمتغير البيئة wsgi.multirthread. تأخذ هذه الخاصية القيمة True كقيمة افتراضية في الصنف BaseHandler، ولكن يمكن أن تأخذ قيمة افتراضية مختلفة في الأصناف الفرعية الأخرى، ويمكن تعيين قيمة الخاصية في الدالة البانية.
wsgi_multiprocess
تحمل هذه الخاصية القيمة التي تُستخدم لمتغير البيئة wsgi.multiprocess. تأخذ هذه الخاصية القيمة True كقيمة افتراضية في الصنف BaseHandler، ولكن يمكن أن تأخذ قيمة افتراضية مختلفة في الأصناف الفرعية الأخرى، ويمكن تعيين قيمة الخاصية في الدالة البانية.
wsgi_run_once
تحمل هذه الخاصية القيمة التي تُستخدم لمتغير البيئة wsgi.run_once. تأخذ هذه الخاصية القيمة False كقيمة افتراضية في الصنف BaseHandler، ولكنّها تأخذ القيمة True كقيمة افتراضية في الصنف CGIHandler.
os_environ
متغيرات البيئة الافتراضية التي ستضمّن في كل طلب في بيئة WSGI. تكون هذه الخاصية -افتراضيًا- نسخة من الخاصية os.environ لحظة استيراد الوحدة wsgiref.handlers، ولكن يمكن للأصناف الفرعية أن تنشئ نسخًا خاصّة بها على مستوى الصنف أو نسخة الصنف.
يجدر الانتباه إلى أنّ القاموس يجب أن يكون للقراءة فقط؛ ذلك لأنّ القيمة الافتراضية تكون مشتركة بين أصناف ونسخ أصناف متعددة.
server_software
إن جرى تعيين قيمة للخاصية origin_server فإنّ قيمة هذه الخاصية ستستخدم لتعيين قيمة لمتغير بيئة WSGI الافتراضي SERVER_SOFWARE، ولتحديد مخدّم افتراضي: header في استجابات HTTP. تتجاهل معالجات الطلبات التي لا تكون من نوع HTTP (مثل BaseCGIHandler و CGIHandler) هذه الخاصية.
ملاحظة: استبدلت الكلمة "Python" بنوع اللغة المستخدم مثل "CPython" و "Jython" ... الخ، في الإصدار 3.3 من بايثون.
التابعget_scheme()
يعيد هذا التابع مخطط URL المستخدم للطلب الحالي. تُستخدم الدالة guess_scheme() من الوحدة wsgiref.util افتراضيًا لتخمين ما إذا كان المخطط "http" أو "https" وذلك بالاعتماد على متغيرات environ في الطلب الحالي.
التابع setup_environ()
يعين التابع بيئة WSGI مهيئة بالكامل إلى الخاصية environ. تُستخدم جميع التوابع والخصائص أعلاه افتراضيًا، إضافة إلى التوابع get_stdin() و get_stderr() و add_cgi_vars() وخاصية wsgi_file_wrapper. كذلك يُدرج المفتاح SERVER_SOFTWARE إن لم يكن موجودًا وما دامت الخاصية origin_server تحمل قيمة صحيحة وما دامت الخاصية server_software معيّنة.
توابع وخصائص تستخدم لتخصيص عملية معالجة الاستثناءات
التابع log_exception(exc_info)
يسجّل التابع الصفّ exc_info في سجلّ المخدّم، ويأخذ هذا الصف الصيغة (type, value, traceback). يُكتب الخطأ traceback افتراضيًا في تدفق أخطاء wsgi في الخاصية wsgi.errors ثم يجري التخلّص منه. يمكن للأصناف الفرعية أن تعيد تعريف هذا التابع لتغيير الصيغة أو لإعادة توجيه المخرجات، أو إرسال الأخطاء برسالة إلكترونية إلى مدير النظام، أو اتخاذ الإجراء المناسب.
traceback_limit
تمثّل هذه الخاصية أقصى عدد ممكن من الإطارات frames المضمّنة في مخرجات الأخطاء tracebacks بواسطة التابع الافتراضي log_excetion(). إن كانت قيمة هذه الخاصية هي None فستُضمَّن جميع الإطارات.
التابع error_output(environ, start_response)
هذا التابع هو تطبيق WSGI وظيفته إنتاج صفحة خطأ للمستخدمين، ويُنفّذ هذا التابع فقط عند حدوث خطأ قبل إرسال الترويسات إلى طرف العميل.
يمكن لهذا التابع الوصول إلى معلومات الخطأ الحالي باستخدام الدالة sys.exc_info()، ويجب أن يمرّر التابع المعلومات إلى الخاصية start_response عند استدعائه (بحسب ما هو موصوف في قسم "Error Handling" في PEP 3333).
يستخدم التابع افتراضيًا الخصائص error_status و error_headers و error_body لإنتاج صفحة مخرجات، ويمكن للأصناف الفرعية أن تعيد تعريف هذا السلوك وذلك لإنتاج مخرجات أخطاء بخصائص ومميّزات مختلفة.
ولكن ومن الناحية الأمنية لا يُنصح بعرض تشخيصات الأخطاء diagnostics على المستخدمين القدماء؛ بل يجب أن يكون هناك بعض الإجراءات الخاصة التي يجب اتخاذها ليتمكن المستخدم من عرض مخرجات تشخيص الأخطاء، ولهذا لا يتضمّن التابع هذا السلوك افتراضيًا.
error_status
حالة HTTP المستخدمة لاستجابات الأخطاء. يجب أن تكون الخاصية سلسلة حالة نصية كما هو معرّف في PEP 3333، والقيمة الافتراضية لهذه الخاصية هي الكود والرسالة 500.
error_headers
ترويسة HTTP المستخدم في استجابات الأخطاء. يجب أن تكون قيمة هذه الخاصية قائمة تتضمّن ترويسات استجابات WSGI والتي تكون صفًّا يأخذ الصيغة (name, value)، وكما هو موصوف في PEP 3333. تعيّن القائمة الافتراضية المحتوى إلى text/plain.
error_body
تمثّل هذه الخاصية متن استجابة الخطأ. يجب أن تكون قيمة الخاصية من نوع bytestring تحتوي على متن استجابة HTTP. القيمة الافتراضية لهذه الخاصية هي "A server error occurred. Please contact the administrator".
الخصائص والتوابع الخاصّة بـالقسم "Optional Platform-Specific File Handling" في المعيار PEP 3333
wsgi_file_wrapper
تأخذ هذه الخاصية القيمة None أو دالة تولّد الصنف wsgi.file_wrapper. القيمة الافتراضية لهذه الخاصية هي الصنف wsgiref.util.FileWrapper.
التابع sendfile()
أعد تعريف هذا التابع لاستخدام عملية نقل ملفّات خاصّة بالمنصّة المستخدمة platform-specific file transmission. يُستدعى هذا التابع عندما تكون القيمة المعادة من التطبيق نسخة من الصنف المعيّن في الخاصية wsgi_file_wrapper فقط. يجب أن يعيد التابع قيمة صحيحة إن تمكن من نقل الملف بنجاح، وبهذا لن تنّفذ عملية النقل الافتراضية. يعيد التابع افتراضيًا القيمة خاطئة.
انظر أيضًا
- الصنف
CGIHandler: يمكن الاستفادة من هذا الصنف عند الحاجة إلى تشغيل تطبيق WSGI كشيفرة CGI. - الصنف
IISCGIHandler: هذا الصنف هو بديل خاص للصنفCGIHandler، ويستخدم لنشر التطبيقات على مخدّم الويب IIS الخاص بمايكروسوفت. - الصنف
BaseCGIHandler: هذا الصنف مشابه للصنفCGIHandler، ولكن عوضًا عن استخدام الوحدتينsysوos، فإنّ بيئة CGI و تدفقات المدخلات والمخرجات تحدّد من قبل المستخدم. - الصنف
SimpleHandler: هذا الصنف مشابه للصنفBaseCGIHandler، ولكنّه مصمّم للاستخدام مع المخدمّات من نوع HTTP.