الفرق بين المراجعتين لصفحة: «Python/urllib/request»

من موسوعة حسوب
< Python‏ | urllib
→ التعديل السابق
مرئينص الويكي
لا ملخص تعديل
لا ملخص تعديل
 
(23 مراجعات متوسطة بواسطة نفس المستخدم غير معروضة)
سطر 1: سطر 1:
تقدّم وحدة urllib.request عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL‏ (HTTP في الغالب) لاستخدامها في عمليات مختلفة مثل الاستيثاق البسيط وإعادة التوجيه والتعامل مع الكعكات cookies وغيرها.
<noinclude>{{DISPLAYTITLE:الوحدة <code>urllib.request‎‎</code> في بايثون}}</noinclude>


ملاحظة: يُنصح باستخدام الحزمة Requests في العمليات المتقدّمة لأنّها توفّر واجهة برمجية ذات مستوى أعلى.
تقدّم وحدة <code>urllib.request</code> عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL‏ (HTTP في الغالب) لاستخدامها في عمليات مختلفة مثل الاستيثاق البسيط وإعادة التوجيه والتعامل مع الكعكات cookies وغيرها.
 
ملاحظة: يُنصح باستخدام الحزمة [http://docs.python-requests.org/ Requests] في العمليات المتقدّمة لأنّها توفّر واجهة برمجية ذات مستوى أعلى.


== دوالّ الوحدة <code>urllib.request</code> ==
== دوالّ الوحدة <code>urllib.request</code> ==
سطر 7: سطر 9:
تقدّم وحدة <code>urllib.request</code> الدوال التالية:
تقدّم وحدة <code>urllib.request</code> الدوال التالية:


=== <code>urllib.request.urlopen()‎</code> ===
=== الدالة <code>[[Python/urllib/request/urlopen|urllib.request.urlopen()]]‎</code> ===
=== <code>urllib.request.install_opener()‎</code> ===
تفتح الدالة عنوان URL المعطى.
=== <code>urllib.request.build_opener()‎</code> ===
 
=== <code>urllib.request.pathname2url()‎</code> ===
=== <code>[[Python/urllib/request/install opener|urllib.request.install_opener()‎]]</code> ===
=== <code>urllib.request.url2pathname()‎</code> ===
تثبّت الدالة نسخة من الصنف [[Python/urllib/request/OpenerDirector|<code></code>]]<code>[[Python/OpenerDirector|OpenerDirector]]</code> كفاتح opener افتراضي عام.
=== <code>urllib.request.getproxies()‎</code> ===
 
=== <code>[[Python/urllib/request/build opener|urllib.request.build_opener()‎]]</code> ===
تعيد الدالة نسخة من الصنف <code>[[Python/urllib/request/OpenerDirector|OpenerDirector]]</code> والتي تربط بين المعالجات handlers حسب الترتيب المعطى. 
 
=== <code>[[Python/urllib/request/pathname2url|urllib.request.pathname2url()‎]]</code> ===
تحوّل الدالة المسار المعطى من الصيغة المستخدمة في المسارات المحلية إلى الصيغة المستخدمة في عناوين URL.
 
=== <code>[[Python/urllib/request/url2pathname|urllib.request.url2pathname()‎]]</code> ===
تحوّل الدالة مكونات المسار المعطى من عنوان URL مرمّز بعلامة النسبة المئوية إلى الصيغة المحلّية للمسارات. 
 
=== <code>[[Python/urllib/request/getproxies|urllib.request.getproxies()‎]]</code> ===
تعيد هذه الدالة المساعدة قاموسًا يربط بين المخطّط scheme وعناوين URL في مخدّم الوسيط. 


== أصناف الوحدة <code>urllib.request</code> ==
== أصناف الوحدة <code>urllib.request</code> ==
سطر 18: سطر 31:
تقدّم الوحدة الأصناف التالية:
تقدّم الوحدة الأصناف التالية:


=== الصنف <code>urllib.request.Request</code> ===
=== الصنف <code>[[Python/urllib/request/Request|urllib.request.Request]]</code> ===
يعدّ هذا الصنف تجريدًا abstraction لطلب URL.


=== الصنف <code>urllib.request.OpenerDirector</code> ===
=== الصنف <code>urllib.request.OpenerDirector</code> ===
يفتح هذا الصنف عناوين URL بواسطة الصنف BaseHandlers المرتبط به. يتحكّم هذا الصنف بعملية ربط الأصناف المعالجة بعضها ببعض، والتعافي من الأخطاء.
يفتح هذا الصنف عناوين URL بواسطة الصنف <code>[[Python/urllib/request/BaseHandler|BaseHandlers]]</code> المرتبط به. يتحكّم هذا الصنف بعملية ربط الأصناف المعالجة بعضها ببعض، والتعافي من الأخطاء.


=== الصنف <code>urllib.request.BaseHandler</code> ===
=== الصنف <code>urllib.request.BaseHandler</code> ===
سطر 35: سطر 49:
يعالج هذا الصنف كعكات HTTP.
يعالج هذا الصنف كعكات HTTP.


=== الصنف <code>urllib.request.ProxyHandler</code> ===
=== الصنف <code>[[Python/urllib/request/ProxyHandler|urllib.request.ProxyHandler]]</code> ===
يتسبب هذا الصنف في تمرير الطلبات عبر وسيط معيّن.


=== الصنف <code>urllib.request.HTTPPasswordMgr</code> ===
=== الصنف <code>urllib.request.HTTPPasswordMgr</code> ===
يحتفظ الصنف بقاعدة بيانات من روابط ‎(realm, uri) -> (user, password).  
يحتفظ الصنف بقاعدة بيانات من روابط ‎<code>(realm, uri) -> (user, password)‎</code>.  


=== الصنف <code>urllib.request.HTTPPasswordMgrWithDefaultRealm</code> ===
=== الصنف <code>urllib.request.HTTPPasswordMgrWithDefaultRealm</code> ===
يحتفظ الصنف بقاعدة بيانات من روابط ‎(realm, uri) -> (user, password).  
يحتفظ الصنف بقاعدة بيانات من روابط ‎<code>(realm, uri) -> (user, password)‎</code>.  


A realm of None is considered a catch-all realm, which is searched if no other realm fits.
يعدّ الحقل None حقلًا عامًّا ويجري البحث عنه في حال عدم مطابقة أي حقل آخر.  


=== الصنف <code>urllib.request.HTTPPasswordMgrWithPriorAuth</code> ===
=== الصنف <code>urllib.request.HTTPPasswordMgrWithPriorAuth</code> ===
شكل مختلف من الصنف HTTPPasswordMgrWithDefaultRealm ويمتلك قاعدة بيانات فيها روابط ‎uri -> is_authenticated. يمكن استخدام هذا الصنف بواسطة الصنف المعالج BasicAuth لتحديد متى يمكن إرسال معلومات الاستيثاق مباشرة دون الحاجة إلى انتظار الاستجابة 401 أوّلًا.
شكل مختلف من الصنف <code>HTTPPasswordMgrWithDefaultRealm</code> ويمتلك قاعدة بيانات فيها روابط ‎<code>uri -> is_authenticated</code>. يمكن استخدام هذا الصنف بواسطة الصنف المعالج <code>BasicAuth</code> لتحديد متى يمكن إرسال معلومات الاستيثاق مباشرة دون الحاجة إلى انتظار الاستجابة 401 أوّلًا.
ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.


=== الصنف <code>urllib.request.AbstractBasicAuthHandler</code> ===
'''ملاحظة:''' هذا الصنف جديد في الإصدار 3.5 من بايثون.


=== الصنف <code>urllib.request.HTTPBasicAuthHandler</code> ===
=== الصنف <code>[[Python/urllib/request/AbstractBasicAuthHandler|urllib.request.AbstractBasicAuthHandler]]</code> ===
صنف مخلوط mixin class يساعد في عمليات استيثاق HTTP لكلٍّ من المضيف البعيد remote host والوسيط proxy.


=== الصنف <code>urllib.request.ProxyBasicAuthHandler</code> ===
=== الصنف <code>[[Python/urllib/request/HTTPBasicAuthHandler|urllib.request.HTTPBasicAuthHandler]]</code> ===
يعالج هذا الصنف عملية الاستيثاق مع المضيف البعيد.


=== الصنف <code>urllib.request.AbstractDigestAuthHandler</code> ===
=== الصنف <code>[[Python/urllib/request/ProxyBasicAuthHandler|urllib.request.ProxyBasicAuthHandler]]</code> ===
يعالج هذا الصنف عملية الاستيثاق مع الوسيط.


=== الصنف <code>urllib.request.HTTPDigestAuthHandler</code> ===
=== الصنف <code>[[Python/urllib/request/AbstractDigestAuthHandler|urllib.request.AbstractDigestAuthHandler]]</code> ===
صنف مخلوط mixin class يساعد في عمليات استيثاق HTTP لكلٍّ من المضيف البعيد remote host والوسيط proxy.


=== الصنف <code>urllib.request.ProxyDigestAuthHandler</code> ===
=== الصنف <code>[[Python/urllib/request/HTTPDigestAuthHandler|urllib.request.HTTPDigestAuthHandler]]</code> ===
يعالج هذا الصنف عملية الاستيثاق مع المضيف البعيد.
 
=== الصنف <code>[[Python/urllib/request/ProxyDigestAuthHandler|urllib.request.ProxyDigestAuthHandler]]</code> ===
يعالج هذا الصنف عملية الاستيثاق مع الوسيط.


=== الصنف <code>urllib.request.HTTPHandler</code> ===
=== الصنف <code>urllib.request.HTTPHandler</code> ===
يعالج هذا الصنف عملية فتح عناوين HTTP.
يعالج هذا الصنف عملية فتح عناوين HTTP.


=== الصنف <code>urllib.request.HTTPSHandler</code> ===
=== الصنف <code>[[Python/urllib/request/HTTPSHandler|urllib.request.HTTPSHandler]]</code> ===
يعالج هذا الصنف عملية فتح عناوين HTTPS.


=== الصنف <code>urllib.request.FileHandler</code> ===
=== الصنف <code>urllib.request.FileHandler</code> ===
سطر 74: سطر 97:
'''ملاحظة:''' هذا الصنف جديد في الإصدار 3.4 من بايثون.
'''ملاحظة:''' هذا الصنف جديد في الإصدار 3.4 من بايثون.


=== الصنف urllib.request.FTPHandler ===
=== الصنف <code>urllib.request.FTPHandler</code> ===
يفتح عناوين FTP.
يفتح عناوين FTP.


سطر 86: سطر 109:
صنف لمعالجة استجابات HTTP الخاصة بالأخطاء.
صنف لمعالجة استجابات HTTP الخاصة بالأخطاء.


== كائنات Request ==
== كائنات <code>OpenerDirector</code> ==
 
تفتح كائنات <code>OpenerDirector</code> عناوين URL عبر ثلاث مراحل، ويُحدّد ترتيب استدعاء هذا التوابع في كلّ مرحلة عن طريق ترتيب نسخ أصناف المعالجة.
# كلّ معالج يمتلك تابعًا يحمل اسمًا مثل <code>protocol_request()</code>‎ سيستدعي ذلك التابع للمعالجة القبلية pre-process للطلب.
# المعالجات التي تمتلك تابعًا يحمل اسمًا مثل <code>protocol_open()</code>‎ ستستدعى لمعالجة الطلب. تنتهي هذه المرحلة عندما يعيد معالجٌ ما قيمة غير القيمة <code>None</code> (أي يعيد استجابة) أو عندما يطلق استثناءً (عادة ما يكون <code>URLError</code>)، ويُسمح للاستثناءات بالتكرار.  تجري تجربة الخوارزمية السابقة مع التوابع التي تحمل اسمًا مثل <code>default_open()‎</code>، وإن أعادت جميع هذه التوابع القيمة <code>None</code>، فإنّ الخوارزمية ستُعاد مع التوابع التي تحمل اسمًا مثل <code>protocol_open()</code>‎، وإن أعادت جميع هذه التوابع القيمة <code>None</code>، فإنّ الخوارزمية ستُعاد مع التوابع التي تحمل اسمًا مثل <code>unknown_open()</code>‎.  يجدر الانتباه إلى أنّ استخدام هذه التوابع قد يتضمّن استدعاءات للتابعين <code>[[Python/urllib/request/OpenerDirector/open|open()]]</code>‎ و [[Python/urllib/request/OpenerDirector/error|<code>error()</code>‎]] في نسخة الصنف <code>OpenerDirector</code> الأب.
# كلّ معالج يمتلك تابعًا يحمل اسمًا مثل <code>protocol_response()‎</code> سيستدعي ذلك التابع للمعالجة البعدية post-process للاستجابة.
تمتلك كائنات <code>OpenerDirector</code> التوابع التالية:
 
=== التابع <code>[[Python/urllib/request/OpenerDirector/add handler|OpenerDirector.add_handler()‎]]</code> ===
يضيف التابع صنف معالجة إلى كائن <code>OpenerDirector</code>.
 
=== التابع <code>[[Python/urllib/request/OpenerDirector/open|OpenerDirector.open()‎]]</code> ===
يفتح التابع العنوان المعطى.
 
=== التابع <code>[[Python/urllib/request/OpenerDirector/error|OpenerDirector.error()‎]]</code> ===
يعالج هذا التابع خطأً معيّنًا في البروتوكول المعطى. 
 
== كائنات <code>BaseHandler</code> ==
 
تقدّم كائنات <code>BaseHandler</code> تابعين يمكن الاستفادة منهما مباشرة، وعددًا من التوابع التي أعدّت للاستخدام بواسطة الأصناف المشتّقة من هذه الكائنات.
 
يُستخدم التابعان التاليان مباشرة:


تصف التوابع التالية الواجهة العامة لكائنات Request ويمكن إعادة تعريف هذه التوابع في الأصناف المتفرّعة عن هذا الصنف. تقدّم هذه الكائنات كذلك مجموعة من الخصائص العامة التي يمكن استخدامها بواسطة العميل لتعقّب الطلب المفسّر.
=== التابع <code>[[Python/urllib/request/BaseHandler/add parent|BaseHandler.add_parent()‎]]</code> ===
يضيف التابع الموجّه المعطى كموجّه أب.


=== <code>Request.full_url</code> ===
=== التابع <code>[[Python/urllib/request/BaseHandler/close|BaseHandler.close()‎]]</code> ===
عنوان URL الأصلي والممرّر إلى الدالة البانية.
يحذف التابع أي موجّهات أبوية.


يمكن تعيين قيمة للخاصية Request.full_url إضافة إلى قراءة القيمة وحذفها. تعيد عملية قراءة القيمة عنوان الطلب الأصلي مع القطعة fragment إن كانت موجودة.
يجب استخدام التوابع والخصائص التالية من قبل الأصناف المشتقّة من الصنف <code>BaseHandler</code> فقط.


=== <code>Request.type</code> ===
'''ملاحظة'''
مخطط URI.


=== <code>Request.host</code> ===
جرى الاتفاق على تسمية الأصناف الفرعية التي تعرّف التابع <code>protocol_request()‎</code> أو <code>protocol_response()‎</code> بالاسم ‎<code>*Processor</code>، وتُسمّى الأصناف الفرعية الأخرى بالاسم ‎<code>*Handler</code>.
صلاحية URI، عادة تكون مضيفًا، ولكن يمكن أن يتضمّن منفذًا مفصولًا عن المضيف بنقطتين رأسيتين.


=== <code>Request.origin_req_host</code> ===
=== الخاصية <code>BaseHandler.parent</code> ===
المضيف الأصلي للطلب، من دون المنفذ.
كائن <code>OpenerDirector</code> صالح للاستخدام، والذي يمكن استخدامه لفتح العناوين باستخدام بروتكول مختلف أو لمعالجة الأخطاء.


=== <code>Request.selector</code> ===
=== التابع <code>[[Python/urllib/request/BaseHandler/default open|BaseHandler.default_open()‎]]</code> ===
مسار URI. إن استخدم كائن Request وسيطًا، فإنّ المنتقي سيكون عنوان URL الكامل الذي مُرِّر إلى الوسيط.
هذا التابع غير معرّف في الصنف <code>BaseHandler</code>، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب التقاط جميع عناوين URL.


=== <code>Request.data</code> ===
=== التابع <code>[[Python/urllib/request/BaseHandler/protocol open|BaseHandler.protocol_open()‎]]</code> ===
متن الطلب، أو القيمة None في حال عدم تعيينه.
هذا التابع غير معرّف في الصنف <code>BaseHandler</code>، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب معالجة عناوين URL مع البروتوكول المعطى.


'''ملاحظة:''' في الإصدار 3.4 من بايثون يؤدي تغيير قيمة <code>Request.data</code> إلى حذف الترويسة "Content-Length" إن كانت معيّنة أو محسوبة في السابق.
=== التابع <code>[[Python/urllib/request/BaseHandler/unknown open|BaseHandler.unknown_open()‎]]</code> ===
هذا التابع غير معرّف في الصنف <code>BaseHandler</code>، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب التقاط جميع عناوين URL دون تحديد أيّ معالج مسجّل لفتح هذه العناوين.


=== <code>Request.unverifiable</code> ===
=== التابع <code>[[Python/urllib/request/BaseHandler/http error default|BaseHandler.http_error_default()‎]]</code> ===
قيمة منطقية تحدّد ما إذا كان الطلب غير قابل للتوثيق unverifiable كما هو معرّف في المعيار RFC 2965.
يُستدعى هذا التابع تلقائيًا بواسطة كائن <code>OpenerDirector</code> الذي يتلقّى الخطأ، ويجب عدم استدعائه في الظروف الأخرى.


=== <code>Request.method</code> ===
=== التابع <code>[[Python/urllib/request/BaseHandler/http error nnn|BaseHandler.http_error_nnn()‎]]</code> ===
تحدّد هذه الخاصية الطريقة المتّبعة لإرسال طلب HTTP. القيمة الافتراضية لهذه الخاصية هي <code>None</code>، والتي تعني أنّ التابع <code>get_method()</code>‎ سيؤدي عملها بصورة طبيعية. يمكن تعيين قيمة هذه الخاصية (وإعادة تعريف طريقة العمل الافتراضية للتابع <code>get_method()‎</code>) إمّا بتقديم قيمة افتراضية عن طريق تعيينها على مستوى الصنف في الأصناف المتفرّعة من الصنف <code>Request</code>، أو بتمرير القيمة إلى الدالة البانية للصنف <code>Request</code> عبر الوسيط <code>method</code>.
هذا التابع غير معرّف في الصنف <code>BaseHandler</code> أيضًا، ولكن سيُستدعى إن كان موجودًا على نسخة من الصنف المتفرّع عن الصنف <code>BaseHandler</code> عند حدوث خطأ HTTP يحمل الشيفرة <code>nnn</code>.


'''ملاحظات:'''
=== التابع <code>[[Python/urllib/request/BaseHandler/protocol request|BaseHandler.protocol_request()‎]]</code> ===
* هذه الخاصية جديدة في الإصدار 3.3 من بايثون.
هذا التابع غير معرّف في الصنف <code>BaseHandler</code>، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب إجراء معالجة قبلية للطلبات الخاصّة بالبروتكول المعطى.
* في الإصدار 3.4 من بايثون أصبح بالإمكان تعيين قيمة افتراضية في الصنف الفرعي، أما في الإصدارات السابقة فقد كانت الطريقة الوحيدة هي تعيين القيمة في الدالة البانية.


== كائنات OpenerDirector ==
=== التابع <code>[[Python/urllib/request/BaseHandler/protocol response|BaseHandler.protocol_response()‎]]</code> ===
هذا التابع غير معرّف في الصنف <code>BaseHandler</code>، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب إجراء معالجة بعدية للاستجابات الخاصّة بالبروتكول المعطى.


تمتلك كائنات <code>OpenerDirector</code> التوابع التالية:
== كائنات <code>HTTPRedirectHandler</code> ==
'''ملاحظة:'''
 
تحتاج بعض عمليات إعادة التوجيه في HTTP إلى بعض الأحداث من شيفرة الوحدة التابعة للعميل، وتُطلق الوحدة الاستثناء <code>HTTPError</code> إن كانت هذه هيه الحالة. راجع المعيار <nowiki>RFC 2616</nowiki> للمزيد من التفاصيل حول المعنى الدقيق لشيفرات إعادة التوجيه المختلفة.
 
يُطلق الاستثناء <code>HTTPError</code> كإجراء احترازي إن حصل المعالج <code>HTTPRedirectHandler</code> على عنوان URL لا ينتمي إلى بروتكولات HTTP أو HTTPS أو FTP.
 
تقدم كائنات <code>HTTPRedirecthandler</code> التوابع التالية:
 
=== التابع <code>[[Python/urllib/request/HTTPRedirectHandler/redirect request|HTTPRedirectHandler.redirect_request()‎]]</code> ===
يعيد التابع كائن <code>Request</code> أو القيمة <code>None</code> استجابةً لعملية إعادة توجيه.
 
=== التابع <code>[[Python/urllib/request/HTTPRedirectHandler/http error 301|HTTPRedirectHandler.http_error_301()‎]]</code> ===
يعيد التابع التوجيه إلى عنوان <code>Location:</code>‎ أو <code>URI:</code>‎.


=== التابع <code>HTTPRedirectHandler.http_error_302()‎</code> ===
هذا التابع مشابه للتابع <code>[[Python/urllib/request/HTTPRedirectHandler/http error 301|http_error_301()]]‎</code> ولكن يُستدعى للاستجابة (found).


== كائنات BaseHandler ==
=== التابع <code>HTTPRedirectHandler.http_error_303()‎</code> ===
هذا التابع مشابه للتابع <code>[[Python/urllib/request/HTTPRedirectHandler/http error 301|http_error_301()‎]]</code> ولكن يُستدعى للاستجابة (see other).


تقدّم كائنات <code>BaseHandler</code> تابعين يمكن الاستفادة منهما مباشرة، وعددًا من التوابع التي أعدّت للاستخدام بواسطة الأصناف المشتّقة من هذه الكائنات.  
=== التابع <code>HTTPRedirectHandler.http_error_307()‎</code> ===
هذا التابع مشابه للتابع <code>[[Python/urllib/request/HTTPRedirectHandler/http error 301|http_error_301()‎]]</code> ولكن يُستدعى للإجابة (temporary redirect).


== كائنات HTTPRedirectHandler ==
== كائنات <code>HTTPCookieProcessor</code> ==
تمتلك كائنات <code>HTTPCookieProcessor</code> خاصّية واحدة فقط:


== كائنات HTTPCookieProcessor ==
=== الخاصية <code>HTTPCookieProcessor.cookiejar</code> ===
كائن <code>http.cookiejar.Cookiejar</code> الذي ستخزّن الكعكات فيه.


== كائنات <code>ProxyHandler</code> ==
== كائنات <code>ProxyHandler</code> ==
تقدّم كائنات ProxyHandler التابع التالي:
=== التابع <code>[[Python/urllib/request/ProxyHandler/protocol open|ProxyHandler.protocol_open()]]‎</code> ===
يعدّل التابع الطلبات لتمرّ عبر الوسيط وذلك باستدعاء التابع <code>request.set_proxy()‎</code> واستدعاء الصنف المعالج التالي في سلسلة الأصناف المعالجة وذلك لتنفيذ البروتوكول.


== كائنات <code>HTTPPasswordMgr</code> ==
== كائنات <code>HTTPPasswordMgr</code> ==
التوابع التالية متوفّرة في كائنات <code>HTTPPasswordMgr</code> و <code>HTTPPasswordMgrWithDefaultRealm</code>.
=== التابع <code>[[Python/urllib/HTTPPasswordMgr/add password|HTTPPasswordMgr.add_password()‎]]</code> ===
يؤدي استدعاء هذا التابع إلى استخدام الصفّ <code>(user, passwd)</code> علامات استيثاق رمزية authentication tokens عند إعطاء الاستيثاق للحقل المعطى و المعرفات الفوقية super-URI للمعرّفات المعطاة.


التوابع التالية متوفّرة في كائنات <code>HTTPPasswordMgr</code> و <code>HTTPPasswordMgrWithDefaultRealm</code>.
=== التابع <code>[[Python/urllib/HTTPPasswordMgr/find user password|HTTPPasswordMgr.find_user_password()]]‎</code> ===
يجلب التابع اسم المستخدم وكلمة المرور للحقل realm أو عنوان URI المعطيين.


== كائنات <code>HTTPPasswordMgrWithPriorAuth</code> ==
== كائنات <code>HTTPPasswordMgrWithPriorAuth</code> ==


يوسّع مدير كلمات المرور هذا عمل كائنات <code>HTTPPasswordMgrWithDefaultRealm</code> لدعم عملية تعقّب معرّفات URI التي يجب إرسال معلومات الاستيثاق إليها على الدوام.
يوسّع مدير كلمات المرور هذا عمل كائنات <code>HTTPPasswordMgrWithDefaultRealm</code> لدعم عملية تعقّب معرّفات URI التي يجب إرسال معلومات الاستيثاق إليها دائمًا.
 
تمتلك كائنات <code>HTTPPasswordMgrWithPriorAuth</code> التوابع التالية:
 
=== التابع <code>[[Python/urllib/request/HTTPPasswordMgrWithPriorAuth/add password|HTTPPasswordMgrWithPriorAuth.add_password()‎]]</code> ===
 
=== التابع <code>HTTPPasswordMgrWithPriorAuth.find_user_password()‎</code> ===
هذا التابع مشابه للتابع  <code>[[Python/urllib/HTTPPasswordMgr/find user password|HTTPPasswordMgr.find_user_password()]]‎</code>.
 
=== التابع <code>[[Python/urllib/request/HTTPPasswordMgrWithPriorAuth/update authenticated|HTTPPasswordMgrWithPriorAuth.update_authenticated()‎]]</code> ===
يحدّث التابع قيمة الراية <code>is_authenticated</code> لعنوان URI المعطى أو قائمة عناوين URI المعطاة.
 
=== التابع <code>[[Python/urllib/request/HTTPPasswordMgrWithPriorAuth/is authenticated|HTTPPasswordMgrWithPriorAuth.is_authenticated()‎]]</code> ===
يعيد التابع حالة راية <code>is_authenticated</code> الحالية لعنوان URI المعطى.


== كائنات <code>AbstractBasicAuthHandler</code> ==
== كائنات <code>AbstractBasicAuthHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/AbstractBasicAuthHandler/http error auth reqed|AbstractBasicAuthHandler.http_error_auth_reqed()‎]]</code> ===
يعالج التابع طلب الاستيثاق عن طريق الحصول على زوج اسم المستخدم/كلمة المرور، وإعادة الطلب مرة أخرى.


