الفرق بين المراجعتين ل"Python/urllib/parse/urlencode"
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.parse.urlencode()</code> في بايثون}}</noinclude> تحوّل الدالة كائن ربط mapping objec...') |
|||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.parse.urlencode()</code> في بايثون}}</noinclude> | <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>query</code> === | |
| + | إن استخدم تسلسل من صفوف ذات عنصرين كقيمة للمعامل <code>query</code>، فيجب أن يكون العنصر الأوّل في كل صفّ مفتاحًا، والعنصر الثاني قيمة له. يمكن أن يكون العنصر الثاني تسلسلًا أيضًا، وفي هذه الحالة إن كانت قيمة المعامل الاختياري doseq هي True، فإنّ أزواج قيمة=مفتاح مفصولة بعلامة '&' ستنشأ لكل عنصر في هذا التسلسل. يكون ترتيب المعاملات في السلسلة النصية المرمّزة مطابقًا لترتيبها لصفوف المعاملات في التسلسل. | ||
| − | + | === <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>. | ||
| − | + | يمكن كذلك تمرير القيمة <code>quote</code> للمعامل <code>quote_via</code> وهذا يعني استخدام الدالة <code>[[Python/urllib/parse/quote|quote()]]</code> وبذلك تحوّل المسافات البيضاء إلى <code>%20</code> ولا يرمّز الحرف <code>'/'</code>. | |
| − | + | استخدم القيمة <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 من بايثون. |
== أمثلة == | == أمثلة == | ||
مراجعة 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.