2.2.6.2 String Formatting Operations

String and Unicode objects have one unique built-in operation: the % operator (modulo). Given format % values (where format is a string or Unicode object), % conversion specifications in format are replaced with zero or more elements of values. The effect is similar to the using sprintf() in the C language. If format is a Unicode object, or if any of the objects being converted using the %s conversion are Unicode objects, the result will be a Unicode object as well.

If format requires a single argument, values may be a single non-tuple object. ^2.8 Otherwise, values must be a tuple with exactly the number of items specified by the format string, or a single mapping object (for example, a dictionary).

A conversion specifier contains two or more characters and has the following components, which must occur in this order:

The "%" character, which marks the start of the specifier.
Mapping key value (optional), consisting of an identifier in parentheses (for example, (somename)).
Conversion flags (optional), which affect the result of some conversion types.
Minimum field width (optional). If specified as an "*" (asterisk), the actual width is read from the next element of the tuple in values, and the object to convert comes after the minimum field width and optional precision.
Precision (optional), given as a "." (dot) followed by the precision. If specified as "*" (an asterisk), the actual width is read from the next element of the tuple in values, and the value to convert comes after the precision.
Length modifier (optional).
Conversion type.

If the right argument is a dictionary (or any kind of mapping), then the formats in the string must have a parenthesized key into that dictionary inserted immediately after the "%" character, and each format formats the corresponding entry from the mapping. For example:

>>> count = 2
>>> language = 'Python'
>>> print '%(language)s has %(count)03d quote types.' % vars()
Python has 002 quote types.

In this case no * specifiers may occur in a format (since they require a sequential parameter list).

The conversion flag characters are:

Flag Meaning

# The value conversion will use the ``alternate form'' (where defined below).
0 The conversion will be zero padded.
- The converted value is left adjusted (overrides "-").
(a space) A blank should be left before a positive number (or empty string) produced by a signed conversion.
+ A sign character ("+" or "-") will precede the conversion (overrides a "space" flag).

Flag	Meaning
`#`	The value conversion will use the ``alternate form'' (where defined below).
`0`	The conversion will be zero padded.
`-`	The converted value is left adjusted (overrides "`-`").
	(a space) A blank should be left before a positive number (or empty string) produced by a signed conversion.
`+`	A sign character ("`+`" or "`-`") will precede the conversion (overrides a "space" flag).

The length modifier may be h, l, and L may be present, but are ignored as they are not necessary for Python.

The conversion types are:

Conversion Meaning

d Signed integer decimal.
i Signed integer decimal.
o Unsigned octal.
u Unsigned decimal.
x Unsigned hexidecimal (lowercase).
X Unsigned hexidecimal (uppercase).
e Floating point exponential format (lowercase).
E Floating point exponential format (uppercase).
f Floating point decimal format.
F Floating point decimal format.
g Same as "e" if exponent is greater than -4 or less than precision, "f" otherwise.
G Same as "E" if exponent is greater than -4 or less than precision, "F" otherwise.
c Single character (accepts integer or single character string).
r String (converts any python object using repr()).
s String (converts any python object using str()).
% No argument is converted, results in a "%" character in the result. (The complete specification is %%.)

Conversion	Meaning
`d`	Signed integer decimal.
`i`	Signed integer decimal.
`o`	Unsigned octal.
`u`	Unsigned decimal.
`x`	Unsigned hexidecimal (lowercase).
`X`	Unsigned hexidecimal (uppercase).
`e`	Floating point exponential format (lowercase).
`E`	Floating point exponential format (uppercase).
`f`	Floating point decimal format.
`F`	Floating point decimal format.
`g`	Same as "`e`" if exponent is greater than -4 or less than precision, "`f`" otherwise.
`G`	Same as "`E`" if exponent is greater than -4 or less than precision, "`F`" otherwise.
`c`	Single character (accepts integer or single character string).
`r`	String (converts any python object using `repr()`).
`s`	String (converts any python object using `str()`).
`%`	No argument is converted, results in a "`%`" character in the result. (The complete specification is `%%`.)

Since Python strings have an explicit length, %s conversions do not assume that '\0' is the end of the string.

For safety reasons, floating point precisions are clipped to 50; %f conversions for numbers whose absolute value is over 1e25 are replaced by %g conversions.^2.9 All other errors raise exceptions.

Additional string operations are defined in standard modules string and re.

Footnotes

... object.^2.8: A tuple object in this case should be a singleton.
... conversions.^2.9: These numbers are fairly arbitrary. They are intended to avoid printing endless strings of meaningless digits without hampering correct use and without having to know the exact precision of floating point values on a particular machine.

See About this document... for information on suggesting changes.