الدالة urllib.request.urlopen() في بايثون
تفتح الدالة عنوان URL المعطى.
البنية العامة
urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)
المعاملات
url
سلسلة نصية أو كائن Request، ويتضمّن عنوان URL الذي ستفتحه الدالة.
data
يجب أن تكون قيمة هذا المعامل كائنًا يحدّد البيانات الإضافية التي ستُرسل إلى المخدّم، أو يأخذ المعامل القيمة None إن لم تكن هناك حاجة لمثل هذه البيانات. (راجع كائنات Request للمزيد من التفاصيل).
تستخدم وحدة urllib.request البروتوكول HTTP/1.1 وتُدرج الترويسة Connection:close في طلبات HTTP الخاصّة بها.
timeout
معامل اختياري يحدّد الفترة الزمنية (بالثواني) لإيقاف عمليات مثل محاولة الاتصال. في حال عدم تحديد قيمة لهذه المعامل فإنّ الدالة ستستخدم القيمة العامّة الافتراضية. يعمل هذا المعامل مع الاتصالات الخاضعة للبروتكولات HTTP و HTTPS و FTP.
context
في حال تعيين قيمة لهذا المعامل فيجب أن تكون نسخة من الصنف ssl.SSLContext تصف خيارات SSL المتعددة. راجع HTTPSConnection للمزيد من التفاصيل.
cafile و capath
معاملان اختياريان يحدّدان مجموعة من شهادات CA الموثوقة لطلبات HTTPS. يجب أن يشير المعامل cafile إلى ملفّ واحد يتضمّن حزمة من شهادات CA، أما المعامل capath فيجب أن يشير إلى مجلّد يتضمّن ملفّات شهادات مقطّعة hashed. يمكن الحصول على المزيد من المعلومات في توثيق التابع ssl.SSLContext.load_verify_locations().
cadefault
تتجاهل الدالة هذا المعامل.
القيمة المعادة
تعيد هذه الدالة دائمًا كائنًا يمكن أن يعمل كمدير للسياق context manager ويمتلك توابع مثل:
- geturl(): يعيد هذا التابع عنوان URL للمصدر المعاد، ويُستخدم عادة لتحديد ما إذا كان عملية إعادة التوجيه صحيحة.
- info(): يعيد التابع المعلومات الوصفية meta-information الخاصة بالصفحة مثل الترويسات، ويعيدها على هيئة نسخة من الصنف email.message_from_string() (راجع الدليل السريع لترويسات HTTP).
- getcode(): يعيد التابع شيفرة حالة HTTP للاستجابة الحالية.
تعيد هذه الدالة لعناوين HTTP و HTTPS كائن http.client.HTTPResponse معدّل قليلًا، وبالإضافة إلى التوابع الثلاثة المذكورة في أعلاه، تحتوي خاصية msg على نفس المعلومات الموجودة في الخاصية reaseon، (عبارة reason التي يعيدها المخدّم) عوضًا عن ترويسات الاستجابة وكما هو موصوف في توثيق الصنف HTTPResponse.
أما بالنسبة لعناوين FTP والملفات والبيانات والطلبات التي تعالجها الأصناف القديمة URLopener و FancyURLopener، فإنّ الدالة تعيد كائن urllib.response.addinfourl.
تطلق الدالة الاستثناء URLError عند حدوث أيّ خطأ في البروتوكولات.
يجدر التنبيه إلى أنّ الدالة قد تعيد القيمة None إن لم يُعالج الطلب من قبل أي معالج (مع أنّ الصنف العام OpenerDirector والمثبّت تلقائيًا يستخدم صنف المعالجة UnknownHandler لضمان عدم حدوث ذلك).
إضافة إلى ما سبق، فإنّ اكتشفت الدالة وجود إعدادات وسيط proxy (كأن تعيّن قيمة لأحد متغيرات البيئة *_proxy مثل http_proxy)، فإنّ الصنف ProxyHandler سيثبّت تلقائيًا وسيحرص على معالجة الطلب عبر الوسيط.
يوفّر الإصدار 2.6 وما قبله من بايثون الدالة urllib.urlopen وقد ألغيت هذه الدالة في الإصدارات الأحدث، والدالة urllib.request.urlopen() فتقابل الدالة urllib2.urlopen القديمة. يمكن إجراء عمليات معالجة الوسيط Proxy handling -والتي كانت تُجرى سابقًا بتمرير قاموس إلى الدالة urllib.urlopen- باستخدام كائنات ProxyHandler.
ملاحظات
- أضيف المعاملان cafile و capath في الإصدار 3.2 من بايثون.
- أصبح الإصدار 3.2 من بايثون يدعم مضيفات HTTPS الافتراضية إن كان ذلك ممكنًا (أي إن أخذت الخاصية ssl.HAS_SNI قيمة صحيحة).
- يمكن استخدام كائن قابل للتكرار iterable كقيمة للمعامل data في الإصدار 3.2 من بايثون.
- أضيف المعامل cadefault في الإصدار 3.3 من بايثون.
- أضيف المعامل context في الإصدار 3.4.3 من بايثون.
- أصبحت المعاملات cafile و capath و cadefault مهملة لصالح المعامل context. يرجى مراجعة توثيق التابع ssl.SSLContext.load_cert_chain()، أو السماح للدالة ssl.create_default_context() باختيار شهادة CA الموثوقة بالنيابة عنك.
أمثلة
يبين المثال التالي طريقة عمل التابع: