Сообщить об ошибке.

Форматирует строку методом format().

Синтаксис:

str.format(*args, **kwargs)

Внимание! Ссылка для тех, кто ищет встроенную функцию форматирования переменных format().

Параметры:

  • *args - позиционные аргументы
  • **kwargs - ключевые аргументы

Возвращаемое значение:

  • str, копия форматированной строки

Описание:

Метод str.format() выполняет операцию форматирования строки str. Возвращает копию строки, в которой каждое замещающее поле заменяется строковым значением соответствующего аргумента.

Строки str метода str.format() содержат "замещающие поля", заключенные в фигурные скобки {}. Все, что не содержится в фигурных скобках, считается буквальным текстом, который копируется без изменений в выходные данные.

Если необходимо включить в текст дополнительные символы скобок, то это можно сделать путем их удвоения, например {{текст}}.

Каждое замещающее поле {} содержит либо числовой индекс позиционного аргумента, либо имя ключевого аргумента.

Можно сразу перейти к примерам.

Грамматика поля замены выглядит следующим образом:

"{" [ field_name] [ "!" conversion] [ ":" format_spec] "}"
# где:
# - field_name - это *args и(или) **kwargs
# - conversion - это 'r' или 's' или 'a'
# - format_spec - это Спецификация формата Mini-Language

Поле замены {...} может начинаться с field_name, указывающего объект, значение которого должно быть отформатировано и вставлено в выходные данные. За полем field_name, необязательно должны следовать поля: conversion, которому предшествует восклицательный знак '!', и format_spec, которому предшествует двоеточие ':'. Они задают формат замены, отличный от формата по умолчанию.

Поле field_name
Поле является либо числом, либо ключевым словом. Если это число, то оно ссылается на позиционный аргумент, а если ключевое слово, то на именованный аргумент ключевого слова.

Если в строке формата '... {0} ... {1} ... {2}'.format(a, b, c) числа являются номерами позиционных аргументов, они все могут быть опущены, а индексы позиционных аргументов 0, 1, 2, ... будут автоматически вставлены.

# ПОЗИЦИОННЫЕ АРГУМЕНТЫ
'текст {0} текст {1} текст'.format(a, b)

# числа позиционных аргументов можно не 
# указывать, если они следуют подряд
'текст {} текст {} текст'.format(a, b)

# числа позиционных аргументов следует указывать,
# если в форматируемой строке они следуют  не по порядку
'текст {1} текст {0} текст {1}'.format(a, b)

# КЛЮЧЕВЫЕ АРГУМЕНТЫ
# имена ключевых аргументов указываются всегда
'текст {one} текст {two} текст {two}'.format(one=a, two=b)

Поле conversion
Поле преобразования conversion вызывает приведение типа перед форматированием. Обычно задание форматирования значения выполняется методом __format__() самого значения. Однако в некоторых случаях желательно принудительно форматировать тип в виде строки, переопределяя его собственное определение форматирования. При преобразовании значения в строку перед вызовом __format__() обычная логика форматирования игнорируется.

В настоящее время поддерживаются три флага преобразования:

  • '!s ' - вызывает str() по значению,
  • '!r' - вызывает repr(),
  • '!a' - вызывает ascii().

Поле format_spec
Cодержит спецификацию формата "Mini-Language". Эта спецификация определяет, как должно быть представлено значение, включая такие детали, как ширина поля, выравнивание, заполнение, десятичная точность и так далее. Большинство встроенных типов поддерживают спецификацию формата "Mini-Language", который описан во встроенной функции format().

Примеры форматирования методом строки str.format().

Вывод значений, заданных позиционными аргументами:

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

# использование строки, как шаблона
>>> tpl = '{0}{1}{0}'
>>> tpl.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.'

Доступ к элементам аргументов:

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

Использование фигурных скобок в строке/шаблоне.

Что если в строке должны использоваться дополнительные фигурные скобки? Например:

# строка - шаблон
>>> tpl = "Строка №{0} с {{1}-мя фигурными скобками}"
# форматируем строку-шаблон
>>> prn = tpl.format(1, 2)
# Traceback (most recent call last):
#   File "<stdin>", line 1, in <module>
# ValueError: Single '}' encountered in format string

Чтобы форматировать строку с дополнительными фигурными скобками, необходимо эти дополнительные скобки удвоить.

# в строке - шаблоне удвоим фигурные скобки, 
# которые не отвечают за перенос значений переменных
>>> tpl = "Строка №{0} с {{{1}-мя фигурными скобками}}"
# форматируем строку-шаблон
>>> tpl.format(1, 2)
# 'Строка №1 с {2-мя фигурными скобками}'

Используем приведение типа перед форматированием на примере !r и !s:

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

Выравнивание текста и указание ширины при помощи разметки:

Подробнее, смотрите спецификацию формата Mini-Language.

>>> '{:<30}'.format('left aligned')
# 'left aligned                  '

>>> '{:>30}'.format('right aligned')
# '                 right aligned'

>>> '{:^30}'.format('centered')
# '           centered           '

# используем '*' как символ-заполнитель
>>> '{:*^30}'.format('centered')  # use '*' as a fill char
# '***********centered***********'

Форматируем число со знаком:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)
# '+3.140000; -3.140000'

# покажем пробел для положительных чисел
>>> '{: f}; {: f}'.format(3.14, -3.14)
# ' 3.140000; -3.140000'

# покажем только минус - то же, что и '{: f}; {: f}'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)
# '3.140000; -3.140000'

Замена %x и %o и преобразование значения в разные счисления:

# Метод str.format() поддерживает двоичные числа
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
# 'int: 42;  hex: 2a;  oct: 52;  bin: 101010'

# теперь с префиксами 0x, 0o или 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
>>> 'Правильные ответы: {:.2%}'.format(points/total)
# 'Правильные ответы: 86.36%'

Использование форматирования, зависящего от типа передаваемых данных:

>>> import datetime
>>> d = datetime.datetime(2021, 7, 3, 11, 13, 13)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
# '2021-07-03 11:13:13'