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

المراجعة الحالية بتاريخ 20:39، 25 يناير 2019

تفتح الدالة عنوان 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

مصادر

صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.

@@ سطر 8: / سطر 8: @@
 urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)
 </syntaxhighlight>
-‎
-== المعاملات ==
-‎
-=== url ===
-سلسلة نصية أو كائن Request، ويتضمّن عنوان URL الذي ستفتحه الدالة.
-=== data ===
+== ‎المعاملات ==
-يجب أن تكون قيمة هذا المعامل كائنًا يحدّد البيانات الإضافية التي ستُرسل إلى المخدّم، أو يأخذ المعامل القيمة None إن لم تكن هناك حاجة لمثل هذه البيانات. (راجع كائنات Request للمزيد من التفاصيل).
-تستخدم وحدة urllib.request البروتوكول HTTP/1.1 وتُدرج الترويسة <code>Connection:close</code> في طلبات HTTP الخاصّة بها.
+=== ‎<code>url</code> ===
+سلسلة نصية أو كائن <code>[[Python/Request|Request]]</code>، ويتضمّن عنوان URL الذي ستفتحه الدالة.
-=== timeout ===
+=== <code>data</code> ===
+يجب أن تكون قيمة هذا المعامل كائنًا يحدّد البيانات الإضافية التي ستُرسل إلى المخدّم، أو يأخذ المعامل القيمة <code>None</code> إن لم تكن هناك حاجة لمثل هذه البيانات. (راجع كائنات <code>[[Python/Request|Request]]</code> للمزيد من التفاصيل).
+تستخدم وحدة <code>urllib.request</code> البروتوكول HTTP/1.1 وتُدرج الترويسة <code>Connection:close</code> في طلبات HTTP الخاصّة بها.
+=== <code>timeout</code> ===
 معامل اختياري يحدّد الفترة الزمنية (بالثواني) لإيقاف عمليات مثل محاولة الاتصال. في حال عدم تحديد قيمة لهذه المعامل فإنّ الدالة ستستخدم القيمة العامّة الافتراضية. يعمل هذا المعامل مع الاتصالات الخاضعة للبروتكولات HTTP و HTTPS و FTP.
-=== context ===
+=== <code>context</code> ===
-في حال تعيين قيمة لهذا المعامل فيجب أن تكون نسخة من الصنف ssl.SSLContext تصف خيارات SSL المتعددة. راجع HTTPSConnection للمزيد من التفاصيل.
+في حال تعيين قيمة لهذا المعامل فيجب أن تكون نسخة من الصنف <code>ssl.SSLContext</code> تصف خيارات SSL المتعددة. راجع <code>[[Python/HTTPSConnection|HTTPSConnection]]</code> للمزيد من التفاصيل.
-=== cafile و capath ===
+=== <code>cafile</code> و <code>capath</code> ===
-معاملان اختياريان يحدّدان مجموعة من شهادات CA الموثوقة لطلبات HTTPS. يجب أن يشير المعامل cafile إلى ملفّ واحد يتضمّن حزمة من شهادات CA، أما المعامل capath فيجب أن يشير إلى مجلّد يتضمّن ملفّات شهادات مقطّعة hashed. يمكن الحصول على المزيد من المعلومات في توثيق التابع ssl.SSLContext.load_verify_locations()‎.
+معاملان اختياريان يحدّدان مجموعة من شهادات CA الموثوقة لطلبات HTTPS. يجب أن يشير المعامل <code>cafile</code> إلى ملفّ واحد يتضمّن حزمة من شهادات CA، أما المعامل <code>capath</code> فيجب أن يشير إلى مجلّد يتضمّن ملفّات شهادات مقطّعة hashed. يمكن الحصول على المزيد من المعلومات في توثيق التابع <code>ssl.SSLContext.load_verify_locations()‎</code>.
-=== cadefault ===
+=== <code>cadefault</code> ===
 تتجاهل الدالة هذا المعامل.
 == القيمة المعادة ==
 تعيد هذه الدالة دائمًا كائنًا يمكن أن يعمل كمدير للسياق context manager ويمتلك توابع مثل:
