الفرق بين المراجعتين لصفحة: «Python/string/Formatter/vformat»
لا ملخص تعديل |
لا ملخص تعديل |
||
| سطر 1: | سطر 1: | ||
هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة exposed كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير قاموس معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغتين <code>*args</code> و <code>**kwargs</code>. | هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة exposed كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير [[Python/dict|قاموس]] معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغتين <code>*args</code> و <code>**kwargs</code>. | ||
==البنية العامة== | ==البنية العامة== | ||
| سطر 9: | سطر 9: | ||
تؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع التالية: | تؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع التالية: | ||
=== <code>parse(format_string)</code> === | === التابع <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>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>. | أما في حال غياب حقول الاستبدال فإنّ قيم كلّ من <code>field_name</code> و <code>format_spec</code> و <code>conversion</code> ستكون <code>None</code>. | ||
=== <code>get_field(field_name, args, kwargs)</code> === | === التابع <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>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>get_value(key, args, kwargs)</code> === | ||
يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل <code>key</code> أن يكون عددًا صحيحًا أو سلسلة نصية. | يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل <code>key</code> أن يكون عددًا صحيحًا أو سلسلة نصية. | ||
| سطر 30: | سطر 30: | ||
وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ <code>IndexError</code> أو <code>KeyError</code>. | وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ <code>IndexError</code> أو <code>KeyError</code>. | ||
=== <code>check_unused_args(used_args, args, kwargs)</code> === | === التابع <code>check_unused_args(used_args, args, kwargs)</code> === | ||
يتحقّق هذا التابع من المعاملات غير المستخدمة، ومعاملات هذا التابع هي مجموعة تضم جميع مفاتيح المعاملات والتي أشير إليها في سلسلة التنسيق النصية (الأعداد الصحيحة في حالة المعاملات الموقعية، والسلاسل النصية في محالة المعاملات المسماة)، إضافة إلى إشارة إلى المعاملين <code>args</code> و <code>kwargs</code> الممرّان في الدالة <code>vformat()</code>. | يتحقّق هذا التابع من المعاملات غير المستخدمة، ومعاملات هذا التابع هي مجموعة تضم جميع مفاتيح المعاملات والتي أشير إليها في سلسلة التنسيق النصية (الأعداد الصحيحة في حالة المعاملات الموقعية، والسلاسل النصية في محالة المعاملات المسماة)، إضافة إلى إشارة إلى المعاملين <code>args</code> و <code>kwargs</code> الممرّان في الدالة <code>vformat()</code>. | ||
يفترض بالتابع <code>check_unused_args()</code> أن يطلق استثناء عند فشل عملية التحقق. | يفترض بالتابع <code>check_unused_args()</code> أن يطلق استثناء عند فشل عملية التحقق. | ||
=== <code>format_field(value, format_spec)</code> === | === التابع <code>format_field(value, format_spec)</code> === | ||
يستدعي هذا التابع الدلة الداخلية <code>[[Python/format|format()]]</code>. ويقدّم الصنف <code>Formatter</code> هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه override. | يستدعي هذا التابع الدلة الداخلية <code>[[Python/format|format()]]</code>. ويقدّم الصنف <code>Formatter</code> هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه override. | ||
=== <code>convert_field(value, conversion)</code> === | === التابع <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). | يحوّل التابع القيمة المعادة من التابع <code>get_field()</code> باعتماد نوع التحويل المعطى (كما في الصفّ المعاد من التابع <code>parse()</code>). عمليات التحويل التي يدعمها هذا التابع هي <code>'s'</code> (str)، <code>'r'</code> (repr)، و <code>'a'</code> (ascii). | ||
== انظر أيضًا == | == انظر أيضًا == | ||
* [[Python/string/Formatter/format|التابع <code>Formatter.format()</code> | * [[Python/string/Formatter/format|التابع <code>Formatter.format()</code>]]: هذا هو تابع الواجهة البرمجية العام، ويأخذ سلسلة تنسيق نصية وعددًا من المعاملات الموقعية والمفتاحية. ويعدّ تابع تغليف wrapper يستدعي الدالة <code>vformat()</code>. | ||
* [[Python/format|الدالة <code>format()</code> في بايثون.]] | * [[Python/format|الدالة <code>format()</code>]]: تُحوّل هذه الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده [[Python/string/formatspec|مواصفة التّنسيق المُعطاة]]. | ||
* [[Python/string/formatspec|مواصفات التنسيق في بايثون.]] | |||
* [[Python/string/format string syntax|صيغة سلاسل التنسيق النصية في بايثون.]] | |||
== مصادر == | == مصادر == | ||
* [https://docs.python.org/3/library/string.html#string.Formatter.vformat قسم Custom String Formatting في صفحة Common String Operations في توثيق بايثون الرسمي.] | * [https://docs.python.org/3/library/string.html#string.Formatter.vformat قسم Custom String Formatting في صفحة Common String Operations في توثيق بايثون الرسمي.] | ||
<noinclude>{{DISPLAYTITLE:الدالة <code>Formatter.vformat()</code> في بايثون}}</noinclude> | <noinclude>{{DISPLAYTITLE:الدالة <code>Formatter.vformat()</code> في بايثون}}</noinclude> | ||
[[تصنيف:Python]] | |||
[[تصنيف:Python Method]] | |||
مراجعة 11:41، 12 يونيو 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(): تُحوّل هذه الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده مواصفة التّنسيق المُعطاة. - مواصفات التنسيق في بايثون.
- صيغة سلاسل التنسيق النصية في بايثون.