== كائنات <code>HTTPBasicAuthHandler</code> ==
== كائنات <code>HTTPBasicAuthHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/HTTPBasicAuthHandler/http error 401|HTTPBasicAuthHandler.http_error_401()‎]]</code> ===
يعيد التابع إرسال الطلب مع معلومات الاستيثاق إن كانت متوفّرة.


== كائنات <code>ProxyBasicAuthHandler</code> ==
== كائنات <code>ProxyBasicAuthHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/ProxyBasicAuthHandler/http error 407|ProxyBasicAuthHandler.http_error_407()‎]]</code> ===
يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.


== كائنات <code>AbstractDigestAuthHandler</code> ==
== كائنات <code>AbstractDigestAuthHandler</code> ==
=== التابع <code>[[Python/urllib/request/AbstractDigestAuthHandler/http error auth reqed|AbstractDigestAuthHandler.http_error_auth_reqed()‎]]</code> ===
يعالج التابع طلب الاستيثاق عن طريق الحصول على زوج اسم المستخدم/كلمة المرور، وإعادة الطلب مرة أخرى.


== كائنات <code>HTTPDigestAuthHandler</code> ==
== كائنات <code>HTTPDigestAuthHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/HTTPDigestAuthHandler/http error 401|HTTPDigestAuthHandler.http_error_401()‎]]</code> ===
يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.


