Python/urllib/parse

تعرّف هذه الوحدة واجهة معيارية لتقسيم سلاسل محدّد موقع الموارد المحدّد Uniform Resource Locator (‏URL اختصارًا) إلى مكوّنات (نظام العنونة addressing scheme، موقع الشبكة network location، المسار path ... الخ)، ولدمج هذه المكونات مرّة أخرى في سلسلة URL، ولتحويل "URL نسبي" إلى URL مطلق بالاعتماد على "URL أساسي".

صمّمت هذه الوحدة لتطابق معايير RFC للإنترنت الخاصّة بالمحدّدات النسبية لمواقع الموارد المحدّدة Relative Uniform Resource Locators. وتدعم الوحدة الأنواع التالية من مخطّطات URL:

file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

تعرّف وحدة urllib.parse عددًا من الدوال التي تندرج ضمن صنفين رئيسيين هما: تحليل عناوين URL وإحاطة مكوّنات عناوين URL بعلامات الاقتباس URL quoting.

تحليل عناوين URL

تركّز الدوال الخاصّة بتحليل عناوين URL على تقسيم السلسلة النصية للعنوان إلى مكونات، أو دمج مكوّنات URL إلى سلسلة URL نصية.

الدالة urllib.parse.urlparse()‎

تحلّل الدالة عنوان URL إلى ستّة مكونات تمثّل البنية الرئيسية لعنوان URL.

الدالة urllib.parse.parse_qs()‎

تحلل الدالة سلسلة الاستعلام المعطاة كسلسلة من المعاملات.

الدالة urllib.parse.parse_qsl()‎

تحلل الدالة سلسلة الاستعلام النصية المعطاة كسلسلة معاملات نصية string argument

الدالة urllib.parse.urlunparse()‎

تبني الدالة عنوان URL من صفّ يشبه الصفّ المعاد من الدالة urlparse()‎.

الدالة urllib.parse.urlsplit()‎

هذه الدالة مشابهة للدالة urlparse()‎ ولكنّها لا تقسم المعاملات من عنوان URL.

الدالة urllib.parse.urlunsplit()‎

تدمج الدالة عناصر الصفّ الذي يشبه ما تعيده الدالة urlsplit()‎ في عنوان URL كامل على هيئة سلسلة نصية.

الدالة urllib.parse.urljoin()‎

تبني الدالة عنوان URL كاملًا (مطلقًا) عن طريق دمج عنوان URL الأساسي base URL المعطى، مع عنوان URL آخر.

الدالة urllib.parse.urldefrag()‎

إن تضمّن عنوان URL المعطى محدّد قطعة fragment identifier فإنّ الدالة تعيد النسخة المعدلة من العنوان المعطى دون محدّد قطعة، وتفصل محدّد القطعة في سلسلة نصية منفصلة.

تحليل البايتات المرمّزة بالترميز ASCII

صمّمت دوال تحليل عناوين URL في المقام الأول للعمل على السلاسل النصية الحرفية فقط، ولكن من المفيد عمليًا القدرة على معالجة عناوين URL المحاطة بعلامات اقتباس والمرمّزة كتسلسل بايتات بترميز ASCII. وعلى هذا الأساس فإنّ جميع دوال تحليل عناوين URLفي هذه الدالة تعمل على كائنات bytes و bytearray إضافة إلى كائنات str.

وفي حال تمرير بيانات نصية فإنّ النتيجة ستتضمّن كذلك بيانات نصية فقط، أما إن مُرِّرت بيانات من نوع bytes أو bytearray فإنّ النتيجة ستكون بيانات من نوع bytes فقط.

يؤدي مزج البيانات النصية مع الباياتات أو مصفوفات البايتات في استدعاء واحد للدالة إلى إطلاق الخطأ TypeError، أما محاول تمرير بايتات خارج ترميز ASCII فستؤدي إلى إطلاق الاستثناء UnicodeDecodeError.

ولتسهيل عملية تحويل الكائنات المعادة بين النوعين str و bytes، تزوّد جميع القيم المعادة من تحليل عناوين URL بتابع encode()‎ (عندما تتضمّن النتيجة المعادة بيانات نصية) أو التابع decode()‎ (عندما تتضمّن النتيجة المعادة بيانات بايتات).

يطابق توقيع signature هذه التوابع توقيع نظيراتها في كائنات str و bytes (باستثناء أنّ الترميز الافتراضي هو 'ascii' وليس 'utf-8'). وينتج كل تابع القيمة المقابلة للنوع، فالتابع encode()‎ ينتج بيانات من نوع bytes والتابع decode()‎ ينتج بيانات من نوع str.

يجب على التطبيقات التي تحتاج إلى العمل على عناوين URL غير مرمّزة بصورة صحيحة أو التي تحتوي على حروف خارج الترميز ASCII أن تجري عملية فك الترميز البايتات وتحويلها إلى محارف قبل استدعاء تابع تحليل عناوين URL.

