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

3.4. The string format operator

One of the commonest string operations is Python's format operator. Here, we want to substitute variable values into a fixed string.

For example, suppose your program wants to report how many bananas you have, and you have an int variable named nBananas that contains the actual banana count, and you want to print a string something like “We have 27 bananas” if nBananas has the value 27. This is how you do it:

>>> nBananas = 27
>>> "We have %d bananas." % nBananas
'We have 27 bananas.'

In general, when a string value appears on the left side of the “%” operator, that string is called the format string. Within a format string, the percent character “%” has special meaning. In the example above, the “%d” part means that an integer value will be substituted into the format string at that position. So the result of the format operator will be a string containing all the characters from the format string, except that the value on the right of the operator (27) will replace the “%d” in the format string.

Here's another example, showing the substitution of a string value.

>>> noSuch = "kiwis"
>>> 'We are out of %s today.' % noSuch
'We are out of kiwis today.'

This demonstrates the “%s” format code, which means that a string value is to be substituted at that position in the result.

You can substitute more than one value in a format operation, but you must enclose the values to be substituted in parentheses, separated by commas. For example:

>>> caseCount = 42
>>> caseContents = "peaches"
>>> print "We have %d cases of %s today." % (caseCount, caseContents)
We have 42 cases of peaches today.

So, in general, a format operator has this form:

format % (value1, value2, ...)

Wherever a format code starting with “%” appears in the format string, the corresponding valuei is substituted for that format code.

The various format codes have a number of additional features that let you control how the values are displayed. For example, the “%s” format code always produces a value exactly as long as the string value you provide. But you may wish to produce a value of a fixed size. To do this, use a format code of the form “%Ns”, where N is the number of characters you want the result to occupy. Examples:

>>> '%s' % 'soup'
>>> '%6s' % 'soup'
'  soup'

If a string shorter than N characters is formatted using format code “%Ns”, spaces are added before the string to fill the result out to N characters. If you would prefer that the extra spaces be added after the string value, use a format code of the form “%-Ns”.

>>> '%-6s' % 'soup'
'soup  '

By default, the integer format code “%d” always produces a string that is just large enough to hold the number. But if you want the number to occupy exactly N digits, you can use a format code of the form “%Nd”. Examples:

>>> "%d" % 1107
>>> "%5d" % 1107
' 1107'
>>> '%30d' % 1107
'                          1107'
>>> '%2d' % 1107

Notice in the last example that when you specify a field size that is too small for the number, Python will not truncate the number; it will take as many characters as needed to properly render the value.

When your number does not fill the field, the default is to add spaces to the left of the number as needed. If you would prefer that the extra spaces be added after the number, use a format code of the form “%-Nd”.

>>> '%5d' % 505
'  505'
>>> '%-5d' % 505
'505  '

You can ask Python to use zeroes instead of spaces to fill extra positions by using a format code of the form “%0Nd”.

>>> '%5d' % 42
'   42'
>>> '%05d'%42

Next we'll examine Python's format code for float values. In its simplest form, it is just “%f”.

>>> "%f" % 0.0
>>> "%f" % 1.5
>>> pi = 3.141592653589793
>>> "%f" % pi

By default, the result will show six digits of precision after the decimal point. To specify P digits of precision, use a format code of the form “%.Pf”.

>>> "%.0f" % pi
>>> "%.15f" % pi

You can also specify the total number of characters to be used in formatting a number. A format code of the form “%N.Pf” will try to fit the result into N characters, with P digits after the decimal point.

>>> "%10f" % pi
'  3.141593'
>>> "%5.1f" % pi
'  3.1'
>>> "%5.3f" % pi
>>> "%50.40f" % 5.33333
'        5.3333300000000001261923898709937930107117'

Notice in the last example above that it is possible for you to produce any number of spurious digits beyond the precision used to specify the number originally! Beware, because those extra digits are utter garbage.

When you specify a precision, the value is rounded to the nearest value with that precision.

>>> "%.1f" % 0.999
>>> "%.1f" % 0.99
>>> "%.1f" % 0.9
>>> "%.1f" % 0.96
>>> "%.1f" % 0.9501
>>> "%.1f" % 0.9499999

As with the %s and %d formats, you can use a negative field size in the %f format code to cause the value to be left-aligned in the field.

>>> "%10.2f" % pi
'      3.14'
>>> "%-10.2f" % pi
'3.14      '

If you would prefer to display a float value using the exponential format, use a format code of the form “%N.Pe”. The exponent will always occupy four or five digits depending on the size of the exponent.

>>> avo = 6.022e23
>>> "%e" % avo
>>> "%.3e" % avo
>>> "%11.4e" % avo
' 6.0220e+23'
>>> googol = 1e100
>>> "%e" % googol
>>> "%e" % pi