== كائنات <code>ProxyDigestAuthHandler</code> ==
== كائنات <code>ProxyDigestAuthHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/ProxyDigestAuthHandler/http error 407|ProxyDigestAuthHandler.http_error_407()‎]]</code> ===
يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.


== كائنات <code>HTTPHandler</code> ==
== كائنات <code>HTTPHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/HTTPHandler/http open|HTTPHandler.http_open()]]‎</code> ===
يرسل التابع طلب HTTP، والذي يمكن أن يكون من نوع <code>GET</code> أو <code>POST</code>، بالاعتماد على التابع <code>req.has_data()</code>‎.


== كائنات <code>HTTPSHandler</code> ==
== كائنات <code>HTTPSHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/HTTPSHandler/https open|HTTPSHandler.https_open()‎]]</code> ===
يرسل التابع طلب HTTPS، والذي يمكن أن يكون من نوع <code>GET</code> أو <code>POST</code>، بالاعتماد على التابع <code>req.has_data()</code>‎.


== كائنات <code>FileHandler</code> ==
== كائنات <code>FileHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/FileHandler/file open|FileHandler.file_open()]]‎</code> ===
يفتح التابع الملفّ محلّيًا، إن لم يحدد اسم المضيف، أو كان اسم المضيف هو <code>'localhost'</code>.


