صيغة سلاسل التنسيق النصية في بايثون

يستخدم التابع 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' attribute of first positional arg
"Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

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

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

"Harold's a clever {0!s}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

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

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

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

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