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

من موسوعة حسوب
< Python‏ | urllib
التعديل اللاحق ←
مرئينص الويكي
أنشأ الصفحة ب'تقدّم وحدة urllib.request عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL‏ (HTTP في الغالب) لاستخ...'
 
لا ملخص تعديل
سطر 3: سطر 3:
ملاحظة: يُنصح باستخدام الحزمة Requests في العمليات المتقدّمة لأنّها توفّر واجهة برمجية ذات مستوى أعلى.
ملاحظة: يُنصح باستخدام الحزمة Requests في العمليات المتقدّمة لأنّها توفّر واجهة برمجية ذات مستوى أعلى.


== دوالّ الوحدة urllib.request ==
== دوالّ الوحدة <code>urllib.request</code> ==


تقدّم وحدة urllib.request الدوال التالية:
تقدّم وحدة <code>urllib.request</code> الدوال التالية:


=== <code>urllib.request.urlopen()‎</code> ===
=== <code>urllib.request.urlopen()‎</code> ===
سطر 14: سطر 14:
=== <code>urllib.request.getproxies()‎</code> ===
=== <code>urllib.request.getproxies()‎</code> ===


== أصناف الوحدة urllib.request ==
== أصناف الوحدة <code>urllib.request</code> ==


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


=== الصنف urllib.request.Request ===
=== الصنف <code>urllib.request.Request</code> ===


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


class urllib.request.BaseHandler
=== الصنف <code>urllib.request.BaseHandler</code> ===
 
الصنف الأساسي لجميع أصناف المعالجة المسجّلة، ويعالج عملية التسجيل البسيطة فقط.
الصنف الأساسي لجميع أصناف المعالجة المسجّلة، ويعالج عملية التسجيل البسيطة فقط.


class urllib.request.HTTPDefaultErrorHandler
=== الصنف <code>urllib.request.HTTPDefaultErrorHandler</code> ===
 
يعرّف هذا الصنف معالجًا افتراضيًا للاستجابات الخاصّة بأخطاء HTTP، وتحوّل جميع الاستجابات إلى استثناءات HTTPError.
يعرّف هذا الصنف معالجًا افتراضيًا للاستجابات الخاصّة بأخطاء HTTP، وتحوّل جميع الاستجابات إلى استثناءات HTTPError.


class urllib.request.HTTPRedirectHandler
=== الصنف <code>urllib.request.HTTPRedirectHandler</code> ===
 
يعالج هذا الصنف عمليات إعادة التوجيه redirection.
يعالج هذا الصنف عمليات إعادة التوجيه redirection.


class urllib.request.HTTPCookieProcessor(cookiejar=None)
=== الصنف <code>urllib.request.HTTPCookieProcessor</code> ===
 
يعالج هذا الصنف كعكات HTTP.
يعالج هذا الصنف كعكات HTTP.


class urllib.request.ProxyHandler
=== الصنف <code>urllib.request.ProxyHandler</code> ===


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


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


class urllib.request.HTTPPasswordMgrWithDefaultRealm
يحتفظ الصنف بقاعدة بيانات من روابط ‎(realm, uri) -> (user, password).
A realm of None is considered a catch-all realm, which is searched if no other realm fits.
A realm of None is considered a catch-all realm, which is searched if no other realm fits.


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


class urllib.request.AbstractBasicAuthHandler
=== الصنف <code>urllib.request.AbstractBasicAuthHandler</code> ===


class urllib.request.HTTPBasicAuthHandler
=== الصنف <code>urllib.request.HTTPBasicAuthHandler</code> ===


class urllib.request.ProxyBasicAuthHandler
=== الصنف <code>urllib.request.ProxyBasicAuthHandler</code> ===


class urllib.request.AbstractDigestAuthHandler
=== الصنف <code>urllib.request.AbstractDigestAuthHandler</code> ===


class urllib.request.HTTPDigestAuthHandler
=== الصنف <code>urllib.request.HTTPDigestAuthHandler</code> ===


class urllib.request.ProxyDigestAuthHandler
=== الصنف <code>urllib.request.ProxyDigestAuthHandler</code> ===


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


class urllib.request.HTTPSHandler
=== الصنف <code>urllib.request.HTTPSHandler</code> ===


class urllib.request.FileHandler
=== الصنف <code>urllib.request.FileHandler</code> ===
يفتح ملفًّا محلّيًا.
يفتح ملفًّا محلّيًا.


class urllib.request.DataHandler
=== الصنف <code>urllib.request.DataHandler</code> ===
يفتح عنوان بيانات.


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


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


class urllib.request.CacheFTPHandler
=== الصنف <code>urllib.request.CacheFTPHandler</code> ===
 
يفتح عناوين FTP ويحتفظ باتصالات FTP المفتوحة في الذاكرة المؤقتة وذلك تجنّبًا للتأخير.
يفتح عناوين FTP ويحتفظ باتصالات FTP المفتوحة في الذاكرة المؤقتة وذلك تجنّبًا للتأخير.


class urllib.request.UnknownHandler
=== الصنف <code>urllib.request.UnknownHandler</code> ===
صنف شامل لمعالجة العناوين المجهولة.
صنف شامل لمعالجة العناوين المجهولة.


class urllib.request.HTTPErrorProcessor
=== الصنف <code>urllib.request.HTTPErrorProcessor</code> ===
 