-* geturl()‎: يعيد هذا التابع عنوان URL للمصدر المعاد، ويُستخدم عادة لتحديد ما إذا كان عملية إعادة التوجيه صحيحة.
+* <code>geturl()‎</code>: يعيد هذا التابع عنوان URL للمصدر المعاد، ويُستخدم عادة لتحديد ما إذا كان عملية إعادة التوجيه صحيحة.
-* info()‎: يعيد التابع المعلومات الوصفية meta-information الخاصة بالصفحة مثل الترويسات، ويعيدها على هيئة نسخة من الصنف email.message_from_string()‎ (راجع الدليل السريع لترويسات HTTP).
+* <code>info()‎</code>: يعيد التابع المعلومات الوصفية meta-information الخاصة بالصفحة مثل الترويسات، ويعيدها على هيئة نسخة من الصنف <code>email.message_from_string()‎</code> (راجع الدليل السريع لترويسات HTTP).
-* getcode()‎: يعيد التابع شيفرة حالة HTTP للاستجابة الحالية.
+* <code>getcode()‎</code>: يعيد التابع شيفرة حالة HTTP للاستجابة الحالية.
-تعيد هذه الدالة لعناوين HTTP و HTTPS كائن http.client.HTTPResponse معدّل قليلًا، وبالإضافة إلى التوابع الثلاثة المذكورة في أعلاه، تحتوي خاصية msg على نفس المعلومات الموجودة في الخاصية reaseon، (عبارة reason التي يعيدها المخدّم) عوضًا عن ترويسات الاستجابة وكما هو موصوف في توثيق الصنف HTTPResponse.
+تعيد هذه الدالة لعناوين HTTP و HTTPS كائن <code>http.client.HTTPResponse</code> معدّل قليلًا، وبالإضافة إلى التوابع الثلاثة المذكورة في أعلاه، تحتوي خاصية <code>msg</code> على نفس المعلومات الموجودة في الخاصية <code>reason</code>، (عبارة reason التي يعيدها المخدّم) عوضًا عن ترويسات الاستجابة وكما هو موصوف في توثيق الصنف <code>[[Python/HTTPResponse|HTTPResponse]]</code>.
-أما بالنسبة لعناوين FTP والملفات والبيانات والطلبات التي تعالجها الأصناف القديمة URLopener و FancyURLopener، فإنّ الدالة تعيد كائن urllib.response.addinfourl.
+أما بالنسبة لعناوين FTP والملفات والبيانات والطلبات التي تعالجها الأصناف القديمة <code>URLopener</code> و <code>FancyURLopener</code>، فإنّ الدالة تعيد كائن <code>urllib.response.addinfourl</code>.
-تطلق الدالة الاستثناء URLError عند حدوث أيّ خطأ في البروتوكولات.
+تطلق الدالة الاستثناء <code>URLError</code> عند حدوث أيّ خطأ في البروتوكولات.
-يجدر التنبيه إلى أنّ الدالة قد تعيد القيمة None إن لم يُعالج الطلب من قبل أي معالج (مع أنّ الصنف العام OpenerDirector والمثبّت تلقائيًا يستخدم صنف المعالجة UnknownHandler لضمان عدم حدوث ذلك).
+يجدر التنبيه إلى أنّ الدالة قد تعيد القيمة <code>None</code> إن لم يُعالج الطلب من قبل أي معالج (مع أنّ الصنف العام <code>OpenerDirector</code> والمثبّت تلقائيًا يستخدم صنف المعالجة <code>UnknownHandler</code> لضمان عدم حدوث ذلك).
-إضافة إلى ما سبق، فإنّ اكتشفت الدالة وجود إعدادات وسيط proxy (كأن تعيّن قيمة لأحد متغيرات البيئة ‎*_proxy مثل http_proxy)، فإنّ الصنف ProxyHandler سيثبّت تلقائيًا وسيحرص على معالجة الطلب عبر الوسيط.
+إضافة إلى ما سبق، فإنّ اكتشفت الدالة وجود إعدادات وسيط <code>proxy</code> (كأن تعيّن قيمة لأحد متغيرات البيئة <code>‎*_proxy</code> مثل <code>http_proxy</code>)، فإنّ الصنف <code>ProxyHandler</code> سيثبّت تلقائيًا وسيحرص على معالجة الطلب عبر الوسيط.
-يوفّر الإصدار 2.6 وما قبله من بايثون الدالة urllib.urlopen وقد ألغيت هذه الدالة في الإصدارات الأحدث، والدالة urllib.request.urlopen()‎ فتقابل الدالة urllib2.urlopen القديمة. يمكن إجراء عمليات معالجة الوسيط Proxy handling  -والتي كانت تُجرى سابقًا بتمرير قاموس إلى الدالة urllib.urlopen- باستخدام كائنات ProxyHandler.
+يوفّر الإصدار 2.6 وما قبله من بايثون الدالة <code>urllib.urlopen</code> وقد ألغيت هذه الدالة في الإصدارات الأحدث، والدالة <code>urllib.request.urlopen()</code>‎ فتقابل الدالة <code>urllib2.urlopen</code> القديمة. يمكن إجراء عمليات معالجة الوسيط Proxy handling  -والتي كانت تُجرى سابقًا بتمرير [[Python/dict|قاموس]] إلى الدالة <code>urllib.urlopen</code>- باستخدام كائنات <code>ProxyHandler</code>.
 == ملاحظات ==
