عرض مصدر Python/urllib/parse/urlencode

<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.parse.urlencode()‎‎</code> في بايثون}}</noinclude>

تحوّل الدالة كائن ربط mapping object أو تسلسلًا من [[Python/tuples|صفوف]] ذات عنصرين، والتي قد تحتوي على كائنات <code>[[Python/str|str]]</code> أو <code>[[Python/bytes|bytes]]</code> إلى سلسلة نصية مرمّزة بالنسبة المئوية ضمن الترميز ASCII.

إن كان المطلوب استخدام السلسلة النصية الناتجة كبيانات لعمليات من نوع POST في الدالة <code>[[Python/urllib/request/urlopen|urlopen()]]</code>‎ فيجب ترميز قيمة المعامل إلى بايتات، وإلّا فإنّ النتيجة ستكون الحصول على الاستثناء TypeError.


== البنية العامة ==

<syntaxhighlight lang="python3">
urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)
</syntaxhighlight>

== ‎المعاملات ==

=== <code>query</code> ===
إن استخدم تسلسل من صفوف ذات عنصرين كقيمة للمعامل <code>query</code>، فيجب أن يكون العنصر الأوّل في كل صفّ مفتاحًا، والعنصر الثاني قيمة له. يمكن أن يكون العنصر الثاني تسلسلًا أيضًا، وفي هذه الحالة إن كانت قيمة المعامل الاختياري <code>doseq</code> هي <code>True</code>، فإنّ أزواج قيمة=مفتاح مفصولة بعلامة '&' ستنشأ لكل عنصر في هذا التسلسل. يكون ترتيب المعاملات في السلسلة النصية المرمّزة مطابقًا لترتيبها لصفوف المعاملات في التسلسل.

=== <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> للتحكّم بصورة أكبر بالحروف المرمّزة.

=== <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> فقط).

يمكن استخدام الدالتين <code>[[Python/urllib/parse/parse qs|parse_qs()]]</code>‎ و <code>[[Python/urllib/parse/parse qsl|parse_qsl()]]</code>‎ لتحليل سلاسل الاستعلام النصية وتحويلها إلى بنى البيانات في بايثون.

راجع الأمثلة في توثيق الوحدة <code>[[Python/urllib/request|urllib.request]]</code> للاطلاع على طريقة استخدام التابع <code>urlencode</code> لإنشاء سلاسل استعلام نصية لعنوان URL أو لبيانات تابعة لطلب من نوع POST.

'''ملاحظات:'''
* يدعم المعامل query كائنات <code>bytes</code> و <code>str</code> في الإصدار 3.2 وما بعده من بايثون.
* أضيف المعامل <code>quote_via</code> في الإصدار 3.5 من بايثون.
== أمثلة ==

يبين المثال التالي طريقة عمل الدالة:

<syntaxhighlight lang="python3">
>>> import urllib.parse
>>> args = {'page': 1, 'category': 'Mobile'}
>>> encoded_args = urllib.parse.urlencode(args)
>>> print(encoded_args)
page=1&category=Mobile

</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[Python/urllib/parse/quote|urllib.parse.quote()]]</code>‎: تستبدل الدالة الحروف الخاصة في السلسلة النصية المعطاة باستخدام علامة التهريب <code>‎%xx</code>.
* الدالة <code>[[Python/urllib/parse/quote plus|urllib.parse.quote_plus()]]</code>‎: هذه الدالة مشابهة للدالة <code>[[Python/urllib/parse/quote|quote()]]</code>‎ ولكنّها تستبدل المسافات الفارغة بعلامات <code>+</code>.
* الدالة <code>[[Python/urllib/parse/quote from bytes|urllib.parse.quote_from_bytes()]]‎</code>: تشبه هذه الدالةُ الدالةَ [[Python/urllib/parse/quote|<code>quote()</code>‎]] ولكنّها تستقبل كائنات <code>[[Python/byte-bytearray-operations|bytes]]</code> عوضًا عن كائنات <nowiki/>[[Python/str|str]]، ولا تؤدي عمليات الترميز من السلاسل النصية إلى البايتات. 
* الدالة <code>[[Python/urllib/parse/unquote|urllib.parse.unquote()]]‎</code>:  تحوّل الدالة الحروف المهرّبة بالصيغة <code>‎%xx</code> إلى الحروف الأصلية المكافئة لها.
* الدالة <nowiki/>[[Python/urllib/parse/unquote plus|<code>urllib.parse.unquote_plus()</code>‎]]: هذه الدالة مشابهة للدالة <code>[[Python/urllib/parse/unquote|unquote()]]</code>‎ ولكنّها تستبدل علامات <code>+</code> بالمسافات البيضاء، وهذا هو المطلوب عند إلغاء الاقتباس من قيم نماذج HTML.
* الدالة <code>[[Python/urllib/parse/unquote to bytes|urllib.parse.unquote_to_bytes()]]</code>‎: تحول الدالة الحروف المهرّبة بالصيغة ‎<code>%xx</code> إلى القيمة الثمانية المفردة المقابلة لها، وتعيد كائن <code>[[Python/bytes|bytes]]</code>.

== مصادر ==
* [https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode صفحة Parse URLs into components في توثيق بايثون الرسمي.]

[[تصنيف:Python]]
[[تصنيف:Python Modules]]