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