الدالة urllib.parse.urlencode() في بايثون
تحوّل الدالة كائن ربط mapping object أو تسلسلًا من صفوف ذات عنصرين، والتي قد تحتوي على كائنات str أو bytes إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII.
إن كان المطلوب استخدام السلسلة النصية الناتجة كبيانات لعمليات من نوع POST في الدالة urlopen() فيجب ترميز قيمة المعامل إلى بايتات، وإلّا فإنّ النتيجة ستكون الحصول على الاستثناء TypeError.
البنية العامة
urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)
المعاملات
query
إن استخدم تسلسل من صفوف ذات عنصرين كقيمة للمعامل query، فيجب أن يكون العنصر الأوّل في كل صفّ مفتاحًا، والعنصر الثاني قيمة له. يمكن أن يكون العنصر الثاني تسلسلًا أيضًا، وفي هذه الحالة إن كانت قيمة المعامل الاختياري doseq هي True، فإنّ أزواج قيمة=مفتاح مفصولة بعلامة '&' ستنشأ لكل عنصر في هذا التسلسل. يكون ترتيب المعاملات في السلسلة النصية المرمّزة مطابقًا لترتيبها لصفوف المعاملات في التسلسل.
quote_via
تتألّف السلسلة النصية الناتجة من أزواج مفتاح=قيمة مفصولة عن بعضها البعض بالحرف '&'، ويحاط كلّ من القيمة والمفتاح بعلامات الاقتباس بواسطة اسم الدالة الممرّر في المعامل quote_via. تستخدم الدالة quote_plus() افتراضيًا لاقتباس القيم، وهذا يعني أنّ المسافات البيضاء ستُحوّل إلى الحرف '+'، والحرف '/' سيُحوّل إلى %2F، وهذا مطابق للمعيار المتّبع في الطلبات من نوع نوع GET وهو (application/x-www-form-urlencoded).
يمكن كذلك تمرير القيمة quote للمعامل quote_via وهذا يعني استخدام الدالة quote() وبذلك تحوّل المسافات البيضاء إلى %20 ولا يرمّز الحرف '/'.
استخدم القيمة quote وحدّد القيم في المعامل safe للتحكّم بصورة أكبر بالحروف المرمّزة.
errors و encoding و safe
تمرّر المعاملات safe و encoding و errors إلى المعامل quote_via (يمرّر المعاملان encoding و errors عندما تكون سلسلة الاستعلام من نوع str فقط).
يمكن استخدام الدالتين parse_qs() و parse_qsl() لتحليل سلاسل الاستعلام النصية وتحويلها إلى بنى البيانات في بايثون.
راجع الأمثلة في توثيق الوحدة urllib.request للاطلاع على طريقة استخدام التابع urlencode لإنشاء سلاسل استعلام نصية لعنوان URL أو لبيانات تابعة لطلب من نوع POST.
ملاحظات:
- يدعم المعامل query كائنات
bytesوstrفي الإصدار 3.2 وما بعده من بايثون. - أضيف المعامل
quote_viaفي الإصدار 3.5 من بايثون.
أمثلة
يبين المثال التالي طريقة عمل الدالة:
>>> import urllib.parse
>>> args = {'page': 1, 'category': 'Mobile'}
>>> encoded_args = urllib.parse.urlencode(args)
>>> print(encoded_args)
page=1&category=Mobile
انظر أيضًا
- الدالة
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.