Next / Previous / Contents / TCC Help System / NM Tech homepage

7.2.2. The string format operator

In addition to the common sequence operations described in Section 7.1, “Operations common to all the sequence types”, strings support the format operator%”. This extremely useful operator uses a template string to specify how to format one or more values. Here is the general form:

f % v

where f is the template string and v specifies the value or values to be formatted using that template. If multiple values are to be formatted, v must be a tuple.

The template string may contain any mixture of ordinary text and format codes. A format code always starts with a percent (%) symbol. See Table 4, “Format codes”.

The result of a format operation consists of the ordinary characters from the template with values substituted within them wherever a format code occurs. A conversational example:

>>> print "We have %d pallets of %s today." % (49, "kiwis")
We have 49 pallets of kiwis today.

In the above example, there are two format codes. Code “%d” means “substitute a decimal number here,” and code “%s” means “substitute a string value here”. The number 49 is substituted for the first format code, and the string "kiwis" replaces the second format code.

In general, format codes have this form:

%[p][m[.n]]c

Table 3. Parts of the format operator

p An optional prefix; see Table 5, “Format code prefixes”.
m

Specifies the total desired field width. The result will never be shorter than this value, but may be longer if the value doesn't fit; so, "%5d" % 1234 yields " 1234", but "%2d" % 1234 yields "1234".

If the value is negative, values are left-aligned in the field whenever they don't fill the entire width.

n For float values, this specifies the number of digits after the decimal point.
c Indicates the type of formatting.

Here are the format type codes, c in the general expression above:

Table 4. Format codes

%s Format a string. For example, '%-3s' % 'xy' yields 'xy '; the width (-3) forces left alignment.
%d Decimal conversion. For example, '%3d' % -4 yields the string ' -4'.
%e Exponential format; allow four characters for the exponent. Examples: '%08.1e' % 1.9783 yields '0002.0e+00'.
%E Same as %e, but the exponent is shown as an uppercase E.
%f For float type. E.g., '%4.1f' % 1.9783 yields ' 2.0'.
%g General numeric format. Use %f if it fits, otherwise use %e.
%G Same as %G, but an uppercase E is used for the exponent if there is one.
%o Octal (base 8). For example, '%o' % 13 yields '15'.
%x Hexadecimal (base 16). For example, '%x' % 247 yields 'f7'.
%X Same as %x, but capital letters are used for the digits A-F. For example, '%04X' % 247 yields '00F7'; the leading zero in the length (04) requests that Python fill up any empty leading positions with zeroes.
%c Convert an integer to the corresponding ASCII code. For example, '%c' % 0x61 yields the string 'a'.
%% Places a percent sign (%) in the result. Does not require a corresponding value. Example: "Energy at %d%%." % 88 yields the value 'Energy at 88%.'.

Table 5. Format code prefixes

+ For numeric types, forces the sign to appear even for positive values.
- Left-justifies the value in the field.
0 For numeric types, use zero fill. For example, '%04d' % 2 produces the value '0002'.
# With the %o (octal) format, append a leading "0"; with the %x (hexadecimal) format, append a leading "0x"; with the %g (general numeric) format, append all trailing zeroes. Examples:
>>> '%4o' % 127
' 177'
>>> '%#4o' % 127
'0177'
>>> '%x' % 127
'7f'
>>> '%#x' % 127
'0x7f'
>>> '%10.5g' % 0.5
'       0.5'
>>> '%#10.5g' % 0.5
'   0.50000'