الصنف urllib.request.Request في بايثون
يعدّ هذا الصنف تجريدًا abstraction لطلب URL.
البنية العامة
urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)
المعاملات
url
يجب أن يكون سلسلة نصية تحتوي على عنوان URL صالح للاستخدام.
data
يجب أن يكون كائنًا يحدّد المعلومات الإضافية التي ستُرسل إلى المخدّم، أو يحمل القيمة None في حال انتفاء الحاجة إلى إرسال مثل هذه المعلومات. يستخدم هذا المعامل من قبل طلبات HTTP فقط في الوقت الحاضر. أنواع الكائنات المدعومة هي كائنات البايتات bytes، والكائنات الشبيهة بالملفات file-like objects، والكائنات القابلة للتكرار iterables.
في حال عدم تقديم الحقلين Content-Length و Transfer-Encoding فإنّ الصنف HTTPHandler سيعين قيمة لهاذين الحقلين في الترويسة بالاعتماد على طبيعة البيانات المعطاة في هذا المعامل. تستخدم الترويسة Content-Length لإرسال كائنات البايتات، أما الترويسة Transfer-Encoding: chunked فستُستخدم لإرسال الملفات والكائنات القابلة للتكرار (وذلك بحسب ما هو محدّد في المعيار RFC 7230 الفصل 3.3.1).
في حال كانت طريقة طلب HTTP هي POST، فإنّ قيمة data يجب أن تكون صِوانًا buffer بالصيغة المعيارية application/x-www-form-urlencoded. تأخذ الدالة urllib.parse.urlencode() كائن ربط أو تسلسلًا من صفّ ثنائي وتعيد سلسلة نصية بترميز ASCII بهذه الصيغة. يجب ترميز هذه السلسلة النصية إلى بايتات قبل استخدامها كقيمة للمعامل data.
headers
يجب أن يكون قاموسًا، وسيعامل كما لو أنّه قد استدعيت الدالة add_header() مع كل مفتاح وقيمة كوسائط لهذه الدالة. يستخدم هذا المعامل غالبًا لانتحال spoof قيمة الترويسة User-Agent، والتي تستخدم بواسطة المتصفح لتمييز نفسه. تجيز بعض مخدّمات HTTP الطلبات القادمة من المتصفّحات المعروفة فقط وذلك بخلاف السكربتات.
يعرّف المتصفح Mozilla Firefox نفسه بالسلسلة النصية "Mozilla/5.0(X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11" في حين يعرّف وكيل المستخدم user agent الافتراضي في وحدة urllib نفسه بالسلسلة النصية "Python-urllib/2.6" (في الإصدار 2.6 من بايثون).
يجب تضمين ترويسة Content-Type ملائمة عند استخدام المعامل data. وفي حال عدم تزويد الطلب بهذه الترويسة وكانت قيمة المعامل data هي None فإنّ الترويسة Content-Type: application/x-www/form/urlencoded ستضاف إلى الطلب افتراضيًا.
يُستخدم المعاملان الأخيران فقط لمعالجة كعكات HTTP من الطرف الثالث بطريقة صحيحة:
origin_req_host
يجب أن يكون مضيف الطلب الخاصّ بالعملية الأصلية origin transaction، وكما هو معرّف في المعيار RFC 2965. يأخذ هذا المعامل القيمة الافتراضية http.cookiejar.request_host(self). يتضمّن هذا المعامل اسم المضيف أو عنوان IP للطلب الأصلي المُرسل من قبل المستخدم. فعلى سبيل المثال، إن كان الطلب لصورة في مستند HTML، يجب أن يكون هذا المعامل مضيف الطلب الخاص بطلب الصفحة التي تحتوي هذه الصورة.
unverifiable
يجب أن يحدّد هذا المعامل ما إذا كان الطلب غير قابلٍ للتحقق منه unverifiable، وكما هو معرف في المعيار RFC 2965. يأخذ المعامل القيمة الافتراضية False. يُقصد بالطلب غير القابل للتحقق منه الطلب الذي يمتلك عنوان URL لا يمكن للمستخدم التثبت منه. فعلى سبيل المثال إن كان الطلب لصورة في ملف HTML ولم يكن المستخدم قادرًا على التثبت من عملية جلب الصورة التلقائية، يجب أن يأخذ هذا المعامل قيمة صحيحة.
method
يجب أن يكون سلسلة نصية تشير إلى طريقة HTTP التي ستُستخدم (مثل: 'HEAD'). تُخزّن قيمة هذا المعامل -إن كانت متوفّرة- في الخاصية method وتُستخدم بواسطة التابع get_method(). يحمل هذا المعامل القيمة الافتراضية 'GET' إن كانت قيمة المعامل data هي None، والقيمة الافتراضية 'POST' فيما عدا ذلك. يمكن للأصناف المتفرّعة أن تحدّد قيمة افتراضية أخرى وذلك بتعيين قيمة للخاصية method في الصنف المتفرّع ذاته.
ملاحظات:
- لن يعمل الطلب بصورة صحيحة إن لم يكن كائن البيانات قادرًا على توصيل محتواه لأكثر من مرّة (مثل ملفّ أو كائن iterable يُنتج المحتوى مرّة واحدة فقط) ويُعاد إرسال الطلب في حالة إعادة التوجيه أو عند الاستيثاق. تُرسل قيمة المعامل data إلى مخدّم HTTP بعد الترويسات مباشرة. لا يوجد دعم لترويسة "100-continue" في المكتبة.
- أضيف الوسيط Request.method إلى الصنف Request في الإصدار 3.3 من بايثون.
- أصبح بالإمكان تحديد القيمة الافتراضية للوسيط Request.method ضمن الصنف نفسه.
- في الإصدار 3.6 من بايثون لا يُطلق أي خطأ إن لم تُزوّد الترويسة Content-Length ولم تكن قيمة المعامل data هي None أو كائن بايتات. استخدم ترميز النقل المقطّع chunked transfer encoding عوضًا عن ذلك.