== كائنات <code>DataHandler</code> ==
== كائنات <code>DataHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/DataHandler/data open|DataHandler.data_open()‎]]</code> ===
يقرأ التابع عنوان URL للبيانات.


== كائنات <code>FTPHandler</code> ==
== كائنات <code>FTPHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/FTPHandler/ftp open|FTPHandler.ftp_open()‎]]</code> ===
يفتح التابع ملف FTP المحدّد في الطلب المعطى.


== كائنات <code>CacheFTPHandler</code> ==
== كائنات <code>CacheFTPHandler</code> ==
هذه الكائنات هي كائنات <code>FTPHandler</code> مع التوابع الإضافية التالية:
=== التابع <code>[[Python/urllib/request/CacheFTPHandler/setTimeout|CacheFTPHandler.setTimeout()‎]]</code> ===
يحدّد التابع المهلة المسموحة للاتصالات بالثواني.
=== التابع <code>[[Python/urllib/request/CacheFTPHandler/setMaxConns|CacheFTPHandler.setMaxConns()]]‎</code> ===
يحدّد التابع العدد الأقصى للاتصالات المخزّنة في الذاكرة الخبيئة.


== كائنات <code>UnknownHandler</code> ==
== كائنات <code>UnknownHandler</code> ==
تمتلك هذه الكائنات التابع التالي:
=== التابع <code>[[Python/urllib/request/UnknownHandler/unknown open|UnknownHandler.unknown_open()‎]]</code> ===
يطلق هذا التابع الاستثناء <code>URLError</code>.


== كائنات <code>HTTPErrorProcessor</code> ==
== كائنات <code>HTTPErrorProcessor</code> ==
تمتلك هذه الكائنات التابعين التاليين:
=== التابع <code>[[Python/urllib/request/HTTPErrorProcessor/http response|HTTPErrorProcessor.http_response()‎]]</code> ===
يعالج استجابات HTTP التي تتضمن أخطاءً.
=== التابع <code>[[Python/urllib/request/HTTPErrorProcessor/https response|HTTPErrorProcessor.https_response()‎]]</code> ===
يعالج التابع استجابات HTTPS التي تتضمّن أخطاءً، ويعمل بنفس طريقة عمل التابع <code>http_resonse()‎</code>.


