الفرق بين المراجعتين لصفحة: «Python/urllib/parse/urlencode»

مراجعة 21:19، 5 فبراير 2019

تحوّل الدالة كائن ربط 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.

مصادر

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

@@ سطر 1: / سطر 1: @@
 <noinclude>{{DISPLAYTITLE:الدالة <code>urllib.parse.urlencode()‎‎</code> في بايثون}}</noinclude>
-تحوّل الدالة كائن ربط mapping object أو تسلسلًا من صفوف ذات عنصرين، والتي قد تحتوي على كائنات str أو bytes إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII.
+تحوّل الدالة كائن ربط mapping object أو تسلسلًا من [[Python/tuples|صفوف]] ذات عنصرين، والتي قد تحتوي على كائنات <code>[[Python/str|str]]</code> أو <code>[[Python/bytes|bytes]]</code> إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII.
-إن كان المطلوب استخدام السلسلة النصية الناتجة كبيانات لعمليات من نوع POST في الدالة urlopen()‎ فيجب ترميز قيمة المعامل إلى بايتات، وإلّا فإنّ النتيجة ستكون الحصول على الاستثناء TypeError.
+إن كان المطلوب استخدام السلسلة النصية الناتجة كبيانات لعمليات من نوع POST في الدالة <code>[[Python/urllib/request/urlopen|urlopen()]]</code>‎ فيجب ترميز قيمة المعامل إلى بايتات، وإلّا فإنّ النتيجة ستكون الحصول على الاستثناء TypeError.
@@ سطر 13: / سطر 13: @@
 == ‎المعاملات ==
-=== <code>quote_via</code> ===
-يجب أن يكون [[Python/str|سلسلة نصية]] أو كائن [[Python/bytes|bytes]].
-تتألّف السلسلة النصية الناتجة من أزواج مفتاح=قيمة مفصولة عن بعضها البعض بالحرف '&'، ويحاط كلّ من القيمة والمفتاح بعلامات الاقتباس بواسطة اسم الدالة الممرّر في المعامل quote_via. تستخدم الدالة quote_plus()‎ افتراضيًا لاقتباس القيم، وهذا يعني أنّ المسافات البيضاء ستُحوّل إلى الحرف '+'، والحرف '/' سيُحوّل إلى ‎%2F، وهذا مطابق للمعيار المتّبع في الطلبات من نوع GET (‏application/x-www-form-urlencoded)‎.
+=== <code>query</code> ===
+إن استخدم تسلسل من صفوف ذات عنصرين كقيمة للمعامل <code>query</code>، فيجب أن يكون العنصر الأوّل في كل صفّ مفتاحًا، والعنصر الثاني قيمة له. يمكن أن يكون العنصر الثاني تسلسلًا أيضًا، وفي هذه الحالة إن كانت قيمة المعامل الاختياري doseq هي True، فإنّ أزواج قيمة=مفتاح مفصولة بعلامة '&' ستنشأ لكل عنصر في هذا التسلسل. يكون ترتيب المعاملات في السلسلة النصية المرمّزة مطابقًا لترتيبها لصفوف المعاملات في التسلسل.
-يمكن كذلك تمرير القيمة quote للمعامل quote_via وهذا يعني استخدام الدالة quote()‎ وبذلك تحوّل المسافات البيضاء إلى ‎%20 ولا يرمّز الحرف '/'.
+=== <code>quote_via</code> ===
+تتألّف السلسلة النصية الناتجة من أزواج مفتاح=قيمة مفصولة عن بعضها البعض بالحرف <code>'&'</code>، ويحاط كلّ من القيمة والمفتاح بعلامات الاقتباس بواسطة اسم الدالة الممرّر في المعامل <code>quote_via</code>. تستخدم الدالة <code>[[Python/urllib/parse/quote plus|quote_plus()‎]]</code> افتراضيًا لاقتباس القيم، وهذا يعني أنّ المسافات البيضاء ستُحوّل إلى الحرف <code>'+'</code>، والحرف <code>'/'</code> سيُحوّل إلى <code>‎%2F</code>، وهذا مطابق للمعيار المتّبع في الطلبات من نوع نوع GET وهو ‎<code>(application/x-www-form-urlencoded)‎</code>.
-استخدم القيمة quote وحدّد القيم في المعامل safe للتحكّم بصورة أكبر بالحروف المرمّزة.
+يمكن كذلك تمرير القيمة <code>quote</code> للمعامل <code>quote_via</code> وهذا يعني استخدام الدالة <code>[[Python/urllib/parse/quote|quote()]]</code>‎ وبذلك تحوّل المسافات البيضاء إلى <code>‎%20</code> ولا يرمّز الحرف <code>'/'</code>.
-إن استخدم تسلسل من صفوف ذات عنصرين كقيمة للمعامل query، فيجب أن يكون العنصر الأوّل في كل صفّ مفتاحًا، والعنصر الثاني قيمة له. يمكن أن يكون العنصر الثاني تسلسلًا أيضًا، وفي هذه الحالة إن كانت قيمة المعامل الاختياري doseq هي True، فإنّ أزواج قيمة=مفتاح مفصولة بعلامة '&' ستنشأ لكل عنصر في هذا التسلسل. يكون ترتيب المعاملات في السلسلة النصية المرمّزة مطابقًا لترتيبها لصفوف المعاملات في التسلسل.
+استخدم القيمة <code>quote</code> وحدّد القيم في المعامل <code>safe</code> للتحكّم بصورة أكبر بالحروف المرمّزة.
-تمرّر المعاملات safe و encoding و errors إلى المعامل quote_via (يمرّر المعاملان encoding و errors عندما تكون سلسلة الاستعلام من نوع str فقط).
+=== <code>errors</code> و <code>encoding</code> و <code>safe</code> ===
+تمرّر المعاملات <code>safe</code> و <code>encoding</code> و <code>errors</code> إلى المعامل <code>quote_via</code> (يمرّر المعاملان <code>encoding</code> و <code>errors</code> عندما تكون سلسلة الاستعلام من نوع <code>[[Python/str|str]]</code> فقط).
-يمكن استخدام الدالتين parse_qs()‎ و parse_qsl()‎ لتحليل سلاسل الاستعلام النصية وتحويلها إلى بنى البيانات في بايثون.
+يمكن استخدام الدالتين <code>[[Python/urllib/parse/parse qs|parse_qs()]]</code>‎ و <code>[[Python/urllib/parse/parse qsl|parse_qsl()]]</code>‎ لتحليل سلاسل الاستعلام النصية وتحويلها إلى بنى البيانات في بايثون.
-راجع الأمثلة في توثيق الوحدة urllib.request للاطلاع على طريقة استخدام التابع urlencode لإنشاء سلاسل استعلام نصية لعنوان URL أو لبيانات تابعة لطلب من نوع POST.
+راجع الأمثلة في توثيق الوحدة <code>[[Python/urllib/request|urllib.request]]</code> للاطلاع على طريقة استخدام التابع <code>urlencode</code> لإنشاء سلاسل استعلام نصية لعنوان URL أو لبيانات تابعة لطلب من نوع POST.
-ملاحظات:
+'''ملاحظات:'''
-* يدعم المعامل query كائنات bytes و str في الإصدار 3.2 وما بعده من بايثون.
+* يدعم المعامل query كائنات <code>bytes</code> و <code>str</code> في الإصدار 3.2 وما بعده من بايثون.
-* أضيف المعامل quote_via في الإصدار 3.5 من بايثون.
+* أضيف المعامل <code>quote_via</code> في الإصدار 3.5 من بايثون.
 == أمثلة ==