Python/string/format string syntax

يستخدم التابع str.format()‎ والصنف Formatter صيغة سلاسل التنسيق النصية ذاتها، (ولكن يمكن للأصناف الفرعية في الصنف Formatter أن تعرّف الصيغة الخاصّة بها). ترتبط هذه الصيغة بحروف سلاسل التنسيق النصية، ولكن هناك بعض الاختلافات.

تتضمّن سلاسل التنسيق "حقول استبدال" محاطة بالأقواس المعقوفة {}، ويعدّ كل شيء خارج هذه الأقواس حرفًا اعتياديًا ويُنسخ إلى المخرجات دون أي تعديل. إن كانت هناك حاجة إلى استخدام الأقواس المعقوفة ضمن النص فيمكن تهريبها بمضاعفتها: {{ و }}.

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

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | digit+]
attribute_name    ::=  identifier
element_index     ::=  digit+ | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  <described in the next section>

يمكن لحقل الاستبدال أن يبدأ باسم حقل field_name يحدّد الكائن الذي الذي سيجري تنسيق قيمته وإدراجها في المخرجات عوضًا عن حقل الاستبدال.

يمكن أن يأتي حقل التحويل conversion الاختياري بعد اسم الحقل، ويكون حقل التحويل مسبوقًا بعلامة تعجب '!'، ويأتي بعدها حقل format_spec والذي يكون مسبوقًا بنقطتين رأسيتين ':'. تحدّد هذه الحقول التنسيق غير الافتراضي لقيمة الاستبدال. (راجع أيضًا قسم ########### Format Specification Mini-Language )

يبدأ اسم الحقل باسم معامل arg_name والذي يمكن أن يكون عددًا أو كلمة مفتاحية، فإن كان عددًا فإنّه يشير إلى معامل موقعي، وإن كان كلمة مفتاحية، فإنّه يشير إلى المعامل المفتاحي الذي يحمل الاسم ذاته.

إن كانت الأعداد في arg_name هي 0، 1، 2... بالتسلسل، فيمكن حينئذ حذف الأرقام جميعها (وليس بعضها) وستُدرج الأرقام بصورة تلقائية وبنفس التسلسل ضمن سلسلة التنسيق النصية.

ونظرًا لكون arg_name غير محدّد بعلامات اقتباس، فإنّه من غير الممكن تعيين مفاتيح قواميس حسب الرغبة (مثال: السلاسل النصية '10' أو ‎':-]'‎) في سلسلة التنسيق النصية.

يمكن أن يتبع arg_name أيّ عددٍ من الفهارس أو تعابير الخصائص، ويحدّد التعبير ذو الهيئة ‎'.name'‎ الخاصية المسمّاة باستخدام التابع getattr()‎، أما التعبير ذو الهيئة '[index]' فيؤدي عملية بحث عن الفهرس باستخدام التابع ‎__getitem__()‎.

ملاحظة: أصبح بالإمكان حذف محدّدات المعاملات الموضعية في الإصدار 3.1 من اللغة، وهذا يعني أنّ التعبير '{} {}' مكافئ للتعبير ‎'{0}{1}'‎.

فيما يلي بعض الأمثلة على سلاسل التنسيق النصية:

"First, thou shalt count to {0}"  # الإشارة إلى المعامل الموقعي الأول
"Bring me a {}"                   # الإشارة الضمنية إلى المعامل الموقعي الأول
"From {} to {}"                   # "From {0} to {1}" مكافئ للتعبير
"My quest is {name}"              # 'name' يشير إلى الكلمة المفتاحية
"Weight in tons {0.weight}"       # 'weight' الخاصية التابعة لأول معامل موضعي
"Units destroyed: {players[0]}"   # 'players' العنصر الأول في المعامل المفتاحي

يؤدي استخدام الحقل conversion إلى فرض طريقة تنسيق خاصّة، ففي الحالات الاعتيادية يجري تنسيق قيمة معيّنة باستخدام التابع ‎__format__()‎ الخاصّ بتلك القيمة، ولكن في بعض الأحيان يكون المطلوب إجبار نوعٍ معيّن من البيانات على أن يُنسّق كسلسلة نصية، وأن يُعاد تعريف طريقة التنسيق الخاصّة بذلك النوع. وهكذا يؤدي تحويل القيمة إلى سلسلة نصية قبل استدعاء التابع ‎__format__()‎ إلى تجاوز عملية التنسيق الاعتيادية الخاصّة بذلك النوع.

تدعم بايثون في الوقت الحاضر ثلاث رايات للتحويل هي: ‎'!s'‎ والتي تستدعي التابع str()‎ وتطّبقه على القيمة، والراية ‎'!r'‎ والتي تستدعي الدالة repr()‎ والراية ‎'!a'‎ والتي تستدعي الدالة ascii()‎.

"Harold's a clever {0!s}"
"Bring out the holy {name!r}"
"More {!a}"

يتضمّن حقل format_spec بيانًا لطريقة تمثيل القيمة، مثل عرض الحقل، والمحاذاة والإزاحة ومقدار الدقة المعتمد في الأعداد العشرية وهكذا. ويمكن لكلّ قيمة أن تعرّف "لغة التنسق المصغّرة" الخاصّة بها أو تفسيرًا خاصًّا للبيان الذي يتضمّنه الحقل format_spec.

تدعم معظم أنواع البيانات الداخلية في بايثون لغة تنسيق مصغّرة مشتركة. (راجع قسم لغة التنسيق المصغّرة).

يمكن لحقل format_spec أن يتضمّن أيضًا حقول استبدال متشعّبة، والتي قد تتضمّن بدورها اسم الحقل وراية التحويل وبيان التنسيق، ولكن لا تدعم اللغة التشعّب العميق لهذه الحقول.

يجري استبدال حقول الاستبدال في حقل format_spec قبل تفسير السلسلة النصية التي يضمّها هذا الحقل، الأمر الذي يسمح بتعيين طريقة تنسيق القيم على نحو ديناميكي.

أمثلة على عمليات التنسيق

يتضمّن هذا القسم مجموعة من الأمثلة على مخرجات التابع str.format()‎ إلى جانب مقارنتها مع طريقة التنسيق القديمة (%).

في معظم الحالات تكون الصيغة مشابهة لصيغة التنسيق القديمة (%)، مع إضافة الأقواس المعقوفة {} واستخدام النقطتين الرأسيتين : بدلًا عن %.

فمثلًا يمكن ترجمة الصيغة ‎'%03.2f'‎ إلى ‎'{:03.2f}'‎.

تدعم صيغة التنسيق الجديدة كذلك عددًا من الخيارات الجديدة، والمبيّنة في الأمثلة التالية:

الوصول إلى المعاملات حسب موقعها

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # فك تحزيم تسلسل المعاملات
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # يمكن تكرار فهارس المعاملات أكثر من مرة
'abracadabra'

الوصول إلى المعاملات بواسطة الأسماء

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'

الوصول إلى خصائص المعاملات

>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
...  'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...     def __str__(self):
...         return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'

الوصول إلى عناصر المعامل

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

استبدال ‎%s وـ ‎%r

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

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

>>> '{:<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