== الواجهة القديمة  ==
== الواجهة القديمة  ==
الدوال والأصناف التالية منقولة من الوحدة <code>urllib</code> في الإصدار الثاني من بايثون (وليست من الوحدة urllib2)، وقد تصبح مهملة في المستقبل:
الدوال والأصناف التالية منقولة من الوحدة <code>urllib</code> في الإصدار الثاني من بايثون (وليست من الوحدة <code>urllib2</code>)، وقد تصبح مهملة في المستقبل:
 
=== الدالة<code>[[Python/urllib/request/urlretrieve|urllib.request.urlretrieve()‎]]</code> ===
تنسخ الدالة كائن شبكة network object المشار إليه بواسطة عنوان URL إلى ملف محلّي.
 
=== الدالة <code>[[Python/urllib/request/urlcleanup|urllib.request.urlcleanup()‎]]</code> ===
تحذف الدالة الملفات المؤقتة التي خلّفتها الاستدعاءات السابقة للدالة <code>[[Python/urllib/request/urlretrieve|urlretrieve()‎]]</code>.
 
=== الصنف <code>[[Python/urllib/request/URLopener|urllib.request.URLopener]]</code> ===
هذا هو الصنف الأساسي لفتح وقراءة عناوين URL. إن لم تكن ترغب في دعم فتح الكائنات باستخدام مخطّطات <code>http:</code>‎ أو <code>ftp:‎</code> أو <code>file</code>، فستحتاج على الأرجح إلى استخدام الصنف <code>FancyURLopener</code>.
 
=== الصنف <code>[[Python/urllib/request/FancyURLopener|urllib.request.FancyURLopener]]</code> ===
يتفرّع الصنف <code>FancyURLopener</code> من الصنف <code>URLopener</code> ويقدّم معالجة افتراضية لشيفرات استجابة HTTP التالية: 301، 302، 303، 307، 401.


== محدّدات وحدة urllib.request ==
== محدّدات وحدة <code>urllib.request</code> ==
* البروتوكولات المدعومة في الوقت الحاضر هي: HTTP (الإصداران 0.9 و 1.0) وFTP والملفات المحلية وعناوين URL للبيانات.
* البروتوكولات المدعومة في الوقت الحاضر هي: HTTP (الإصداران 0.9 و 1.0) وFTP والملفات المحلية وعناوين URL للبيانات.
ملاحظة: أضيف دعم عناوين URL للبيانات في الإصدار 3.4 من بايثون.
ملاحظة: أضيف دعم عناوين URL للبيانات في الإصدار 3.4 من بايثون.
* خاصية التخزين في الذاكرة المخبئية caching للدالة <code>urlretrieve()</code>‎ معطلة إلى أن يجد شخصٌ ما الوقت الكافي لتطوير طريقة معالجة مناسبة لترويسات Expiration time.
* خاصية التخزين في الذاكرة المخبئية caching للدالة <code>[[Python/urllib/request/urlretrieve|urlretrieve()]]</code>‎ معطلة إلى أن يجد شخصٌ ما الوقت الكافي لتطوير طريقة معالجة مناسبة لترويسات Expiration time.
* يجب أن تكون هناك دالة للاستعلام عمّا إذا كان عنوان URL معيّن مخزّنًا في الذاكرة المخبئية.
* يجب أن تكون هناك دالة للاستعلام عمّا إذا كان عنوان URL معيّن مخزّنًا في الذاكرة المخبئية.
* إن أشار عنوان URL إلى ملف محلي ولم يكن بالإمكان فتح ذلك الملف، فإنّ عنوان URL سيفسّر مرّة أخرى باستخدام بروتوكول FTP، وذلك لأغراض التوافق مع الإصدارات السابقة من بايثون. قد يؤدي هذا السلوك إلى الحصول على رسائل أخطاء مربكة.  
* إن أشار عنوان URL إلى ملف محلي ولم يكن بالإمكان فتح ذلك الملف، فإنّ عنوان URL سيفسّر مرّة أخرى باستخدام بروتوكول FTP، وذلك لأغراض التوافق مع الإصدارات السابقة من بايثون. قد يؤدي هذا السلوك إلى الحصول على رسائل أخطاء مربكة.  
* يمكن أن تتسبّب الدالتان <code>urlopen()‎</code> و <code>urlretrieve()</code>‎ في حدوث فترات تأخير طويلة وذلك في انتظار تهيئة اتصال الشبكة. وهذا يعني صعوبة بناء عميل ويب تفاعلي باستخدام هذه الدوال دون اللجوء إلى الخيوط threads.
* يمكن أن تتسبّب الدالتان <code>[[Python/urllib/request/urlopen|urlopen()]]‎</code> و <code>[[Python/urllib/request/urlretrieve|urlretrieve()]]</code>‎ في حدوث فترات تأخير طويلة وذلك في انتظار تهيئة اتصال الشبكة. وهذا يعني صعوبة بناء عميل ويب تفاعلي باستخدام هذه الدوال دون اللجوء إلى الخيوط threads.
* تكون البيانات المعادة من الدالة <code>urlopen()</code>‎ أو <code>urlretrieve()‎</code> هي البيانات الخام المعادة من المخدّم، والتي يمكن أن تكون بيانات ثنائية (مثل الصور) أو بيانات نصية صرفة أو HTML. يقدّم بروتوكول HTTP نوع البيانات في ترويسة الرد reply header، والتي يمكن تعقبّها باستخدام ترويسة Content-Type. إن كانت البيانات المعادة من نوع HTML، فيمكن استخدام الوحدة html.parser لتحليلها.
* تكون البيانات المعادة من الدالة [[Python/urllib/request/urlopen|<code>urlopen()</code>]]‎ أو <code>[[Python/urllib/request/urlretrieve|urlretrieve()]]‎</code> هي البيانات الخام المعادة من المخدّم، والتي يمكن أن تكون بيانات ثنائية (مثل الصور) أو بيانات نصية صرفة أو HTML. يقدّم بروتوكول HTTP نوع البيانات في ترويسة الرد reply header، والتي يمكن تعقبّها باستخدام ترويسة <code>Content-Type</code>. إن كانت البيانات المعادة من نوع HTML، فيمكن استخدام الوحدة <code>[[Python/html/parser|html.parser]]</code> لتحليلها.
* لا يمكن للشيفرة التي تعالج بروتوكول FTP أن تميّز بين الملف والمجلّد، ويمكن لهذا أن يتسبب في حدوث أخطاء غير متوقعة عند محاولة قراءة عنوان URL يشير إلى ملف لا يمكن الوصول إليه. إن انتهى عنوان URL بالرمز / فستفترض الشيفرة أنّه يشير إلى مجلد وستتعامل معه على أساس ذلك. ولكن إن أدّت محاولة قراءة ملفّ إلى التسبّب في الخطأ 550 (ما يعني أنّ عنوان URL غير موجود أو غير قابل للوصول إليه، وغالبًا ما يحدث ذلك بسبب الأذونات) فإنّ المسار سيعامل معاملة المجلّد وذلك لمعالجة الحالة التي يُحدّد فيها المجلّد بواسطة عنوان URL ولكن مع ترك علامة / في نهاية العنوان. يمكن أن يؤدي هذا الأمر إلى الحصول على نتائج مضللة عند محاولة جلب ملفّ لا تسمح أذوناته بقرائته، وذلك لأنّ شيفرة FTP ستحاول قراءة هذا الملف، فتفشل العملية ويعاد الخطأ 550، ثم تسرد الشيفرة محتويات المجلّد التي تكون غير قابلة للقراءة. يمكن التحكّم بصورة أكبر في هذا الأمر عن طريق استخدام الوحدة ftplib، أو تفريع الصنف <code>FancyURLopener</code> أو تغيير <code>‎_urlopener</code> حسب الحاجة.
* لا يمكن للشيفرة التي تعالج بروتوكول FTP أن تميّز بين الملف والمجلّد، ويمكن لهذا أن يتسبب في حدوث أخطاء غير متوقعة عند محاولة قراءة عنوان URL يشير إلى ملف لا يمكن الوصول إليه. إن انتهى عنوان URL بالرمز / فستفترض الشيفرة أنّه يشير إلى مجلد وستتعامل معه على أساس ذلك. ولكن إن أدّت محاولة قراءة ملفّ إلى التسبّب في الخطأ <code>550</code> (ما يعني أنّ عنوان URL غير موجود أو غير قابل للوصول إليه، وغالبًا ما يحدث ذلك بسبب الأذونات) فإنّ المسار سيعامل معاملة المجلّد وذلك لمعالجة الحالة التي يُحدّد فيها المجلّد بواسطة عنوان URL ولكن مع ترك علامة / في نهاية العنوان. يمكن أن يؤدي هذا الأمر إلى الحصول على نتائج مضللة عند محاولة جلب ملفّ لا تسمح أذوناته بقرائته، وذلك لأنّ شيفرة FTP ستحاول قراءة هذا الملف، فتفشل العملية ويعاد الخطأ <code>550</code>، ثم تسرد الشيفرة محتويات المجلّد التي تكون غير قابلة للقراءة. يمكن التحكّم بصورة أكبر في هذا الأمر عن طريق استخدام الوحدة <code>[[Python/ftplib|ftplib]]</code>، أو تفريع الصنف <code>FancyURLopener</code> أو تغيير <code>‎_urlopener</code> حسب الحاجة.