-* أضيف المعاملان cafile و capath في الإصدار 3.2 من بايثون.
+* أضيف المعاملان <code>cafile</code> و <code>capath</code> في الإصدار 3.2 من بايثون.
-* أصبح الإصدار 3.2 من بايثون يدعم مضيفات HTTPS الافتراضية إن كان ذلك ممكنًا (أي إن أخذت الخاصية ssl.HAS_SNI قيمة صحيحة).
+* أصبح الإصدار 3.2 من بايثون يدعم مضيفات HTTPS الافتراضية إن كان ذلك ممكنًا (أي إن أخذت الخاصية <code>ssl.HAS_SNI</code> قيمة صحيحة).
-* يمكن استخدام كائن قابل للتكرار iterable كقيمة للمعامل data في الإصدار 3.2 من بايثون.
+* يمكن استخدام كائن قابل للتكرار iterable كقيمة للمعامل <code>data</code> في الإصدار 3.2 من بايثون.
-* أضيف المعامل cadefault في الإصدار 3.3 من بايثون.
+* أضيف المعامل <code>cadefault</code> في الإصدار 3.3 من بايثون.
-* أضيف المعامل context في الإصدار 3.4.3 من بايثون.
+* أضيف المعامل <code>context</code> في الإصدار 3.4.3 من بايثون.
-* أصبحت المعاملات cafile و capath و cadefault مهملة لصالح المعامل context. يرجى مراجعة توثيق التابع ssl.SSLContext.load_cert_chain()‎، أو السماح للدالة ssl.create_default_context()‎ باختيار شهادة CA الموثوقة بالنيابة عنك.
+* أصبحت المعاملات <code>cafile</code> و <code>capath</code> و <code>cadefault</code> مهملة لصالح المعامل <code>context</code>. راجع توثيق التابع <code>ssl.SSLContext.load_cert_chain()‎</code>، أو اسمح للدالة <code>ssl.create_default_context()‎</code> باختيار شهادة CA الموثوقة نيابةً عنك.
 == أمثلة ==
-يبين المثال التالي طريقة عمل التابع:
+يجلب المثال التالي الصفحة الرئيسية لموقع [https://www.python.org/ python.org] ويعرض أول 300 بايت منها.
 <syntaxhighlight lang="python3">
+>>> 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 '
+</syntaxhighlight>لاحظ أنّ الدالة <code>urlopen</code> تعيد [[PHP/array sorting|كائن بايتات]]، وذلك عدم وجود طريقة يمكن للدالة من خلالها أن تحدد ترميز تدفق البيانات الذي تستقلبه من مخدّم HTTP. وبصورة عامّة، يمكن فكّ ترميز كائن البياتات المعاد وتحويله إلى سلسلة نصية بعد تحديد أو تخمين الترميز الملائم.
+تسرد صفحة W3C هذه: https://www.w3.org/International/O-charset الطرق المختلفة التي يمكن لملفات ‎(X)HTML أو XML أن تمتلك معلومات ترميز خاصّة.
+يستخدم موقع [https://www.python.org/ python.org] الترميز utf-8 كما هو موضّح في وسم meta، ويستخدم المثال التالي الترميز عينه لفك ترميز كائن البايتات:<syntaxhighlight lang="python3">
+>>> 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
+</syntaxhighlight>يمكن الحصول على النتيجة ذاتها دون اللجوء إلى طريقة مدير السياق context manager:<syntaxhighlight lang="python3">
+>>> 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
 </syntaxhighlight>
-== انظر أيضًا ==
 == مصادر ==

المراجعة الحالية بتاريخ 20:39، 25 يناير 2019

البنية العامة

‎المعاملات

‎url

data

timeout

context

cafile و capath

cadefault