الفرق بين المراجعتين ل"Python/urllib/request/urlopen"

من موسوعة حسوب
< Python‏ | urllib‏ | request
اذهب إلى التنقل اذهب إلى البحث
 
(مراجعتان متوسطتان بواسطة نفس المستخدم غير معروضتين)
سطر 1: سطر 1:
−
<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.request.install_opener()‎‎</code> في بايثون}}</noinclude>
+
<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.request.urlopen()‎‎</code> في بايثون}}</noinclude>
 +
 
 +
تفتح الدالة عنوان URL المعطى.
  
−
ثبّت الدالة نسخة من الصنف OpenerDirector كفاتح opener افتراضي عام. لن تحتاج إلى تثبيت الفاتح إلّا إن كنت ترغب في أن تستخدم الدالة urlopen ذلك الفاتح بالتحديد، وإلاّ فبالإمكان استدعاء التابع OpenerDirector.open()‎ عوضًا عن urlopen()‎. لن تتحقّق الشيفرة من وجود صنف OpenerDirector حقيقي، ويمكن لأيّ صنفٍ يمتلك الواجهة الملائمة أن يؤدي العمل نفسه.
 
 
== البنية العامة ==
 
== البنية العامة ==
  
 
<syntaxhighlight lang="python3">
 
<syntaxhighlight lang="python3">
−
urllib.request.install_opener(opener)
+
urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)
 +
</syntaxhighlight>
 +
 
 +
== ‎المعاملات ==
 +
 
 +
=== ‎<code>url</code> ===
 +
سلسلة نصية أو كائن <code>[[Python/Request|Request]]</code>، ويتضمّن عنوان URL الذي ستفتحه الدالة.
 +
 
 +
=== <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.
 +
 
 +
=== <code>context</code> ===
 +
في حال تعيين قيمة لهذا المعامل فيجب أن تكون نسخة من الصنف <code>ssl.SSLContext</code> تصف خيارات SSL المتعددة. راجع <code>[[Python/HTTPSConnection|HTTPSConnection]]</code> للمزيد من التفاصيل.
 +
 
 +
=== <code>cafile</code> و <code>capath</code> ===
 +
معاملان اختياريان يحدّدان مجموعة من شهادات CA الموثوقة لطلبات HTTPS. يجب أن يشير المعامل <code>cafile</code> إلى ملفّ واحد يتضمّن حزمة من شهادات CA، أما المعامل <code>capath</code> فيجب أن يشير إلى مجلّد يتضمّن ملفّات شهادات مقطّعة hashed. يمكن الحصول على المزيد من المعلومات في توثيق التابع <code>ssl.SSLContext.load_verify_locations()‎</code>.
 +
 
 +
=== <code>cadefault</code> ===
 +
تتجاهل الدالة هذا المعامل.
 +
 
 +
== القيمة المعادة ==
 +
تعيد هذه الدالة دائمًا كائنًا يمكن أن يعمل كمدير للسياق context manager ويمتلك توابع مثل:
 +
* <code>geturl()‎</code>: يعيد هذا التابع عنوان URL للمصدر المعاد، ويُستخدم عادة لتحديد ما إذا كان عملية إعادة التوجيه صحيحة.
 +
* <code>info()‎</code>: يعيد التابع المعلومات الوصفية meta-information الخاصة بالصفحة مثل الترويسات، ويعيدها على هيئة نسخة من الصنف <code>email.message_from_string()‎</code> (راجع الدليل السريع لترويسات HTTP).
 +
* <code>getcode()‎</code>: يعيد التابع شيفرة حالة HTTP للاستجابة الحالية.
 +
 
 +
تعيد هذه الدالة لعناوين HTTP و HTTPS كائن <code>http.client.HTTPResponse</code> معدّل قليلًا، وبالإضافة إلى التوابع الثلاثة المذكورة في أعلاه، تحتوي خاصية <code>msg</code> على نفس المعلومات الموجودة في الخاصية <code>reason</code>، (عبارة reason التي يعيدها المخدّم) عوضًا عن ترويسات الاستجابة وكما هو موصوف في توثيق الصنف <code>[[Python/HTTPResponse|HTTPResponse]]</code>.
 +
 
 +
أما بالنسبة لعناوين FTP والملفات والبيانات والطلبات التي تعالجها الأصناف القديمة <code>URLopener</code> و <code>FancyURLopener</code>، فإنّ الدالة تعيد كائن <code>urllib.response.addinfourl</code>.
 +
 
 +
تطلق الدالة الاستثناء <code>URLError</code> عند حدوث أيّ خطأ في البروتوكولات.
 +
 
 +
يجدر التنبيه إلى أنّ الدالة قد تعيد القيمة <code>None</code> إن لم يُعالج الطلب من قبل أي معالج (مع أنّ الصنف العام <code>OpenerDirector</code> والمثبّت تلقائيًا يستخدم صنف المعالجة <code>UnknownHandler</code> لضمان عدم حدوث ذلك).
 +
 
 +
إضافة إلى ما سبق، فإنّ اكتشفت الدالة وجود إعدادات وسيط <code>proxy</code> (كأن تعيّن قيمة لأحد متغيرات البيئة <code>‎*_proxy</code> مثل <code>http_proxy</code>)، فإنّ الصنف <code>ProxyHandler</code> سيثبّت تلقائيًا وسيحرص على معالجة الطلب عبر الوسيط.
 +
 
 +
يوفّر الإصدار 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>.
 +
 
 +
== ملاحظات ==
 +
* أضيف المعاملان <code>cafile</code> و <code>capath</code> في الإصدار 3.2 من بايثون.
 +
* أصبح الإصدار 3.2 من بايثون يدعم مضيفات HTTPS الافتراضية إن كان ذلك ممكنًا (أي إن أخذت الخاصية <code>ssl.HAS_SNI</code> قيمة صحيحة).
 +
* يمكن استخدام كائن قابل للتكرار iterable كقيمة للمعامل <code>data</code> في الإصدار 3.2 من بايثون.
 +
* أضيف المعامل <code>cadefault</code> في الإصدار 3.3 من بايثون.
 +
* أضيف المعامل <code>context</code> في الإصدار 3.4.3 من بايثون.
 +
* أصبحت المعاملات <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>
 
</syntaxhighlight>
  
 
== مصادر ==
 
== مصادر ==
−
* [https://docs.python.org/3/library/urllib.request.html#urllib.request.install_opener صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.]
+
* [https://docs.python.org/3/library/urllib.request.html#urllib.request.urlopen صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.]
  
 
[[تصنيف:Python]]
 
[[تصنيف:Python]]
 
[[تصنيف:Python Modules]]
 
[[تصنيف:Python Modules]]

المراجعة الحالية بتاريخ 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

مصادر

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