الفرق بين المراجعتين ل"Python/urllib/parse"
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الوحدة <code>urllib.parser()</code> في بايثون}}</noinclude> تعرّف هذه الوحدة واجهة معيارية لتق...') |
|||
| سطر 2: | سطر 2: | ||
تعرّف هذه الوحدة واجهة معيارية لتقسيم سلاسل محدّد موقع الموارد المحدّد Uniform Resource Locator (URL اختصارًا) إلى مكوّنات (نظام العنونة addressing scheme، موقع الشبكة network location، المسار path ... الخ)، ولدمج هذه المكونات مرّة أخرى في سلسلة URL، ولتحويل "URL نسبي" إلى URL مطلق بالاعتماد على "URL أساسي". | تعرّف هذه الوحدة واجهة معيارية لتقسيم سلاسل محدّد موقع الموارد المحدّد Uniform Resource Locator (URL اختصارًا) إلى مكوّنات (نظام العنونة addressing scheme، موقع الشبكة network location، المسار path ... الخ)، ولدمج هذه المكونات مرّة أخرى في سلسلة URL، ولتحويل "URL نسبي" إلى URL مطلق بالاعتماد على "URL أساسي". | ||
| − | صمّمت هذه الوحدة لتطابق معايير RFC للإنترنت الخاصّة بالمحدّدات النسبية لمواقع الموارد المحدّدة. وتدعم الوحدة الأنواع التالية من مخطّطات 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. | + | <code>file</code>, <code>ftp</code>, <code>gopher</code>, <code>hdl</code>, <code>http</code>, <code>https</code>, <code>imap</code>, <code>mailto</code>, <code>mms</code>, <code>news</code>, <code>nntp</code>, <code>prospero</code>, <code>rsync</code>, <code>rtsp</code>, <code>rtspu</code>, <code>sftp</code>, <code>shttp</code>, <code>sip</code>, <code>sips</code>, <code>snews</code>, <code>svn</code>, <code>svn+ssh</code>, <code>telnet</code>, <code>wais</code>, <code>ws</code>, <code>wss</code>. |
| − | تعرّف وحدة urllib.parse عددًا من الدوال التي تندرج ضمن صنفين رئيسيين هما: تحليل عناوين URL وإحاطة مكوّنات عناوين URL بعلامات الاقتباس URL quoting. | + | تعرّف وحدة <code>urllib.parse</code> عددًا من الدوال التي تندرج ضمن صنفين رئيسيين هما: تحليل عناوين URL وإحاطة مكوّنات عناوين URL بعلامات الاقتباس URL quoting. |
== تحليل عناوين URL == | == تحليل عناوين URL == | ||
| سطر 12: | سطر 12: | ||
تركّز الدوال الخاصّة بتحليل عناوين URL على تقسيم السلسلة النصية للعنوان إلى مكونات، أو دمج مكوّنات URL إلى سلسلة URL نصية. | تركّز الدوال الخاصّة بتحليل عناوين URL على تقسيم السلسلة النصية للعنوان إلى مكونات، أو دمج مكوّنات URL إلى سلسلة URL نصية. | ||
| − | === الدالة urllib.parse.urlparse() === | + | === الدالة <code>urllib.parse.urlparse()</code> === |
تحلّل الدالة عنوان URL إلى ستّة مكونات تمثّل البنية الرئيسية لعنوان URL. | تحلّل الدالة عنوان URL إلى ستّة مكونات تمثّل البنية الرئيسية لعنوان URL. | ||
| − | === الدالة urllib.parse.parse_qs() === | + | === الدالة <code>urllib.parse.parse_qs()</code> === |
تحلل الدالة سلسلة الاستعلام المعطاة كسلسلة من المعاملات. | تحلل الدالة سلسلة الاستعلام المعطاة كسلسلة من المعاملات. | ||
| − | === الدالة urllib.parse.parse_qsl() === | + | === الدالة <code>urllib.parse.parse_qsl()</code> === |
تحلل الدالة سلسلة الاستعلام النصية المعطاة كسلسلة معاملات نصية string argument | تحلل الدالة سلسلة الاستعلام النصية المعطاة كسلسلة معاملات نصية string argument | ||
| − | === الدالة urllib.parse.urlunparse() === | + | === الدالة <code>urllib.parse.urlunparse()</code> === |
| − | تبني الدالة عنوان URL من صفّ يشبه الصفّ المعاد من الدالة urlparse(). | + | تبني الدالة عنوان URL من صفّ يشبه الصفّ المعاد من الدالة <code>urlparse()</code>. |
| − | === الدالة urllib.parse.urlsplit() === | + | === الدالة <code>urllib.parse.urlsplit()</code> === |
| − | هذه الدالة مشابهة للدالة urlparse() ولكنّها لا تقسم المعاملات من عنوان URL. | + | هذه الدالة مشابهة للدالة <code>urlparse()</code> ولكنّها لا تقسم المعاملات من عنوان URL. |
| − | === الدالة urllib.parse.urlunsplit() === | + | === الدالة <code>urllib.parse.urlunsplit()</code> === |
| − | تدمج الدالة عناصر الصفّ الذي يشبه ما تعيده الدالة urlsplit() في عنوان URL كامل على هيئة سلسلة نصية. | + | تدمج الدالة عناصر الصفّ الذي يشبه ما تعيده الدالة <code>urlsplit()</code> في عنوان URL كامل على هيئة سلسلة نصية. |
| − | === الدالة urllib.parse.urljoin() === | + | === الدالة <code>urllib.parse.urljoin()</code> === |
تبني الدالة عنوان URL كاملًا (مطلقًا) عن طريق دمج عنوان URL الأساسي base URL المعطى، مع عنوان URL آخر. | تبني الدالة عنوان URL كاملًا (مطلقًا) عن طريق دمج عنوان URL الأساسي base URL المعطى، مع عنوان URL آخر. | ||
| − | === الدالة urllib.parse.urldefrag() === | + | === الدالة <code>urllib.parse.urldefrag()</code> === |
إن تضمّن عنوان URL المعطى محدّد قطعة fragment identifier فإنّ الدالة تعيد النسخة المعدلة من العنوان المعطى دون محدّد قطعة، وتفصل محدّد القطعة في سلسلة نصية منفصلة. | إن تضمّن عنوان URL المعطى محدّد قطعة fragment identifier فإنّ الدالة تعيد النسخة المعدلة من العنوان المعطى دون محدّد قطعة، وتفصل محدّد القطعة في سلسلة نصية منفصلة. | ||
== تحليل البايتات المرمّزة بالترميز ASCII == | == تحليل البايتات المرمّزة بالترميز ASCII == | ||
| − | صمّمت دوال تحليل عناوين URL في المقام الأول للعمل على السلاسل النصية الحرفية فقط، ولكن من المفيد عمليًا القدرة على معالجة عناوين URL المحاطة بعلامات اقتباس والمرمّزة كتسلسل بايتات بترميز ASCII. وعلى هذا الأساس فإنّ جميع دوال تحليل عناوين URLفي هذه الدالة تعمل على كائنات bytes و bytearray إضافة إلى كائنات str. | + | صمّمت دوال تحليل عناوين URL في المقام الأول للعمل على السلاسل النصية الحرفية فقط، ولكن من المفيد عمليًا القدرة على معالجة عناوين URL المحاطة بعلامات اقتباس والمرمّزة كتسلسل بايتات بترميز ASCII. وعلى هذا الأساس فإنّ جميع دوال تحليل عناوين URLفي هذه الدالة تعمل على كائنات <code>[[Python/bytes|bytes]]</code> و [[Python/bytearray|<code>bytearray</code>]] إضافة إلى كائنات <code>[[Python/str|str]]</code>. |
| − | وفي حال تمرير بيانات نصية فإنّ النتيجة ستتضمّن كذلك بيانات نصية فقط، أما إن مُرِّرت بيانات من نوع bytes أو bytearray فإنّ النتيجة ستكون بيانات من نوع bytes فقط. | + | وفي حال تمرير بيانات نصية فإنّ النتيجة ستتضمّن كذلك بيانات نصية فقط، أما إن مُرِّرت بيانات من نوع <code>[[Python/bytes|bytes]]</code> أو [[Python/bytearray|<code>bytearray</code>]] فإنّ النتيجة ستكون بيانات من نوع bytes فقط. |
| − | يؤدي مزج البيانات النصية مع الباياتات أو مصفوفات البايتات في استدعاء واحد للدالة إلى إطلاق الخطأ | + | يؤدي مزج البيانات النصية مع الباياتات أو مصفوفات البايتات في استدعاء واحد للدالة إلى إطلاق الخطأ <code>TypeError</code>، أما محاول تمرير بايتات خارج ترميز ASCII فستؤدي إلى إطلاق الاستثناء <code>UnicodeDecodeError</code>. |
| − | ولتسهيل عملية تحويل الكائنات المعادة بين النوعين str و | + | ولتسهيل عملية تحويل الكائنات المعادة بين النوعين <code>[[Python/str|str]]</code> و <code>[[Python/bytes|bytes]]</code>، تزوّد جميع القيم المعادة من تحليل عناوين URL بتابع <code>encode()</code> (عندما تتضمّن النتيجة المعادة بيانات نصية) أو التابع <code>decode()</code> (عندما تتضمّن النتيجة المعادة بيانات بايتات). |
| − | يطابق توقيع signature هذه التوابع توقيع نظيراتها في كائنات str و bytes (باستثناء أنّ الترميز الافتراضي هو 'ascii' وليس 'utf-8'). وينتج كل تابع القيمة المقابلة للنوع، فالتابع encode() ينتج بيانات من نوع bytes والتابع decode() ينتج بيانات من نوع str. | + | يطابق توقيع signature هذه التوابع توقيع نظيراتها في كائنات <code>[[Python/str|str]]</code> و <code>[[Python/bytes|bytes]]</code> (باستثناء أنّ الترميز الافتراضي هو 'ascii' وليس 'utf-8'). وينتج كل تابع القيمة المقابلة للنوع، فالتابع <code>encode()</code> ينتج بيانات من نوع <code>[[Python/bytes|bytes]]</code> والتابع decode() ينتج بيانات من نوع <code>[[Python/str|str]]</code>. |
يجب على التطبيقات التي تحتاج إلى العمل على عناوين URL غير مرمّزة بصورة صحيحة أو التي تحتوي على حروف خارج الترميز ASCII أن تجري عملية فك الترميز البايتات وتحويلها إلى محارف قبل استدعاء تابع تحليل عناوين URL. | يجب على التطبيقات التي تحتاج إلى العمل على عناوين URL غير مرمّزة بصورة صحيحة أو التي تحتوي على حروف خارج الترميز ASCII أن تجري عملية فك الترميز البايتات وتحويلها إلى محارف قبل استدعاء تابع تحليل عناوين URL. | ||
| سطر 51: | سطر 51: | ||
ينطبق السلوك الموصوف في هذا القسم على دوال تحليل عناوين URL فقط، أما الدول المسؤولة عن إحاطة عناوين URL بعلامات الاقتباس quoting functions فتستخدم قواعدها الخاصّة لإنتاج واستخدام تسلسلات البايتات وبالطريقة الموضّحة في توثيق كلّ دالة من هذه الدوال. | ينطبق السلوك الموصوف في هذا القسم على دوال تحليل عناوين URL فقط، أما الدول المسؤولة عن إحاطة عناوين URL بعلامات الاقتباس quoting functions فتستخدم قواعدها الخاصّة لإنتاج واستخدام تسلسلات البايتات وبالطريقة الموضّحة في توثيق كلّ دالة من هذه الدوال. | ||
| − | ملاحظة: | + | '''ملاحظة:''' تستقبل دوال تحليل عناوين URL تسلسلات البايتات المرمّزة بالترميز ASCII في الإصدار 3.2 وما بعده. |
| − | تستقبل دوال تحليل عناوين URL تسلسلات البايتات المرمّزة بالترميز ASCII في الإصدار 3.2 وما بعده. | ||
== نتائج التحليل المنظّمة == | == نتائج التحليل المنظّمة == | ||
| − | تعيد الدوال urlparse() و urlsplit() و urldefrag() كائنات تكون متفرّعة من نوع الصفوف | + | تعيد الدوال <code>urlparse()</code> و <code>urlsplit()</code> و <code>urldefrag()</code> كائنات تكون متفرّعة من نوع الصفوف <code>[[PHP/Array Sorting|tuple]]</code>، وتضيف هذه الأصناف الفرعية الخصائص الموضّحة في التوثيق الخاص بتلك الدوال إضافة إلى توابع الترميز وفك الترميز التي مرّ ذكرها في القسم السابق، إلى جانب التابع الإضافي التالي: |
| − | === التابع urllib.parse.SplitResult.geturl() === | + | === التابع <code>urllib.parse.SplitResult.geturl()</code> === |
يعيد التابع نسخة من عنوان URL الأصلي بعد إعادة دمجها. | يعيد التابع نسخة من عنوان URL الأصلي بعد إعادة دمجها. | ||
| − | === الصنف urllib.parse.DefragResult === | + | === الصنف <code>urllib.parse.DefragResult</code> === |
| − | الصنف المحدّد concrete class المسؤول عن النتائج المعادة من الدالة urldefrag() والتي تتضمّن بيانات من نوع str. | + | الصنف المحدّد concrete class المسؤول عن النتائج المعادة من الدالة urldefrag() والتي تتضمّن بيانات من نوع <code>[[Python/str|str]]</code>. |
| − | === الصنف urllib.parse.ParseResult === | + | === الصنف <code>urllib.parse.ParseResult</code> === |
| − | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlparse() والتي تتضمّن بيانات من نوع str. | + | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة <code>urlparse()</code> والتي تتضمّن بيانات من نوع <code>[[Python/str|str]]</code>. |
| − | === الصنف urllib.parse.SplitResult === | + | === الصنف <code>urllib.parse.SplitResult</code> === |
| − | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlsplit() والتي تتضمّن بيانات من نوع str. | + | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة <code>urlsplit()</code> والتي تتضمّن بيانات من نوع <code>[[Python/str|str]]</code>. |
| − | === الصنف urllib.parse.DefragResultBytes === | + | === الصنف <code>urllib.parse.DefragResultBytes</code> === |
| − | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urldefrag() والتي تتضمّن بيانات من نوع bytes. | + | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة <code>urldefrag()</code> والتي تتضمّن بيانات من نوع <code>[[Python/bytes|bytes]]</code>. |
| − | === الصنف urllib.parse.ParseResultBytes === | + | === الصنف <code>urllib.parse.ParseResultBytes</code> === |
| − | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlparse() والتي تتضمّن بيانات من نوع bytes. | + | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة <code>urlparse()</code> والتي تتضمّن بيانات من نوع <code>[[Python/bytes|bytes]]</code>. |
| − | === الصنف urllib.parse.SplitResultBytes === | + | === الصنف <code>urllib.parse.SplitResultBytes</code> === |
| − | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlsplit() والتي تتضمّن بيانات من نوع bytes. | + | الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة <code>urlsplit()</code> والتي تتضمّن بيانات من نوع <code>[[Python/bytes|bytes]]</code>. |
== اقتباس عناوين URL == | == اقتباس عناوين URL == | ||
| سطر 77: | سطر 76: | ||
تركّز دوال اقتباس عناوين URL على جعل بيانات البرامج آمنة للاستخدام كمكوّنات في عناوين URL وذلك بإحاطة الحروف الخاصة والحروف غير الداخلة في ترميز ASCI بعلامات اقتباس. وتدعم هذه الدوال كذلك عكس هذه العمليات لإعادة إنتاج البيانات الأصلية من محتويات مكوّنات عنوان URL وذلك إن لم تؤد دوال تحليل عناوين URL هذه المهمّة. | تركّز دوال اقتباس عناوين URL على جعل بيانات البرامج آمنة للاستخدام كمكوّنات في عناوين URL وذلك بإحاطة الحروف الخاصة والحروف غير الداخلة في ترميز ASCI بعلامات اقتباس. وتدعم هذه الدوال كذلك عكس هذه العمليات لإعادة إنتاج البيانات الأصلية من محتويات مكوّنات عنوان URL وذلك إن لم تؤد دوال تحليل عناوين URL هذه المهمّة. | ||
| − | === الدالة urllib.parse.quote() === | + | === الدالة <code>urllib.parse.quote()</code> === |
تستبدل الدالة الحروف الخاصة في السلسلة النصية المعطاة باستخدام علامة التهريب %xx. | تستبدل الدالة الحروف الخاصة في السلسلة النصية المعطاة باستخدام علامة التهريب %xx. | ||
| − | === الدالة urllib.parse.quote_plus() === | + | === الدالة <code>urllib.parse.quote_plus()</code> === |
| − | هذه الدالة مشابهة للدالة quote() ولكنّها تستبدل المسافات الفارغة بعلامات +. | + | هذه الدالة مشابهة للدالة <code>quote()</code> ولكنّها تستبدل المسافات الفارغة بعلامات <code>+</code>. |
| − | === الدالة urllib.parse.quote_from_bytes() === | + | === الدالة <code>urllib.parse.quote_from_bytes()</code> === |
| − | تشبه هذه الدالة الدالة quote() ولكنّها تستقبل كائنات bytes عوضًا عن كائنات | + | تشبه هذه الدالة الدالة quote() ولكنّها تستقبل كائنات bytes عوضًا عن كائنات [[Python/str|str]]، ولا تؤدي عمليات الترميز من السلاسل النصية إلى البايتات. |
| − | === الدالة urllib.parse.unquote() === | + | === الدالة <code>urllib.parse.unquote()</code> === |
| − | تحوّل الدالة الحروف المهرّبة بالصيغة %xx إلى الحروف الأصلية المكافئة لها. | + | تحوّل الدالة الحروف المهرّبة بالصيغة <code>%xx</code> إلى الحروف الأصلية المكافئة لها. |
| − | === الدالة urllib.parse.unquote_plus() === | + | === الدالة <code>urllib.parse.unquote_plus()</code> === |
| − | هذه الدالة مشابهة للدالة unquote() ولكنّها تستبدل علامات + بالمسافات البيضاء، وهذا هو المطلوب عند إلغاء الاقتباس من قيم نماذج HTML. | + | هذه الدالة مشابهة للدالة <code>unquote()</code> ولكنّها تستبدل علامات <code>+</code> بالمسافات البيضاء، وهذا هو المطلوب عند إلغاء الاقتباس من قيم نماذج HTML. |
| − | === الدالة urllib.parse.unquote_to_bytes() === | + | === الدالة <code>urllib.parse.unquote_to_bytes()</code> === |
| − | تحول الدالة الحروف المهرّبة بالصيغة %xx إلى القيمة الثمانية المفردة المقابلة لها، وتعيد كائن bytes. | + | تحول الدالة الحروف المهرّبة بالصيغة <code>%xx</code> إلى القيمة الثمانية المفردة المقابلة لها، وتعيد كائن <code>[[Python/bytes|bytes]]</code>. |
| − | === الدالة urllib.parse.urlencode() === | + | === الدالة <code>urllib.parse.urlencode()</code> === |
| − | تحوّل الدالة كائن ربط mapping object أو تسلسلًا من صفوف ذات عنصرين، والتي قد تحتوي على كائنات str أو bytes إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII. | + | تحوّل الدالة كائن ربط mapping object أو تسلسلًا من صفوف ذات عنصرين، والتي قد تحتوي على كائنات <code>[[Python/str/encode|str]]</code> أو <code>[[Python/bytes|bytes]]</code> إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII. |
| + | == انظر أيضًا == | ||
| + | * الوحدة <code>[[Python/urllib/request|urllib.request]]</code>: تقدّم وحدة <code>urllib.request</code> عددًا من الدوال والأصناف التي تساعد في فتح عناوين URL (HTTP في الغالب) لاستخدامها في عمليات مختلفة مثل الاستيثاق البسيط وإعادة التوجيه والتعامل مع الكعكات cookies وغيرها. | ||
| + | |||
| + | == مصادر == | ||
| + | * [https://docs.python.org/3/library/urllib.parse.html صفحة Parse URLs into components في توثيق بايثون الرسمي.] | ||
[[تصنيف:Python]] | [[تصنيف:Python]] | ||
[[تصنيف:Python Modules]] | [[تصنيف:Python Modules]] | ||
[[تصنيف:Python Methods]] | [[تصنيف:Python Methods]] | ||
مراجعة 19:36، 4 فبراير 2019
تعرّف هذه الوحدة واجهة معيارية لتقسيم سلاسل محدّد موقع الموارد المحدّد 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 الأصلي بعد إعادة دمجها.
الصنف urllib.parse.DefragResult
الصنف المحدّد concrete class المسؤول عن النتائج المعادة من الدالة urldefrag() والتي تتضمّن بيانات من نوع str.
الصنف urllib.parse.ParseResult
الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlparse() والتي تتضمّن بيانات من نوع str.
الصنف urllib.parse.SplitResult
الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlsplit() والتي تتضمّن بيانات من نوع str.
الصنف urllib.parse.DefragResultBytes
الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urldefrag() والتي تتضمّن بيانات من نوع bytes.
الصنف urllib.parse.ParseResultBytes
الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlparse() والتي تتضمّن بيانات من نوع bytes.
الصنف urllib.parse.SplitResultBytes
الصنف المحدّد concrete class المحدّد والمسؤول عن النتائج المعادة من الدالة urlsplit() والتي تتضمّن بيانات من نوع bytes.
اقتباس عناوين URL
تركّز دوال اقتباس عناوين URL على جعل بيانات البرامج آمنة للاستخدام كمكوّنات في عناوين URL وذلك بإحاطة الحروف الخاصة والحروف غير الداخلة في ترميز ASCI بعلامات اقتباس. وتدعم هذه الدوال كذلك عكس هذه العمليات لإعادة إنتاج البيانات الأصلية من محتويات مكوّنات عنوان 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 وغيرها.