|
|
| سطر 1: |
سطر 1: |
| <noinclude>{{DISPLAYTITLE:الدالة <code>urllib.request.urlopen()</code> في بايثون}}</noinclude> | | <noinclude>{{DISPLAYTITLE:الدالة <code>urllib.request.install_opener()</code> في بايثون}}</noinclude> |
| | |
| تفتح الدالة عنوان URL المعطى.
| |
|
| |
|
| | ثبّت الدالة نسخة من الصنف OpenerDirector كفاتح opener افتراضي عام. لن تحتاج إلى تثبيت الفاتح إلّا إن كنت ترغب في أن تستخدم الدالة urlopen ذلك الفاتح بالتحديد، وإلاّ فبالإمكان استدعاء التابع OpenerDirector.open() عوضًا عن urlopen(). لن تتحقّق الشيفرة من وجود صنف OpenerDirector حقيقي، ويمكن لأيّ صنفٍ يمتلك الواجهة الملائمة أن يؤدي العمل نفسه. |
| == البنية العامة == | | == البنية العامة == |
|
| |
|
| <syntaxhighlight lang="python3"> | | <syntaxhighlight lang="python3"> |
| urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None) | | urllib.request.install_opener(opener) |
| </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 الموثوقة نيابةً عنك.
| |
| == أمثلة ==
| |
| | |
| يجلب المثال التالي الصفحة الرئيسية لموقع 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>لاحظ أنّ الدالة urlopen تعيد كائن بايتات، وذلك عدم وجود طريقة يمكن للدالة من خلالها أن تحدد ترميز تدفق البيانات الذي تستقلبه من مخدّم HTTP. وبصورة عامّة، يمكن فكّ ترميز كائن البياتات المعاد وتحويله إلى سلسلة نصية بعد تحديد أو تخمين الترميز الملائم.
| |
| | |
| تسرد صفحة W3C هذه: <nowiki>https://www.w3.org/International/O-charset</nowiki> الطرق المختلفة التي يمكن لملفات (X)HTML أو XML أن تمتلك معلومات ترميز خاصّة.
| |
| | |
| يستخدم موقع 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.urlopen صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.] | | * [https://docs.python.org/3/library/urllib.request.html#urllib.request.install_opener صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.] |
|
| |
|
| [[تصنيف:Python]] | | [[تصنيف:Python]] |
| [[تصنيف:Python Modules]] | | [[تصنيف:Python Modules]] |
ثبّت الدالة نسخة من الصنف OpenerDirector كفاتح opener افتراضي عام. لن تحتاج إلى تثبيت الفاتح إلّا إن كنت ترغب في أن تستخدم الدالة urlopen ذلك الفاتح بالتحديد، وإلاّ فبالإمكان استدعاء التابع OpenerDirector.open() عوضًا عن urlopen(). لن تتحقّق الشيفرة من وجود صنف OpenerDirector حقيقي، ويمكن لأيّ صنفٍ يمتلك الواجهة الملائمة أن يؤدي العمل نفسه.
البنية العامة
urllib.request.install_opener(opener)
مصادر