== مصادر ==
== مصادر ==

المراجعة الحالية بتاريخ 18:29، 6 فبراير 2019


تقدّم وحدة urllib.request عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL‏ (HTTP في الغالب) لاستخدامها في عمليات مختلفة مثل الاستيثاق البسيط وإعادة التوجيه والتعامل مع الكعكات cookies وغيرها.

ملاحظة: يُنصح باستخدام الحزمة Requests في العمليات المتقدّمة لأنّها توفّر واجهة برمجية ذات مستوى أعلى.

دوالّ الوحدة urllib.request

تقدّم وحدة urllib.request الدوال التالية:

الدالة urllib.request.urlopen()‎

تفتح الدالة عنوان URL المعطى.

urllib.request.install_opener()‎

تثبّت الدالة نسخة من الصنف OpenerDirector كفاتح opener افتراضي عام.

urllib.request.build_opener()‎

تعيد الدالة نسخة من الصنف OpenerDirector والتي تربط بين المعالجات handlers حسب الترتيب المعطى. 

urllib.request.pathname2url()‎

تحوّل الدالة المسار المعطى من الصيغة المستخدمة في المسارات المحلية إلى الصيغة المستخدمة في عناوين URL.

urllib.request.url2pathname()‎

تحوّل الدالة مكونات المسار المعطى من عنوان URL مرمّز بعلامة النسبة المئوية إلى الصيغة المحلّية للمسارات. 

urllib.request.getproxies()‎

تعيد هذه الدالة المساعدة قاموسًا يربط بين المخطّط scheme وعناوين URL في مخدّم الوسيط. 

أصناف الوحدة urllib.request

تقدّم الوحدة الأصناف التالية:

الصنف urllib.request.Request

يعدّ هذا الصنف تجريدًا abstraction لطلب URL.

الصنف urllib.request.OpenerDirector

يفتح هذا الصنف عناوين URL بواسطة الصنف BaseHandlers المرتبط به. يتحكّم هذا الصنف بعملية ربط الأصناف المعالجة بعضها ببعض، والتعافي من الأخطاء.

الصنف urllib.request.BaseHandler

الصنف الأساسي لجميع أصناف المعالجة المسجّلة، ويعالج عملية التسجيل البسيطة فقط.

الصنف urllib.request.HTTPDefaultErrorHandler

يعرّف هذا الصنف معالجًا افتراضيًا للاستجابات الخاصّة بأخطاء HTTP، وتحوّل جميع الاستجابات إلى استثناءات HTTPError.

الصنف urllib.request.HTTPRedirectHandler

يعالج هذا الصنف عمليات إعادة التوجيه redirection.

الصنف urllib.request.HTTPCookieProcessor

يعالج هذا الصنف كعكات HTTP.

الصنف urllib.request.ProxyHandler

يتسبب هذا الصنف في تمرير الطلبات عبر وسيط معيّن.

الصنف urllib.request.HTTPPasswordMgr

يحتفظ الصنف بقاعدة بيانات من روابط ‎(realm, uri) -> (user, password)‎.

الصنف urllib.request.HTTPPasswordMgrWithDefaultRealm

يحتفظ الصنف بقاعدة بيانات من روابط ‎(realm, uri) -> (user, password)‎.

يعدّ الحقل None حقلًا عامًّا ويجري البحث عنه في حال عدم مطابقة أي حقل آخر.

الصنف urllib.request.HTTPPasswordMgrWithPriorAuth

شكل مختلف من الصنف HTTPPasswordMgrWithDefaultRealm ويمتلك قاعدة بيانات فيها روابط ‎uri -> is_authenticated. يمكن استخدام هذا الصنف بواسطة الصنف المعالج BasicAuth لتحديد متى يمكن إرسال معلومات الاستيثاق مباشرة دون الحاجة إلى انتظار الاستجابة 401 أوّلًا.

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

الصنف urllib.request.AbstractBasicAuthHandler

صنف مخلوط mixin class يساعد في عمليات استيثاق HTTP لكلٍّ من المضيف البعيد remote host والوسيط proxy.

الصنف urllib.request.HTTPBasicAuthHandler

يعالج هذا الصنف عملية الاستيثاق مع المضيف البعيد.

الصنف urllib.request.ProxyBasicAuthHandler

يعالج هذا الصنف عملية الاستيثاق مع الوسيط.

الصنف urllib.request.AbstractDigestAuthHandler

صنف مخلوط mixin class يساعد في عمليات استيثاق HTTP لكلٍّ من المضيف البعيد remote host والوسيط proxy.

الصنف urllib.request.HTTPDigestAuthHandler

يعالج هذا الصنف عملية الاستيثاق مع المضيف البعيد.

الصنف urllib.request.ProxyDigestAuthHandler

يعالج هذا الصنف عملية الاستيثاق مع الوسيط.

الصنف urllib.request.HTTPHandler

يعالج هذا الصنف عملية فتح عناوين HTTP.

الصنف urllib.request.HTTPSHandler

يعالج هذا الصنف عملية فتح عناوين HTTPS.

الصنف urllib.request.FileHandler

يفتح ملفًّا محلّيًا.

الصنف urllib.request.DataHandler

يفتح عنوان بيانات.

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

الصنف urllib.request.FTPHandler

يفتح عناوين FTP.

الصنف urllib.request.CacheFTPHandler

يفتح عناوين FTP ويحتفظ باتصالات FTP المفتوحة في الذاكرة المؤقتة وذلك تجنّبًا للتأخير.

الصنف urllib.request.UnknownHandler

صنف شامل لمعالجة العناوين المجهولة.

الصنف urllib.request.HTTPErrorProcessor

صنف لمعالجة استجابات HTTP الخاصة بالأخطاء.

كائنات OpenerDirector

تفتح كائنات OpenerDirector عناوين URL عبر ثلاث مراحل، ويُحدّد ترتيب استدعاء هذا التوابع في كلّ مرحلة عن طريق ترتيب نسخ أصناف المعالجة.

  1. كلّ معالج يمتلك تابعًا يحمل اسمًا مثل protocol_request()‎ سيستدعي ذلك التابع للمعالجة القبلية pre-process للطلب.
  2. المعالجات التي تمتلك تابعًا يحمل اسمًا مثل protocol_open()‎ ستستدعى لمعالجة الطلب. تنتهي هذه المرحلة عندما يعيد معالجٌ ما قيمة غير القيمة None (أي يعيد استجابة) أو عندما يطلق استثناءً (عادة ما يكون URLError)، ويُسمح للاستثناءات بالتكرار. تجري تجربة الخوارزمية السابقة مع التوابع التي تحمل اسمًا مثل default_open()‎، وإن أعادت جميع هذه التوابع القيمة None، فإنّ الخوارزمية ستُعاد مع التوابع التي تحمل اسمًا مثل protocol_open()‎، وإن أعادت جميع هذه التوابع القيمة None، فإنّ الخوارزمية ستُعاد مع التوابع التي تحمل اسمًا مثل unknown_open()‎. يجدر الانتباه إلى أنّ استخدام هذه التوابع قد يتضمّن استدعاءات للتابعين open()‎ و error()‎ في نسخة الصنف OpenerDirector الأب.
  3. كلّ معالج يمتلك تابعًا يحمل اسمًا مثل protocol_response()‎ سيستدعي ذلك التابع للمعالجة البعدية post-process للاستجابة.