ينطبق السلوك الموصوف في هذا القسم على دوال تحليل عناوين URL فقط، أما الدول المسؤولة عن إحاطة عناوين URL بعلامات الاقتباس quoting functions فتستخدم قواعدها الخاصّة لإنتاج واستخدام تسلسلات البايتات وبالطريقة الموضّحة في توثيق كلّ دالة من هذه الدوال.

ملاحظة: تستقبل دوال تحليل عناوين URL تسلسلات البايتات المرمّزة بالترميز ASCII في الإصدار 3.2 وما بعده.

نتائج التحليل المنظّمة

تعيد الدوال urlparse()‎ و urlsplit()‎ و urldefrag()‎ كائنات تكون متفرّعة من نوع الصفوف tuple، وتضيف هذه الأصناف الفرعية الخصائص الموضّحة في التوثيق الخاص بتلك الدوال إضافة إلى توابع الترميز وفك الترميز التي مرّ ذكرها في القسم السابق، إلى جانب التابع الإضافي التالي:

التابع urllib.parse.SplitResult.geturl()‎

يعيد التابع نسخة من عنوان URL الأصلي بعد إعادة دمجها.

تقدّم الأصناف التالية الوسائل اللازمة للتعامل مع نتائج التحليل المنظّمة عند العمل مع كائنات str:

الصنف urllib.parse.DefragResult(url, fragment)‎

الصنف المحدّد concrete class المسؤول عن النتائج المعادة من الدالة urldefrag()‎ والتي تتضمّن بيانات من نوع str.

الصنف urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)‎

الصنف المحدّد concrete class والمسؤول عن النتائج المعادة من الدالة urlparse()‎ والتي تتضمّن بيانات من نوع str.

الصنف urllib.parse.SplitResult(scheme, netloc, path, query, fragment)‎

الصنف المحدّد concrete class والمسؤول عن النتائج المعادة من الدالة urlsplit()‎ والتي تتضمّن بيانات من نوع str.

تقدّم الأصناف التالية الأدوات اللازمة للتعامل مع النتائج التحليل المنظّمة عند العمل مع كائنات bytes أو bytearray:

الصنف urllib.parse.DefragResultBytes(url, fragment)‎

الصنف المحدّد concrete class والمسؤول عن النتائج المعادة من الدالة urldefrag()‎ والتي تتضمّن بيانات من نوع bytes.

الصنف urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)‎

الصنف المحدّد concrete class والمسؤول عن النتائج المعادة من الدالة urlparse()‎ والتي تتضمّن بيانات من نوع bytes.

الصنف urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)‎

الصنف المحدّد concrete class والمسؤول عن النتائج المعادة من الدالة urlsplit()‎ والتي تتضمّن بيانات من نوع bytes.

اقتباس عناوين URL

تركّز دوال اقتباس عناوين URL على جعل بيانات البرامج آمنة للاستخدام كمكوّنات في عناوين URL وذلك بإحاطة الحروف الخاصة والحروف غير الداخلة في ترميز ASCII بعلامات اقتباس. وتدعم هذه الدوال كذلك عكس هذه العمليات لإعادة إنتاج البيانات الأصلية من محتويات مكوّنات عنوان URL وذلك إن لم تؤد دوال تحليل عناوين URL هذه المهمّة.

الدالة urllib.parse.quote()‎

تستبدل الدالة الحروف الخاصة في السلسلة النصية المعطاة باستخدام علامة التهريب ‎%xx.

الدالة urllib.parse.quote_plus()‎

هذه الدالة مشابهة للدالة quote()‎ ولكنّها تستبدل المسافات الفارغة بعلامات +.

الدالة urllib.parse.quote_from_bytes()‎

تشبه هذه الدالة الدالة quote()‎ ولكنّها تستقبل كائنات bytes عوضًا عن كائنات str، ولا تؤدي عمليات الترميز من السلاسل النصية إلى البايتات.

الدالة urllib.parse.unquote()‎

تحوّل الدالة الحروف المهرّبة بالصيغة ‎%xx إلى الحروف الأصلية المكافئة لها.

الدالة urllib.parse.unquote_plus()‎

هذه الدالة مشابهة للدالة unquote()‎ ولكنّها تستبدل علامات + بالمسافات البيضاء، وهذا هو المطلوب عند إلغاء الاقتباس من قيم نماذج HTML.

الدالة urllib.parse.unquote_to_bytes()‎

تحول الدالة الحروف المهرّبة بالصيغة ‎%xx إلى القيمة الثمانية المفردة المقابلة لها، وتعيد كائن bytes.

الدالة urllib.parse.urlencode()‎

تحوّل الدالة كائن ربط mapping object أو تسلسلًا من صفوف ذات عنصرين، والتي قد تحتوي على كائنات str أو bytes إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII.

انظر أيضًا

• الوحدة urllib.request: تقدّم وحدة urllib.request عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL‏ (HTTP في الغالب) لاستخدامها في عمليات مختلفة مثل الاستيثاق البسيط وإعادة التوجيه والتعامل مع الكعكات cookies وغيرها.

مصادر

• صفحة Parse URLs into components في توثيق بايثون الرسمي.