الفرق بين المراجعتين ل"Python/string/Formatter/vformat"

المراجعة الحالية بتاريخ 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()‎: تُحوّل هذه الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده مواصفة التّنسيق المُعطاة.

مصادر

قسم Custom String Formatting في صفحة Common String Operations في توثيق بايثون الرسمي.

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE:الدالة <code>Formatter.vformat()‎</code> في بايثون}}</noinclude>
+هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة (exposed) كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير [[Python/dict|قاموس]] معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغتين ‎<code>*args</code> و <code>‎**kwargs</code>.
-== البنية العامة ==
+==البنية العامة==
+<syntaxhighlight lang="python3">
 vformat(format_string, args, kwargs)
+</syntaxhighlight>
+== طريقة عمل الدالة ==
+تؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع التالية:
-هذه الدالة هي المسؤولة الحقيقية عن جميع عمليات التنسيق، وهي دالة مكشوفة exposed كدالة منفصلة لاستخدامها في الحالات التي يكون المطلوب فيها تمرير قاموس معاملات معرّف مسبقًا، بدلًا عن فك تحزيم القاموس وإعادة تحزيمه مرة أخرى كمعاملات منفردة باستخدام الصيغة ‎*args و ‎**kwargs. وتؤدي هذه الدالة مهمّة تقسيم سلسلة التنسيق النصية إلى بيانات حرفية وحقول استبدال، وتستدعي جميع التوابع الموصوفة أدناه.
+=== <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> سيكون سلسلة نصية فارغة.
-يقدّم الصنف Fromatter عددًا من التوابع الإضافية المعدّة للاستبدال بواسطة الأصناف الفرعية:
+أما في حال غياب حقول الاستبدال فإنّ قيم كلّ من <code>field_name</code> و <code>format_spec</code> و <code>conversion</code> ستكون <code>None</code>.
-parse(format_string)
+=== <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>‎.
-يمرّ هذا التابع على سلسلة التنسيق النصية الممرّرة بواسطة المعامل format_string وتعيد صفًّا على هيئة (literal_text, field_name, format_spec, conversion). تستخدم الدالة vformat()‎ هذا الصفّ لتقسيم السلسلة النصية إلى نصوص أو حقول استبدال. نظريًّا تمثّل القيم التي يتضمّنها الصفّ مجموعة من النصوص متبوعةً بحقل استبدال مفرد. وفي حال عدم وجود النصوص (قد يحدث هذا إذا كان هناك حقلا استبدال متتابعان) فإنّ literal_text سيكون سلسلة نصية فارغة.
+=== <code>get_value(key, args, kwargs)‎</code> ===
-أما في حال غياب حقول الاستبدال فإنّ قيم كلّ من field_name و format_spec و conversion ستكون None.
+يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل <code>key</code> أن يكون عددًا صحيحًا أو سلسلة نصية.
-get_field(field_name, args, kwargs)
+فإن كان [[Python/int|عددًا صحيحًا]] فإنّه يمثل فهرس (موقع) المعامل الموقعي في المعامل <code>args</code>، وإن كان [[Python/str|سلسلة نصية]]، فإنّه يمثّل المعامل المسمّى في المعامل <code>kwargs</code>.
-يحوّل هذا التابع قيمة المعامل field_name الممرّر إليه والمعاد بواسطة التابع parse()‎، يحوّله إلى كائن جاهز للتنسيق. يعيد هذا التابع صفًّا بهيئة (obj, used_key)، ويأخذ بصورة افتراضية سلاسل نصية بالهيئة المعرّفة في PEP 3101، مثل ‎"0[name]"‎ أو "label.title". يُمرّر المعاملان args و kwargs إلى الدالة voformat()‎. تشبه القيمة المعادة used_key المعامل key في التابع get_value()‎.
+يعيّن المعامل <code>args</code> في قائمة المعاملات الموقعية الخاصّة بالدالة <code>vformat()‎</code>، أما المعامل <code>kwargs</code> فيعيّن في قاموس المعاملات المفتاحية.
-get_value(key, args, kwargs)
+أما بالنسبة لحقول الأسماء المركّبة، فإنّ هذه الدوال تستدعى لأجل المكوّن الأول فقط، ويمكن التعامل مع المكونات الأخرى عن طريق عمليات الفهرسة والخصائص الاعتيادية.
-يعيد هذا التابع قيمة الحقل المحدّد في المعاملات، ويمكن للمعامل key أن يكون عددًا صحيحًا أو سلسلة نصية.
+فعلى سبيل المثال، عند استخدام تعبير الحقل ‎<code>'0.name'‎</code> فإنّ التابع <code>get_value()‎</code> سيُستدعى مع معامل <code>key</code> يحمل القيمة <code>0</code>. أما الخاصية فسيُعثر عليها بعد انتهاء عمل التابع <code>get_value()‎</code> وذلك باستدعاء الدالة الداخلية <code>getattr()</code>‎.
-فإن كان عددًا صحيحًا فإنّه يمثل فهرس (موقع) المعامل الموقعي في المعامل args، وإن كان سلسلة نصية، فإنّه يمثّل المعامل المسمّى في المعامل kwargs.
-يعيّن المعامل args في قائمة المعاملات الموقعية الخاصّة بالدالة vformat()‎، أما المعامل kwargs فيعيّن في قاموس المعاملات المفتاحية.
+وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ <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>‎.
-فعلى سبيل المثال، عند استخدام تعبير الحقل ‎'0.name'‎ فإنّ التابع get_value()‎ سيُستدعى مع معامل key يحمل القيمة 0. أما الخاصية فسيُعثر عليها بعد انتهاء عمل التابع get_value()‎ وذلك باستدعاء الدالة الداخلية getattr()‎.
+يفترض بالتابع <code>check_unused_args()</code>‎ أن يطلق استثناء عند فشل عملية التحقق.
-وفي حال أشار الفهرس أو الكلمة المفتاحية إلى عنصر غير موجود، فإنّ اللغة تطلق الخطأ IndexError أو KeyError.
+=== <code>format_field(value, format_spec)‎</code> ===
+يستدعي هذا التابع الدلة الداخلية <code>[[Python/format|format()‎]]</code>. ويقدّم الصنف <code>Formatter</code> هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه (override).
-check_unused_args(used_args, args, kwargs)
+=== <code>convert_field(value, conversion)‎</code> ===
-يتحقّق هذا التابع من المعاملات غير المستخدمة، ومعاملات هذا التابع هي مجموعة تضم جميع مفاتيح المعاملات والتي أشير إليها في سلسلة التنسيق النصية (الأعداد الصحيحة في حالة المعاملات الموقعية، والسلاسل النصية في محالة المعاملات المسماة)، إضافة إلى إشارة إلى المعاملين args و kwargs الممرّان في الدالة vformat()‎.
+يحوّل التابع القيمة المعادة من التابع <code>get_field()</code>‎ باعتماد نوع التحويل المعطى (كما في الصفّ المعاد من التابع <code>parse()</code>‎). عمليات التحويل التي يدعمها هذا التابع هي ‎<code>'s'</code> (str)‎، و ‎<code>'r'</code> (repr)‎، و ‎<code>'a'</code> (ascii)‎.
-يفترض بالتابع check_unused_args()‎ أن يطلق استثناء عند فشل عملية التحقق.
-format_field(value, format_spec)
+== انظر أيضًا ==
-يستدعي هذا التابع الدلة الداخلية format()‎. ويقدّم الصنف Formatter هذا التابع للسماح للأصناف الفرعية بأن تعيد تعريفه override.
+* [[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|مواصفة التّنسيق المُعطاة]].
-convert_field(value, conversion)
+== مصادر ==
-يحوّل التابع القيمة المعادة من التابع get_field()‎ باعتماد نوع التحويل المعطى (كما في الصفّ المعاد من التابع parse()‎). عمليات التحويل التي يدعمها هذا التابع هي ‎'s' (str)‎، ‎'r' (repr)‎، و ‎'a' (ascii)‎.
+* [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]]