تمتلك كائنات OpenerDirector التوابع التالية:

التابع OpenerDirector.add_handler()‎

يضيف التابع صنف معالجة إلى كائن OpenerDirector.

التابع OpenerDirector.open()‎

يفتح التابع العنوان المعطى.

التابع OpenerDirector.error()‎

يعالج هذا التابع خطأً معيّنًا في البروتوكول المعطى. 

كائنات BaseHandler

تقدّم كائنات BaseHandler تابعين يمكن الاستفادة منهما مباشرة، وعددًا من التوابع التي أعدّت للاستخدام بواسطة الأصناف المشتّقة من هذه الكائنات.

يُستخدم التابعان التاليان مباشرة:

التابع BaseHandler.add_parent()‎

يضيف التابع الموجّه المعطى كموجّه أب.

التابع BaseHandler.close()‎

يحذف التابع أي موجّهات أبوية.

يجب استخدام التوابع والخصائص التالية من قبل الأصناف المشتقّة من الصنف BaseHandler فقط.

ملاحظة

جرى الاتفاق على تسمية الأصناف الفرعية التي تعرّف التابع protocol_request()‎ أو protocol_response()‎ بالاسم ‎*Processor، وتُسمّى الأصناف الفرعية الأخرى بالاسم ‎*Handler.

الخاصية BaseHandler.parent

كائن OpenerDirector صالح للاستخدام، والذي يمكن استخدامه لفتح العناوين باستخدام بروتكول مختلف أو لمعالجة الأخطاء.

التابع BaseHandler.default_open()‎

هذا التابع غير معرّف في الصنف BaseHandler، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب التقاط جميع عناوين URL.

التابع BaseHandler.protocol_open()‎

هذا التابع غير معرّف في الصنف BaseHandler، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب معالجة عناوين URL مع البروتوكول المعطى.

التابع BaseHandler.unknown_open()‎

هذا التابع غير معرّف في الصنف BaseHandler، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب التقاط جميع عناوين URL دون تحديد أيّ معالج مسجّل لفتح هذه العناوين.

التابع BaseHandler.http_error_default()‎

يُستدعى هذا التابع تلقائيًا بواسطة كائن OpenerDirector الذي يتلقّى الخطأ، ويجب عدم استدعائه في الظروف الأخرى.

التابع BaseHandler.http_error_nnn()‎

هذا التابع غير معرّف في الصنف BaseHandler أيضًا، ولكن سيُستدعى إن كان موجودًا على نسخة من الصنف المتفرّع عن الصنف BaseHandler عند حدوث خطأ HTTP يحمل الشيفرة nnn.

التابع BaseHandler.protocol_request()‎

هذا التابع غير معرّف في الصنف BaseHandler، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب إجراء معالجة قبلية للطلبات الخاصّة بالبروتكول المعطى.

التابع BaseHandler.protocol_response()‎

هذا التابع غير معرّف في الصنف BaseHandler، ولكن يجب على الأصناف المتفرّعة منه أن تعرّف هذا التابع إن كان المطلوب إجراء معالجة بعدية للاستجابات الخاصّة بالبروتكول المعطى.

كائنات HTTPRedirectHandler

ملاحظة:

تحتاج بعض عمليات إعادة التوجيه في HTTP إلى بعض الأحداث من شيفرة الوحدة التابعة للعميل، وتُطلق الوحدة الاستثناء HTTPError إن كانت هذه هيه الحالة. راجع المعيار RFC 2616 للمزيد من التفاصيل حول المعنى الدقيق لشيفرات إعادة التوجيه المختلفة.

يُطلق الاستثناء HTTPError كإجراء احترازي إن حصل المعالج HTTPRedirectHandler على عنوان URL لا ينتمي إلى بروتكولات HTTP أو HTTPS أو FTP.

تقدم كائنات HTTPRedirecthandler التوابع التالية:

التابع HTTPRedirectHandler.redirect_request()‎

يعيد التابع كائن Request أو القيمة None استجابةً لعملية إعادة توجيه.

التابع HTTPRedirectHandler.http_error_301()‎

يعيد التابع التوجيه إلى عنوان Location:‎ أو URI:‎.

التابع HTTPRedirectHandler.http_error_302()‎

هذا التابع مشابه للتابع http_error_301()‎ ولكن يُستدعى للاستجابة (found).

التابع HTTPRedirectHandler.http_error_303()‎

هذا التابع مشابه للتابع http_error_301()‎ ولكن يُستدعى للاستجابة (see other).

التابع HTTPRedirectHandler.http_error_307()‎

هذا التابع مشابه للتابع http_error_301()‎ ولكن يُستدعى للإجابة (temporary redirect).

كائنات HTTPCookieProcessor

تمتلك كائنات HTTPCookieProcessor خاصّية واحدة فقط:

الخاصية HTTPCookieProcessor.cookiejar

كائن http.cookiejar.Cookiejar الذي ستخزّن الكعكات فيه.

كائنات ProxyHandler

تقدّم كائنات ProxyHandler التابع التالي:

التابع ProxyHandler.protocol_open()‎

يعدّل التابع الطلبات لتمرّ عبر الوسيط وذلك باستدعاء التابع request.set_proxy()‎ واستدعاء الصنف المعالج التالي في سلسلة الأصناف المعالجة وذلك لتنفيذ البروتوكول.

كائنات HTTPPasswordMgr

التوابع التالية متوفّرة في كائنات HTTPPasswordMgr و HTTPPasswordMgrWithDefaultRealm.

التابع HTTPPasswordMgr.add_password()‎

يؤدي استدعاء هذا التابع إلى استخدام الصفّ (user, passwd) علامات استيثاق رمزية authentication tokens عند إعطاء الاستيثاق للحقل المعطى و المعرفات الفوقية super-URI للمعرّفات المعطاة.

التابع HTTPPasswordMgr.find_user_password()‎

يجلب التابع اسم المستخدم وكلمة المرور للحقل realm أو عنوان URI المعطيين.

كائنات HTTPPasswordMgrWithPriorAuth

يوسّع مدير كلمات المرور هذا عمل كائنات HTTPPasswordMgrWithDefaultRealm لدعم عملية تعقّب معرّفات URI التي يجب إرسال معلومات الاستيثاق إليها دائمًا.

تمتلك كائنات HTTPPasswordMgrWithPriorAuth التوابع التالية:

التابع HTTPPasswordMgrWithPriorAuth.add_password()‎

التابع HTTPPasswordMgrWithPriorAuth.find_user_password()‎

هذا التابع مشابه للتابع HTTPPasswordMgr.find_user_password()‎.

التابع HTTPPasswordMgrWithPriorAuth.update_authenticated()‎

يحدّث التابع قيمة الراية is_authenticated لعنوان URI المعطى أو قائمة عناوين URI المعطاة.

التابع HTTPPasswordMgrWithPriorAuth.is_authenticated()‎

يعيد التابع حالة راية is_authenticated الحالية لعنوان URI المعطى.

كائنات AbstractBasicAuthHandler

تمتلك هذه الكائنات التابع التالي:

التابع AbstractBasicAuthHandler.http_error_auth_reqed()‎

يعالج التابع طلب الاستيثاق عن طريق الحصول على زوج اسم المستخدم/كلمة المرور، وإعادة الطلب مرة أخرى.