صنف لمعالجة استجابات HTTP الخاصة بالأخطاء.
صنف لمعالجة استجابات HTTP الخاصة بالأخطاء.


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


 
=== <code>Request.full_url</code> ===
Request.full_url
 
عنوان URL الأصلي والممرّر إلى الدالة البانية.
عنوان URL الأصلي والممرّر إلى الدالة البانية.


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


Request.type
=== <code>Request.type</code> ===
 
مخطط URI.
مخطط URI.


Request.host
=== <code>Request.host</code> ===
 
صلاحية URI، عادة تكون مضيفًا، ولكن يمكن أن يتضمّن منفذًا مفصولًا عن المضيف بنقطتين رأسيتين.
صلاحية URI، عادة تكون مضيفًا، ولكن يمكن أن يتضمّن منفذًا مفصولًا عن المضيف بنقطتين رأسيتين.


Request.origin_req_host
=== <code>Request.origin_req_host</code> ===
المضيف الأصلي للطلب، من دون المنفذ.
المضيف الأصلي للطلب، من دون المنفذ.


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


Request.data
=== <code>Request.data</code> ===
متن الطلب، أو القيمة None في حال عدم تعيينه.
متن الطلب، أو القيمة None في حال عدم تعيينه.


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


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


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


ملاحظات:  
'''ملاحظات:'''
* هذه الخاصية جديدة في الإصدار 3.3 من بايثون.
* هذه الخاصية جديدة في الإصدار 3.3 من بايثون.
* في الإصدار 3.4 من بايثون أصبح بالإمكان تعيين قيمة افتراضية في الصنف الفرعي، أما في الإصدارات السابقة فقد كانت الطريقة الوحيدة هي تعيين القيمة في الدالة البانية.
* في الإصدار 3.4 من بايثون أصبح بالإمكان تعيين قيمة افتراضية في الصنف الفرعي، أما في الإصدارات السابقة فقد كانت الطريقة الوحيدة هي تعيين القيمة في الدالة البانية.
سطر 138: سطر 124:
== كائنات OpenerDirector ==
== كائنات OpenerDirector ==


تمتلك كائنات OpenerDirector التوابع التالية:
تمتلك كائنات <code>OpenerDirector</code> التوابع التالية:




== كائنات BaseHandler ==
== كائنات BaseHandler ==


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


== كائنات HTTPRedirectHandler ==
== كائنات HTTPRedirectHandler ==
سطر 149: سطر 135:
== كائنات HTTPCookieProcessor ==
== كائنات HTTPCookieProcessor ==


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


== الواجهة القديمة  ==
== الواجهة القديمة  ==
الدوال والأصناف التالية منقولة من الوحدة urllib في الإصدار الثاني من بايثون (بخلاف الوحدة urllib2)، وقد تصبح مهملة في المستقبل:
الدوال والأصناف التالية منقولة من الوحدة <code>urllib</code> في الإصدار الثاني من بايثون (وليست من الوحدة urllib2)، وقد تصبح مهملة في المستقبل:


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


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

مراجعة 18:10، 25 يناير 2019

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

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

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

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

urllib.request.urlopen()‎

urllib.request.install_opener()‎

urllib.request.build_opener()‎

urllib.request.pathname2url()‎

urllib.request.url2pathname()‎

urllib.request.getproxies()‎

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

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

الصنف urllib.request.Request

الصنف 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).

A realm of None is considered a catch-all realm, which is searched if no other realm fits.

الصنف urllib.request.HTTPPasswordMgrWithPriorAuth

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

الصنف urllib.request.AbstractBasicAuthHandler

الصنف urllib.request.HTTPBasicAuthHandler

الصنف urllib.request.ProxyBasicAuthHandler

الصنف urllib.request.AbstractDigestAuthHandler

الصنف urllib.request.HTTPDigestAuthHandler

الصنف urllib.request.ProxyDigestAuthHandler

الصنف urllib.request.HTTPHandler

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

الصنف urllib.request.HTTPSHandler

الصنف urllib.request.FileHandler

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

الصنف urllib.request.DataHandler

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

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

الصنف urllib.request.FTPHandler

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

الصنف urllib.request.CacheFTPHandler

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

الصنف urllib.request.UnknownHandler

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

الصنف urllib.request.HTTPErrorProcessor

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

كائنات 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 من بايثون أصبح بالإمكان تعيين قيمة افتراضية في الصنف الفرعي، أما في الإصدارات السابقة فقد كانت الطريقة الوحيدة هي تعيين القيمة في الدالة البانية.

كائنات OpenerDirector

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


كائنات BaseHandler

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

كائنات HTTPRedirectHandler

كائنات HTTPCookieProcessor

كائنات ProxyHandler

كائنات HTTPPasswordMgr

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

كائنات HTTPPasswordMgrWithPriorAuth

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

كائنات AbstractBasicAuthHandler

كائنات HTTPBasicAuthHandler

كائنات ProxyBasicAuthHandler

كائنات AbstractDigestAuthHandler

كائنات HTTPDigestAuthHandler

كائنات ProxyDigestAuthHandler

كائنات HTTPHandler

كائنات HTTPSHandler

كائنات FileHandler

كائنات DataHandler

كائنات FTPHandler

كائنات CacheFTPHandler

كائنات UnknownHandler

كائنات HTTPErrorProcessor

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

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

محدّدات وحدة 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=27296»