الدالة 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 على نفس المعلومات الموجودة في الخاصية reason، (عبارة 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 الموثوقة نيابةً عنك.
أمثلة
يجلب المثال التالي الصفحة الرئيسية لموقع python.org ويعرض أول 300 بايت منها.
>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
... print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '
لاحظ أنّ الدالة urlopen تعيد كائن بايتات، وذلك عدم وجود طريقة يمكن للدالة من خلالها أن تحدد ترميز تدفق البيانات الذي تستقلبه من مخدّم HTTP. وبصورة عامّة، يمكن فكّ ترميز كائن البياتات المعاد وتحويله إلى سلسلة نصية بعد تحديد أو تخمين الترميز الملائم.
تسرد صفحة W3C هذه: https://www.w3.org/International/O-charset الطرق المختلفة التي يمكن لملفات (X)HTML أو XML أن تمتلك معلومات ترميز خاصّة.
يستخدم موقع python.org الترميز utf-8 كما هو موضّح في وسم meta، ويستخدم المثال التالي الترميز عينه لفك ترميز كائن البايتات:
>>> with urllib.request.urlopen('http://www.python.org/') as f:
... print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm
يمكن الحصول على النتيجة ذاتها دون اللجوء إلى طريقة مدير السياق context manager:
>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm