Python/string/Formatter/vformat

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

vformat(format_string, args, kwargs)

هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة exposed كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير قاموس معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغة ‎*args و ‎**kwargs. وتؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع الموصوفة أدناه.

يقدّم الصنف Fromatter عددًا من التوابع الإضافية المعدّة للاستبدال بواسطة الأصناف الفرعية:

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)‎.