الدالة 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
.