كائنات HTTPBasicAuthHandler

تمتلك هذه الكائنات التابع التالي:

التابع HTTPBasicAuthHandler.http_error_401()‎

يعيد التابع إرسال الطلب مع معلومات الاستيثاق إن كانت متوفّرة.

كائنات ProxyBasicAuthHandler

تمتلك هذه الكائنات التابع التالي:

التابع ProxyBasicAuthHandler.http_error_407()‎

يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.

كائنات AbstractDigestAuthHandler

التابع AbstractDigestAuthHandler.http_error_auth_reqed()‎

يعالج التابع طلب الاستيثاق عن طريق الحصول على زوج اسم المستخدم/كلمة المرور، وإعادة الطلب مرة أخرى.

كائنات HTTPDigestAuthHandler

تمتلك هذه الكائنات التابع التالي:

التابع HTTPDigestAuthHandler.http_error_401()‎

يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.

كائنات ProxyDigestAuthHandler

تمتلك هذه الكائنات التابع التالي:

التابع ProxyDigestAuthHandler.http_error_407()‎

يعيد التابع إرسال الطلب مع معلومات الاستيثاق، إن كانت متوفّرة.

كائنات HTTPHandler

تمتلك هذه الكائنات التابع التالي:

التابع HTTPHandler.http_open()‎

يرسل التابع طلب HTTP، والذي يمكن أن يكون من نوع GET أو POST، بالاعتماد على التابع req.has_data()‎.

كائنات HTTPSHandler

تمتلك هذه الكائنات التابع التالي:

التابع HTTPSHandler.https_open()‎

يرسل التابع طلب HTTPS، والذي يمكن أن يكون من نوع GET أو POST، بالاعتماد على التابع req.has_data()‎.

كائنات FileHandler

تمتلك هذه الكائنات التابع التالي:

التابع FileHandler.file_open()‎

يفتح التابع الملفّ محلّيًا، إن لم يحدد اسم المضيف، أو كان اسم المضيف هو 'localhost'.

كائنات DataHandler

تمتلك هذه الكائنات التابع التالي:

التابع DataHandler.data_open()‎

يقرأ التابع عنوان URL للبيانات.

كائنات FTPHandler

تمتلك هذه الكائنات التابع التالي:

التابع FTPHandler.ftp_open()‎

يفتح التابع ملف FTP المحدّد في الطلب المعطى.

كائنات CacheFTPHandler

هذه الكائنات هي كائنات FTPHandler مع التوابع الإضافية التالية:

التابع CacheFTPHandler.setTimeout()‎

يحدّد التابع المهلة المسموحة للاتصالات بالثواني.

التابع CacheFTPHandler.setMaxConns()‎

يحدّد التابع العدد الأقصى للاتصالات المخزّنة في الذاكرة الخبيئة.

كائنات UnknownHandler

تمتلك هذه الكائنات التابع التالي:

التابع UnknownHandler.unknown_open()‎

يطلق هذا التابع الاستثناء URLError.

كائنات HTTPErrorProcessor

تمتلك هذه الكائنات التابعين التاليين:

التابع HTTPErrorProcessor.http_response()‎

يعالج استجابات HTTP التي تتضمن أخطاءً.

التابع HTTPErrorProcessor.https_response()‎

يعالج التابع استجابات HTTPS التي تتضمّن أخطاءً، ويعمل بنفس طريقة عمل التابع http_resonse()‎.

الواجهة القديمة

الدوال والأصناف التالية منقولة من الوحدة urllib في الإصدار الثاني من بايثون (وليست من الوحدة urllib2)، وقد تصبح مهملة في المستقبل:

الدالةurllib.request.urlretrieve()‎

تنسخ الدالة كائن شبكة network object المشار إليه بواسطة عنوان URL إلى ملف محلّي.

الدالة urllib.request.urlcleanup()‎

تحذف الدالة الملفات المؤقتة التي خلّفتها الاستدعاءات السابقة للدالة urlretrieve()‎.

الصنف urllib.request.URLopener

هذا هو الصنف الأساسي لفتح وقراءة عناوين URL. إن لم تكن ترغب في دعم فتح الكائنات باستخدام مخطّطات http:‎ أو ftp:‎ أو file، فستحتاج على الأرجح إلى استخدام الصنف FancyURLopener.

الصنف urllib.request.FancyURLopener

يتفرّع الصنف FancyURLopener من الصنف URLopener ويقدّم معالجة افتراضية لشيفرات استجابة HTTP التالية: 301، 302، 303، 307، 401.

محدّدات وحدة urllib.request

  • البروتوكولات المدعومة في الوقت الحاضر هي: HTTP (الإصداران 0.9 و 1.0) وFTP والملفات المحلية وعناوين URL للبيانات.

ملاحظة: أضيف دعم عناوين URL للبيانات في الإصدار 3.4 من بايثون.

  • خاصية التخزين في الذاكرة المخبئية caching للدالة urlretrieve()‎ معطلة إلى أن يجد شخصٌ ما الوقت الكافي لتطوير طريقة معالجة مناسبة لترويسات Expiration time.
  • يجب أن تكون هناك دالة للاستعلام عمّا إذا كان عنوان URL معيّن مخزّنًا في الذاكرة المخبئية.
  • إن أشار عنوان URL إلى ملف محلي ولم يكن بالإمكان فتح ذلك الملف، فإنّ عنوان URL سيفسّر مرّة أخرى باستخدام بروتوكول FTP، وذلك لأغراض التوافق مع الإصدارات السابقة من بايثون. قد يؤدي هذا السلوك إلى الحصول على رسائل أخطاء مربكة.
  • يمكن أن تتسبّب الدالتان urlopen()‎ و urlretrieve()‎ في حدوث فترات تأخير طويلة وذلك في انتظار تهيئة اتصال الشبكة. وهذا يعني صعوبة بناء عميل ويب تفاعلي باستخدام هذه الدوال دون اللجوء إلى الخيوط threads.
  • تكون البيانات المعادة من الدالة urlopen()‎ أو urlretrieve()‎ هي البيانات الخام المعادة من المخدّم، والتي يمكن أن تكون بيانات ثنائية (مثل الصور) أو بيانات نصية صرفة أو HTML. يقدّم بروتوكول HTTP نوع البيانات في ترويسة الرد reply header، والتي يمكن تعقبّها باستخدام ترويسة Content-Type. إن كانت البيانات المعادة من نوع HTML، فيمكن استخدام الوحدة html.parser لتحليلها.
  • لا يمكن للشيفرة التي تعالج بروتوكول FTP أن تميّز بين الملف والمجلّد، ويمكن لهذا أن يتسبب في حدوث أخطاء غير متوقعة عند محاولة قراءة عنوان URL يشير إلى ملف لا يمكن الوصول إليه. إن انتهى عنوان URL بالرمز / فستفترض الشيفرة أنّه يشير إلى مجلد وستتعامل معه على أساس ذلك. ولكن إن أدّت محاولة قراءة ملفّ إلى التسبّب في الخطأ 550 (ما يعني أنّ عنوان URL غير موجود أو غير قابل للوصول إليه، وغالبًا ما يحدث ذلك بسبب الأذونات) فإنّ المسار سيعامل معاملة المجلّد وذلك لمعالجة الحالة التي يُحدّد فيها المجلّد بواسطة عنوان URL ولكن مع ترك علامة / في نهاية العنوان. يمكن أن يؤدي هذا الأمر إلى الحصول على نتائج مضللة عند محاولة جلب ملفّ لا تسمح أذوناته بقرائته، وذلك لأنّ شيفرة FTP ستحاول قراءة هذا الملف، فتفشل العملية ويعاد الخطأ 550، ثم تسرد الشيفرة محتويات المجلّد التي تكون غير قابلة للقراءة. يمكن التحكّم بصورة أكبر في هذا الأمر عن طريق استخدام الوحدة ftplib، أو تفريع الصنف FancyURLopener أو تغيير ‎_urlopener حسب الحاجة.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Python/urllib/request&oldid=27640»