Python/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 عوضًا عن ذلك.

 كائنات Request

تصف التوابع التالية الواجهة العامة لكائنات Request ويمكن إعادة تعريف هذه التوابع في الأصناف المتفرّعة عن هذا الصنف. تقدّم هذه الكائنات كذلك مجموعة من الخصائص العامة التي يمكن استخدامها بواسطة العميل لتعقّب الطلب المفسّر.

الخاصية Request.full_url

عنوان URL الأصلي والممرّر إلى الدالة البانية.

يمكن تعيين قيمة للخاصية Request.full_url إضافة إلى قراءة القيمة وحذفها. تعيد عملية قراءة القيمة عنوان الطلب الأصلي مع القطعة fragment إن كانت موجودة.

الخاصية Request.type

مخطط URI.

الخاصية Request.host

صلاحية URI، عادة تكون مضيفًا، ولكن يمكن أن يتضمّن منفذًا مفصولًا عن المضيف بنقطتين رأسيتين.

الخاصية Request.origin_req_host

المضيف الأصلي للطلب، من دون المنفذ.

الخاصية Request.selector

مسار URI. إن استخدم كائن Request وسيطًا، فإنّ المنتقي سيكون عنوان URL الكامل الذي مُرِّر إلى الوسيط.

الخاصية Request.data

متن الطلب، أو القيمة None في حال عدم تعيينه.

ملاحظة: في الإصدار 3.4 من بايثون يؤدي تغيير قيمة Request.data إلى حذف الترويسة "Content-Length" إن كانت معيّنة أو محسوبة في السابق.

الخاصية Request.unverifiable

قيمة منطقية تحدّد ما إذا كان الطلب غير قابل للتوثيق unverifiable كما هو معرّف في المعيار RFC 2965.

الخاصية Request.method

تحدّد هذه الخاصية الطريقة المتّبعة لإرسال طلب HTTP. القيمة الافتراضية لهذه الخاصية هي None، والتي تعني أنّ التابع get_method()‎ سيؤدي عملها بصورة طبيعية. يمكن تعيين قيمة هذه الخاصية (وإعادة تعريف طريقة العمل الافتراضية للتابع get_method()‎) إمّا بتقديم قيمة افتراضية عن طريق تعيينها على مستوى الصنف في الأصناف المتفرّعة من الصنف Request، أو بتمرير القيمة إلى الدالة البانية للصنف Request عبر الوسيط method.

ملاحظات:

• هذه الخاصية جديدة في الإصدار 3.3 من بايثون.
• في الإصدار 3.4 من بايثون أصبح بالإمكان تعيين قيمة افتراضية في الصنف الفرعي، أما في الإصدارات السابقة فقد كانت الطريقة الوحيدة هي تعيين القيمة في الدالة البانية.

التابع Request.get_method()‎

يعيد التابع سلسلة نصية تحدّد الطريقة المتّبعة في إرسال طلب HTTP. 

التابع Request.add_header()‎

يضيف التابع ترويسة جديدة إلى الطلب.

التابع Request.add_unredirected_header()‎

يضيف التابع ترويسة لن تُضاف إلى الطلب المعاد توجيهه.

التابع Request.has_header()‎

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

التابع Request.remove_header()‎

يحذف التابع الترويسة المسمّاة من نسخة الكائن (من الترويسات العادية وغير المعاد توجيهها).

ملاحظة: هذا التابع جديد في الإصدار 3.4 من بايثون.

التابع Request.get_full_url()‎

يعيد التابع عنوان URL المعطى في الدالة البانية للصنف.

ملاحظة: في الإصدار 3.4 من بايثون، يعيد التابع قيمة الخاصية Request.full_url.

التابع Request.set_proxy()‎

يحضِّر التابع الطلب عن طريق الاتصال بمخدّم وسيط proxy server. 

التابع Request.get_header()‎

يعيد التابع قيمة الترويسة المعطاة.

التابع Request.header_items()‎

يعيد التابع الترويسات في كائن Request على هيئة قائمة من صفوف بهيئة (اسم الترويسة، قيمة الترويسة).

ملاحظة: كانت التوابع add_data ،has_data ،get_data ،get_type ،get_host ،get_selector ،get_origin_req_host ،is_unverifiable مهملة في الإصدار 3.3 من بايثون، وقد حذفت في الإصدار 3.4.

مصادر

• صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.