الفرق بين المراجعتين لصفحة: «Python/string/Formatter/vformat»
لا ملخص تعديل |
|||
| (4 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
| سطر 1: | سطر 1: | ||
< | هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة (exposed) كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير [[Python/dict|قاموس]] معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغتين <code>*args</code> و <code>**kwargs</code>. | ||
==البنية العامة== | |||
<syntaxhighlight lang="python3"> | |||
vformat(format_string, args, kwargs) | vformat(format_string, args, kwargs) | ||
</syntaxhighlight> | |||
== طريقة عمل الدالة == | |||
تؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع التالية: | |||
=== <code>parse(format_string)</code> === | |||
يمرّ هذا التابع على سلسلة التنسيق النصية الممرّرة بواسطة المعامل <code>format_string</code> وتعيد [[Python/tuples|صفًّا]] على هيئة <code>(literal_text, field_name, format_spec, conversion)</code>. تستخدم الدالة <code>vformat()</code> هذا الصفّ لتقسيم السلسلة النصية إلى نصوص أو حقول استبدال. نظريًّا تمثّل القيم التي يتضمّنها الصفّ مجموعة من النصوص متبوعةً بحقل استبدال مفرد. وفي حال عدم وجود النصوص (قد يحدث هذا إذا كان هناك حقلا استبدال متتابعان) فإنّ <code>literal_text</code> سيكون سلسلة نصية فارغة. | |||
أما في حال غياب حقول الاستبدال فإنّ قيم كلّ من <code>field_name</code> و <code>format_spec</code> و <code>conversion</code> ستكون <code>None</code>. | |||
parse( | === <code>get_field(field_name, args, kwargs)</code> === | ||
يحوّل هذا التابع قيمة المعامل <code>field_name</code> الممرّر إليه والمعاد بواسطة التابع <code>parse()</code> إلى كائن جاهز للتنسيق. يعيد هذا التابع صفًّا بهيئة <code>(obj, used_key)</code>، ويأخذ بصورة افتراضية سلاسل نصية بالهيئة المعرّفة في PEP 3101، مثل <code>"0[name]"</code> أو <code>"label.title"</code>. يُمرّر المعاملان <code>args</code> و <code>kwargs</code> إلى الدالة <code>voformat()</code>. تشبه القيمة المعادة <code>used_key</code> المعامل <code>key</code> في التابع <code>get_value()</code>. | |||
=== <code>get_value(key, args, kwargs)</code> === | |||
يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل <code>key</code> أن يكون عددًا صحيحًا أو سلسلة نصية. | |||
فإن كان [[Python/int|عددًا صحيحًا]] فإنّه يمثل فهرس (موقع) المعامل الموقعي في المعامل <code>args</code>، وإن كان [[Python/str|سلسلة نصية]]، فإنّه يمثّل المعامل المسمّى في المعامل <code>kwargs</code>. | |||
يعيّن المعامل <code>args</code> في قائمة المعاملات الموقعية الخاصّة بالدالة <code>vformat()</code>، أما المعامل <code>kwargs</code> فيعيّن في قاموس المعاملات المفتاحية. | |||
أما بالنسبة لحقول الأسماء المركّبة، فإنّ هذه الدوال تستدعى لأجل المكوّن الأول فقط، ويمكن التعامل مع المكونات الأخرى عن طريق عمليات الفهرسة والخصائص الاعتيادية. | |||
فعلى سبيل المثال، عند استخدام تعبير الحقل <code>'0.name'</code> فإنّ التابع <code>get_value()</code> سيُستدعى مع معامل <code>key</code> يحمل القيمة <code>0</code>. أما الخاصية فسيُعثر عليها بعد انتهاء عمل التابع <code>get_value()</code> وذلك باستدعاء الدالة الداخلية <code>getattr()</code>. | |||
وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ <code>[[Python/built-in exceptions#IndexError|IndexError]]</code> أو <code>[[Python/built-in exceptions#KeyError|KeyError]]</code>. | |||
=== <code>check_unused_args(used_args, args, kwargs)</code> === | |||
يتحقّق هذا التابع من المعاملات غير المستخدمة، ومعاملات هذا التابع هي مجموعة تضم جميع مفاتيح المعاملات والتي أشير إليها في سلسلة التنسيق النصية (الأعداد الصحيحة في حالة المعاملات الموقعية، والسلاسل النصية في محالة المعاملات المسماة)، إضافة إلى إشارة إلى المعاملين <code>args</code> و <code>kwargs</code> الممرّان في الدالة <code>vformat()</code>. | |||
يفترض بالتابع <code>check_unused_args()</code> أن يطلق استثناء عند فشل عملية التحقق. | |||
=== <code>format_field(value, format_spec)</code> === | |||
يستدعي هذا التابع الدلة الداخلية <code>[[Python/format|format()]]</code>. ويقدّم الصنف <code>Formatter</code> هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه (override). | |||
=== <code>convert_field(value, conversion)</code> === | |||
يحوّل التابع القيمة المعادة من التابع <code>get_field()</code> باعتماد نوع التحويل المعطى (كما في الصفّ المعاد من التابع <code>parse()</code>). عمليات التحويل التي يدعمها هذا التابع هي <code>'s'</code> (str)، و <code>'r'</code> (repr)، و <code>'a'</code> (ascii). | |||
== انظر أيضًا == | |||
* [[Python/string/formatspec|مواصفات التنسيق في بايثون.]] | |||
* [[Python/string/format string syntax|صيغة سلاسل التنسيق النصية في بايثون.]] | |||
* [[Python/string/Formatter/format|التابع <code>Formatter.format()</code>]]: هذا هو تابع الواجهة البرمجية العام، ويأخذ سلسلة تنسيق نصية وعددًا من المعاملات الموقعية والمفتاحية. ويعدّ تابع تغليف wrapper يستدعي الدالة <code>vformat()</code>. | |||
* [[Python/format|الدالة <code>format()</code>]]: تُحوّل هذه الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده [[Python/string/formatspec|مواصفة التّنسيق المُعطاة]]. | |||
== مصادر == | |||
* [https://docs.python.org/3/library/string.html#string.Formatter.vformat قسم Custom String Formatting في صفحة Common String Operations في توثيق بايثون الرسمي.] | |||
<noinclude>{{DISPLAYTITLE:الدالة <code>Formatter.vformat()</code> في بايثون}}</noinclude> | |||
[[تصنيف:Python]] | |||
[[تصنيف:Python Method]] | |||
[[تصنيف:Python string]] | |||
[[تصنيف:Python Formatter]] | |||
المراجعة الحالية بتاريخ 05:32، 18 يونيو 2018
هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة (exposed) كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير قاموس معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغتين *args و **kwargs.
البنية العامة
vformat(format_string, args, kwargs)
طريقة عمل الدالة
تؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع التالية:
parse(format_string)
يمرّ هذا التابع على سلسلة التنسيق النصية الممرّرة بواسطة المعامل format_string وتعيد صفًّا على هيئة (literal_text, field_name, format_spec, conversion). تستخدم الدالة vformat() هذا الصفّ لتقسيم السلسلة النصية إلى نصوص أو حقول استبدال. نظريًّا تمثّل القيم التي يتضمّنها الصفّ مجموعة من النصوص متبوعةً بحقل استبدال مفرد. وفي حال عدم وجود النصوص (قد يحدث هذا إذا كان هناك حقلا استبدال متتابعان) فإنّ literal_text سيكون سلسلة نصية فارغة.
أما في حال غياب حقول الاستبدال فإنّ قيم كلّ من field_name و format_spec و conversion ستكون None.
get_field(field_name, args, kwargs)
يحوّل هذا التابع قيمة المعامل field_name الممرّر إليه والمعاد بواسطة التابع parse() إلى كائن جاهز للتنسيق. يعيد هذا التابع صفًّا بهيئة (obj, used_key)، ويأخذ بصورة افتراضية سلاسل نصية بالهيئة المعرّفة في PEP 3101، مثل "0[name]" أو "label.title". يُمرّر المعاملان args و kwargs إلى الدالة voformat(). تشبه القيمة المعادة used_key المعامل key في التابع get_value().
get_value(key, args, kwargs)
يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل key أن يكون عددًا صحيحًا أو سلسلة نصية.
فإن كان عددًا صحيحًا فإنّه يمثل فهرس (موقع) المعامل الموقعي في المعامل args، وإن كان سلسلة نصية، فإنّه يمثّل المعامل المسمّى في المعامل kwargs.
يعيّن المعامل args في قائمة المعاملات الموقعية الخاصّة بالدالة vformat()، أما المعامل kwargs فيعيّن في قاموس المعاملات المفتاحية.
أما بالنسبة لحقول الأسماء المركّبة، فإنّ هذه الدوال تستدعى لأجل المكوّن الأول فقط، ويمكن التعامل مع المكونات الأخرى عن طريق عمليات الفهرسة والخصائص الاعتيادية.
فعلى سبيل المثال، عند استخدام تعبير الحقل '0.name' فإنّ التابع get_value() سيُستدعى مع معامل key يحمل القيمة 0. أما الخاصية فسيُعثر عليها بعد انتهاء عمل التابع get_value() وذلك باستدعاء الدالة الداخلية getattr().
وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ IndexError أو KeyError.
check_unused_args(used_args, args, kwargs)
يتحقّق هذا التابع من المعاملات غير المستخدمة، ومعاملات هذا التابع هي مجموعة تضم جميع مفاتيح المعاملات والتي أشير إليها في سلسلة التنسيق النصية (الأعداد الصحيحة في حالة المعاملات الموقعية، والسلاسل النصية في محالة المعاملات المسماة)، إضافة إلى إشارة إلى المعاملين args و kwargs الممرّان في الدالة vformat().
يفترض بالتابع check_unused_args() أن يطلق استثناء عند فشل عملية التحقق.
format_field(value, format_spec)
يستدعي هذا التابع الدلة الداخلية format(). ويقدّم الصنف Formatter هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه (override).
convert_field(value, conversion)
يحوّل التابع القيمة المعادة من التابع get_field() باعتماد نوع التحويل المعطى (كما في الصفّ المعاد من التابع parse()). عمليات التحويل التي يدعمها هذا التابع هي 's' (str)، و 'r' (repr)، و 'a' (ascii).
انظر أيضًا
- مواصفات التنسيق في بايثون.
- صيغة سلاسل التنسيق النصية في بايثون.
- التابع
Formatter.format(): هذا هو تابع الواجهة البرمجية العام، ويأخذ سلسلة تنسيق نصية وعددًا من المعاملات الموقعية والمفتاحية. ويعدّ تابع تغليف wrapper يستدعي الدالةvformat(). - الدالة
format(): تُحوّل هذه الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده مواصفة التّنسيق المُعطاة.