عرض مصدر Python/string/format string syntax

<noinclude>{{DISPLAYTITLE:صيغة سلاسل التنسيق النصية في بايثون}}</noinclude>

يستخدم التابع <code>[[Python/str/format|str.format()]]</code>‎ والصنف <code>[[Python/string/Formatter|Formatter]]</code> صيغة سلاسل التنسيق النصية ذاتها، (ولكن يمكن للأصناف الفرعية في الصنف [[Python/string/Formatter|<code>Formatter</code>]] أن تعرّف الصيغة الخاصّة بها). ترتبط هذه الصيغة بحروف سلاسل التنسيق النصية، ولكن هناك بعض الاختلافات.

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

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

<syntaxhighlight lang="python3">
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>
</syntaxhighlight>

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

يمكن أن يأتي حقل التحويل <code>conversion</code> الاختياري بعد اسم الحقل، ويكون حقل التحويل مسبوقًا بعلامة تعجب <code>'!'</code>، ويأتي بعدها حقل <code>format_spec</code> والذي يكون مسبوقًا بنقطتين رأسيتين <code>':'</code>. تحدّد هذه الحقول التنسيق غير الافتراضي لقيمة الاستبدال. (راجع أيضًا قسم [[Python/string/formatspec|مواصفات التنسيق في بايثون]] ).

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

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

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

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

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

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

<syntaxhighlight lang="python3">
"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' العنصر الأول في المعامل المفتاحي
</syntaxhighlight>

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

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

<syntaxhighlight lang="python3">
"Harold's a clever {0!s}"
"Bring out the holy {name!r}"
"More {!a}"
</syntaxhighlight>

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

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

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

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

== أمثلة على عمليات التنسيق ==
يتضمّن هذا القسم مجموعة من الأمثلة على مخرجات التابع <code>[[Python/str/format|str.format()]]‎</code> إلى جانب مقارنتها مع طريقة التنسيق القديمة <code>(%)</code>.

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

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

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

=== الوصول إلى المعاملات حسب موقعها ===
<syntaxhighlight lang="python3">
>>> '{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'
</syntaxhighlight>

=== الوصول إلى المعاملات بواسطة الأسماء ===
<syntaxhighlight lang="python3">
>>> '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'
</syntaxhighlight>

=== الوصول إلى خصائص المعاملات ===
<syntaxhighlight lang="python3">
>>> 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)'
</syntaxhighlight>

=== الوصول إلى عناصر المعامل ===
<syntaxhighlight lang="python3">
>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'
</syntaxhighlight>

=== استبدال ‎<code>%s</code> وـ ‎<code>%r</code> ===
<syntaxhighlight lang="python3">
>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"
</syntaxhighlight>

== انظر أيضًا ==
* [[Python/string/formatspec|مواصفات التنسيق في بايثون.]]
* [[Python/format|الدالة <code>format()‎</code> في بايثون.]]
* [[Python/str/format|التابع <code>str.format()‎</code> في بايثون.]]

== مصادر ==
* [https://docs.python.org/3/library/string.html#format-string-syntax قسم Format String Syntax في صفحة Common String Operations في توثيق بايثون الرسمي.]