Python/string/formatspec

تستخدم "مواصفات التنسيق" ضمن حقول الاستبدال الموجودة في سلاسل التنسيق النصية لتحديد طريقة تمثيل القيم المفردة فيها. ويمكن تمرير هذه المعايير مباشرة إلى الدالة الداخلية format()‎. ويمكن لكل نوع من أنواع جداول التنسيق formattable أن يحدّد الطريقة التي ستُفسَّر بها معايير التنسيق هذه.

صيغة التنسيق

تعتمد معظم الأنواع الداخلية في بايثون الخيارات التالية كمواصفات للتنسيق، ولكن بعض الخيارات مدعومة بواسطة الأنواع العددية فقط.

يؤدي استخدام سلسلة تنسيق نصية فارغة ("") في العادة إلى الحصول على نفس النتيجة المستحصلة من استدعاء الدالة str()‎ على القيمة المراد تنسيقها، أما سلاسل التنسيق غير الفارغة فتؤثّر على النتيجة عادة.

الصيغة العامة لمحدّد التنسيق القياسي هي:

format_spec     ::=  [[fill]align][sign][#][0][width][grouping_option][.precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
type            ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

إن جرى تحديد قيمة صالحة للحقل align فيمكن لهذه القيمة أن تكون مسبوقة بمحرف لملئ الفراغ fill ويمكن استخدام جميع المحارف، وتستخدم اللغة محرف المسافة البيضاء بصورة افتراضية في حال عدم تحديد محرف التعبئة، ويستثنى محرفا الأقواس المعقوفة ("{" و "}") ممّا سبق، إذ لا يمكن استخدامها كمحرفي تعبئة ضمن سلسلة التنسيق أو عند استخدام التابع str.format()‎. ولكن يمكن إدراج الأقواس المعقوفة بواسطة حقول الاستبدال المتشعبة. وجدير بالذكر أنّ هذا الاستثناء غير موجود في الدالة format()‎.

يبين الجدول التالي خيارات المحاذاة المتاحة:

الخيار	المعنى
‎‎'<'‎	يفرض هذا الخيار على الحقل المحاذاة إلى الجانب الأيسر ضمن المساحة المتاحة (هذا هو الخيار الافتراضي لمعظم الكائنات).
‎‎'>'‎	يفرض هذا الخيار على الحقل المحاذاة إلى الجانب الأيمن ضمن المساحة المتاحة (هذا هو الخيار الافتراضي للأعداد).
'='	يفرض إضافة الإزاحة بعد الإشارة (إن وجدت) ولكن قبل الأعداد. يستخدم هذا الخيار لطباعة الحقول على هيئة ‎'+000000120'‎. يمكن استخدام خيار المحاذاة هذا مع الأنواع العددية فقط، ويصبح الخيار الافتراضي عندما يكون عرض الحقل مسبوقًا مباشرة بالقيمة '0'.
'^'	يفرض على الحقل أن يتوسّط المساحة المتاحة.

لاحظ أنّه فيما لو لم يحدّد العرض الأدنى للحقل، فإنّ عرض الحقل سيكون مساويًا دائمًا للبيانات التي ستملؤه، ولن يكون لخيارات المحاذاة أي معنى في مثل هذه الحالة.

الخيار sign صالح للأنواع العددية فقط، ويمكن أن يأخذ إحدى القيم التالية:

الخيار	المعنى
‎‎'+'‎	يفرض استخدام الإشارة مع الأعداد الموجبة والسالبة.
‎‎'-'‎	يفرض استخدام الإشارة مع الأعداد السالبة فقط (هذا هو الخيار الافتراضي).
space	يجب استخدام المسافة البادئة مع الأعداد الموجبة، والإشارة السالبة مع الأعداد السالبة.

يؤدي استخدام الخيار '#' إلى تطبيق الصيغة البديلة في عملية التحويل، ولكل نوع طريقته الخاصة في تعريف الصيغة البديلة. هذا الخيار صالح للأعداد الصحيحة والأعداد ذات الفاصلة العائمة والأعداد المركبة والأعداد العشرية Decimal فقط.

في الأعداد الصحيحة وعند استخدام مخرجات بالنظام الثنائي أو الثماني أو الست عشري، فإنّ هذا الخيار يضيف البادئات ‎'0b'‎ أو '0o' أو '0x' على التوالي إلى المخرجات.

في الأعداد ذات الفاصلة العائمة والأعداد المركبة والأعداد العشرية يؤدي استخدام الصيغة البديلة إلى إحتواء نتيجة التحويل على محرف الفاصلة العشرية بصورة دائمة، حتى لو لم يتلها أي عدد، أما في الحالات الاعتيادية تظهر الفاصلة العشرية في نتائج عمليات التحويل هذه عندما يتبع هذه الفاصلة أعداد فقط. وإلى جانب ذلك، ففي نوعي التمثيل 'g' و 'G' تُحذف الأصفار من بداية نتيجة التحويل.

يشير الخيار ',' إلى أن عملية التحويل تتضمن فصل الآلاف بفاصلة، ولجعل الفاصلة متناسبة مع الإعدادات المحلية، يمكن استخدام نوع التمثيل 'n' الخاص بالأعداد الصحيحة.

ملاحظة: أضيف الخيار ',' في الإصدار 3.1.

يشير الخيار '_' إلى أن عملية التحويل تتضمّن استخدام الشرطة السفلية كفاصل للآلاف في أنواع تمثيل الأعداد ذات الفاصلة العائمة ولنوع التمثيل 'd' الخاص بالأعداد الصحيحة.

في أنواع التمثيل 'b' و 'o' و 'x' و 'X'، تضاف الشرطة السفلية بعد كلّ 4 أرقام. أما تعيين هذا الخيار لأنواع التمثيل الأخرى فيؤدي إلى حدوث خطأ.

ملاحظة: أضيف الخيار '_' في الإصدار 3.6.

الحقل width هو عدد صحيح في النظام العشري يحدّد العرض الأدنى للحقل، وفي حال عدم تعيينه فإنّ محتوى الحقل سيحدّد عرضه.

في حال عدم تحديد نوع المحاذاة في عملية التحويل، يؤدي إلحاق محرف ('0') بالحقل width إلى إجراء الإزاحة باستخدام الرقم صفر مع مراعاة الإشارة. نتيجة استخدام هذا الخيار مطابقة لاستخدام المحرف '0' في الحقل fill واستخدام نوع المحاذاة '='.

الحقل precision هو عدد عشري يشير إلى عدد الأعداد التي يجب عرضها بعد الفاصلة العشرية في قيمة من نوع الأعداد العشرية ذات الفاصلة العائمة والمنسّقة بواسطة بنوعي التمثيل 'f' و 'F'، أو قبل وبعد الفاصلة العشرية في الأعداد العشرية ذات الفاصلة العائمة والمنسّقة بنوعي التمثيل 'g' أو 'G'. أما في أنواع البيانات غير العددية، فيمثّل هذا الحقل الحجم الأقصى للحقل، وبمعنى آخر، ما هو عدد المحارف التي ستُستخدم من محتوى الحقل. لا يسمح باستخدام الحقل precision مع الأعداد الصحيحة.

يحدّد الحقل type طريقة عرض البيانات.

يبين الجدول التالي طرق عرض السلاسل النصية:

النوع	المعنى
‎‎'s'‎	تنسيق السلاسل النصية. هذا هو النوع الافتراضي في السلاسل النصية ويمكن حذفه عند استخدامها.
None‎	مشابه للنوع 's'.

ويبين الجدول التالي طرق عرض الأعداد الصحيحة:

النوع	المعنى
‎‎'b'‎	تعرض الأعداد بتنسيق الأعداد الثنائية. (الأساس 2).
‎‎'c'‎	تحوّل الأعداد الصحيحة إلى محارف الترميز الموحد المقابلة قبل طباعتها.
‎‎'d'‎	تعرض الأعداد بتنسيق الأعداد الصحيحة في النظام العشري. (الأساس 10).
'o'	تعرض الأعداد بتنسيق الأعداد الثمانية. (الأساس 8)
'x'	تعرض الأعداد بتنسيق الأعداد الست عشرية (الأساس 16)، باستخدام الأحرف الصغيرة للأعداد التي تكون أكبر من 9.
'X'	تعرض الأعداد بتنسيق الأعداد الست عشرية (الأساس 16)، باستخدام الأحرف الكبيرة للأعداد التي تكون أكبر من 9.
'n'	طريقة العرض هذه مشابهة للطريقة 'd'، باستثناء أنّها تستخدم الإعدادات المحلية لإضافة فاصل الأعداد المناسب.
None	مشابهة للطريقة 'd'.

وإضافة لطرق العرض الآنفة الذكر، يمكن تنسيق الأعداد الصحيحة بواسطة طرق عرض الأعداد العشرية ذات الفاصلة العائمة المدرجة أدناه (باسثتناء 'n' و None). وعند القيام بذلك، تُستخدم الدالة float()‎ لتحويل العدد الصحيح إلى عدد عشري ذي فاصلة عائمة قبل إجراء عملية التنسيق.

يبين الجدول التالي طرق العرض المتاحة للأعداد العشرية ذات الفاصلة العائمة:

النوع	المعنى
'e'	تُطبع الأعداد بالصيغة العلمية وباستخدام الحرف 'e' للإشارة إلى الأس. مقدار الدقة الافتراضي هو 6.
‎‎'E'‎	تشبه الطريقة 'e' باستثناء أنّها تستخدم الحرف الكبير 'E'.
‎‎'f'‎	تعرض العدد كعدد ذي فاصلة ثابتة. مقدار الدقة الافتراضي هو 6.
'F'	مشابهة للطريقة 'f' باستثناء أنّها تحوّل nan إلى NAN و inf إلى INF.
'g'	إن كان مقدار الدقة precision أكبر من أو يساوي 1، فإنّ هذه الطريقة تقرّب العدد إلى بمقدار p من الأعداد المعنوية ثم تنسيّق النتيجة إمّا باستخدام تنسيق الأعداد ذات الفاصلة الثابتة أو الصيغة العلمية، بالاعتماد على مقدار الرقم. أما القواعد الدقيقة لهذه الطريقة فكما يلي: لنفرض أنّ النتيجة منسّقة بطريقة العرض 'e' وأنّ الدقة p-1 تمتلك الأس exp. إذن، إن كان ‎-4 <= exp < p‎ فإنّ العدد سيُنسّق باستخدام طريقة العرض 'f' والدقة p-1-exp، وإلا فإنّ العدد سينسّق باستخدام طريقة العرض 'e' والدقة p-1. وفي كلتا الحالتين ستُحذف الأصفار غير المعنوية من نهاية الجزء المعنوي من العدد، وكذلك تحذف الفاصلة العشرية إن لم يتلها أي عدد. تُنسّق موجب ما لا نهاية وسالب ما لا نهاية، والصفر الموجب والسالب، وnan إلى inf، -inf، 0، -0 و nan على التوالي، بصرف النظر عن مقدار الدقّة المستخدم. لا فرق في عملية التنسيق بين مقدار الدقة 0 و 1، ومقدار الدقة الافتراضي هو 6.
'G'	مشابهة للطريقة 'g'، باستثناء التحويل إلى الصيغة العلمية باستخدام المحرف 'E' عندما يصبح العدد كبيرًا جدًّا. تحول هذه الطريقة تمثيلات ما لا نهاية و nan إلى أحرف كبيرة أيضًا.
'n'	هذه الطريقة مشابهة للطريقة 'g' باستثناء أنّها تستخدم الإعدادات المحلية لإدراج فاصل الأعداد المناسب.
'%'	يُضرب العدد بالعدد 100 ويعرض الناتج بطريقة 'f' متبوعًا بعلامة النسبة المئوية.
None	مشابهة للطريقة 'g'، باستثناء أنه عند استخدام صيغة الفاصلة الثابتة، سيكون هناك على الأقل عدد واحد بعد الفاصلة العشرية. يمكن لمقدار الدقة الافتراضية أن يكون مرتفعًا حسب الحاجة لتمثيل القيمة الحاضرة. يطابق التأثير الكلّي لهذه الطريقة مخرجات الدالة str()‎ عند تعديلها بواسطة معدّلات التنسيق الأخرى.

أمثلة

فيما يلي بعض الأمثلة التي توضّح طريقة الاستفادة من مواصفات التنسيق في معالجة وتنسيق السلاسل النصية:

محاذاة النصوص وتحديد عرض السلسلة النصية

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # استخدام المحرف '*' لتعبئة السلسلة النصية
'***********centered***********'

استبدال ‎%+f و ‎%-f و ‎% f وتحديد الإشارة

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # عرض الإشارة دائمًا
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # عرض مسافة بيضاء في الأعداد الموجبة
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # '{:f}; {:f}' عرض الإشارة السالبة فقط -- مشابه للصيغة
'3.140000; -3.140000'

استبدال ‎%x و ‎%o وتحويل القيم إلى أسس مختلفة

>>> # يدعم التنسيق الأعداد الثنائية أيضًا
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # 0x, 0o, or 0b البوادئ
>>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

استخدام الفاصلة ',' كفاصل للآلاف

>>> '{:,}'.format(1234567890)
'1,234,567,890'

عرض النسب المئوية

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

استخدام عمليات التنسيق الخاصّة بالأنواع

>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

استخدام المعاملات المتشعبة إضافة إلى أمثلة أكثر تعقيدًا

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
...     for base in 'dXob':
...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011

انظر أيضًا

• السلاسل النصية في بايثون.
• الأعداد الصحيحة في بايثون.
• الأعداد ذات الفاصلة العائمة في بايثون.
• الدالة format()‎: تُحوّل الدّالة قيمةً مُعطاةً إلى تمثيل مُنسّق حسب ما تُحدّده مواصفة التّنسيق المُعطاة.
• التابع str.format()‎: يجري هذا التابع عمليات التنسيق على السلسلة النصية بواسطة معاملات موضعية أو مفتاحية.

مصادر

• قسم Format Specification Mini-Language في صفحة Common String Operations في توثيق بايثون الرسمي.