Previous Page
Next Page

9.3. String Formatting

In Python, a string-formatting expression has the syntax:

format % values

where format is a plain or Unicode string containing format specifiers and values is any single object or a collection of objects in a tuple or dictionary. Python's string-formatting operator has roughly the same set of features as the C language's printf and operates in a similar way. Each format specifier is a substring of format that starts with a percent sign (%) and ends with one of the conversion characters shown in Table 9-1.

Table 9-1. String-formatting conversion characters


Output format


d, i

Signed decimal integer

Value must be number.


Unsigned decimal integer

Value must be number.


Unsigned octal integer

Value must be number.


Unsigned hexadecimal integer (lowercase letters)

Value must be number.


Unsigned hexadecimal integer (uppercase letters)

Value must be number.


Floating-point value in exponential form (lowercase e for exponent)

Value must be number.


Floating-point value in exponential form (uppercase E for exponent)

Value must be number.

f, F

Floating-point value in decimal form

Value must be number.

g, G

Like e or E when exp is >=4 or < precision; otherwise, like f or F

exp is the exponent of the number being converted.


Single character

Value can be integer or single-character string.



Converts any value with repr.



Converts any value with str.


Literal % character

Consumes no value.

Between the % and the conversion character, you can specify a number of optional modifiers, as we'll discuss shortly.

The result of a formatting expression is a string that is a copy of format where each format specifier is replaced by the corresponding item of values converted to a string according to the specifier. Here are some simple examples:

x = 42
y = 3.14
z = "george"
print 'result = %d' % x                 # prints: result = 42
print 'answers are: %d %f' % (x,y)      # prints: answers are: 42 3.14
print 'hello %s' % z                    # prints: hello george

9.3.1. Format Specifier Syntax

A format specifier can include many modifiers to control how the corresponding item in values is converted to a string. The components of a format specifier, in order, are:

  • The mandatory leading % character that marks the start of the specifier

  • An optional item name in parentheses (e.g., (name))

  • Zero or more optional conversion flags:


    The conversion uses an alternate form (if any exists for its type).


    The conversion is zero-padded.


    The conversion is left-justified.

    A space

    A space is placed before a positive number.


    The numeric sign (+ or -) is placed before any numeric conversion.

  • An optional minimum width of the conversion: one or more digits, or an asterisk (*), meaning that the width is taken from the next item in values

  • An optional precision for the conversion: a dot (.) followed by zero or more digits, or by a *, meaning that the precision is taken from the next item in values

  • A mandatory conversion type from Table 9-1

Item names must be given either in all format specifiers in format or in none of them. When item names are given, values must be a mapping (often the dictionary of a namespace, e.g., vars( )), and each item name is a key in values. In other words, each format specifier corresponds to the item in values keyed by the specifier's item name. When item names are given, you cannot use * in any format specifier.

When item names are absent, values must be a tuple; when there is just one item, values may be the item itself (of any type except tuple) instead of a singleton tuple. Each format specifier corresponds to an item in values by position, and values must have exactly as many items as format has specifiers (plus one extra for each width or precision given by *). When the width or precision component of a specifier is given by *, the * consumes one item in values, which must be an integer and is taken as the number of characters to use as width or precision of the conversion.

9.3.2. Common String-Formatting Idioms

It is quite common for format to contain several occurrences of %s and for values to be a tuple with exactly as many items as format has occurrences of %s. The result is a copy of format where each %s is replaced with str applied to the corresponding item of values. For example:

'%s+%s is %s'%(23,45,23+45)              # results in: '23+45 is 68'

You can think of %s as a fast and concise way to put together a few values, converted to string form, into a larger string. For example:

oneway = 'x' + str(j) + 'y' + str(j) + 'z'
another = 'x%sy%sz' % (j, j)

After this code is executed, variables oneway and another will always be equal, but the computation of another, done via string formatting, is measurably faster. Which way is clearer and simpler is a matter of habit. I urge you to get used to the string-formatting idiom, and soon it will come to look simpler and clearer to you.

Besides %s, other reasonably common format specifiers are those used to format floating-point values: %f for decimal formatting, %e for exponential formatting, and %g for either decimal or exponential formatting, depending on the number's magnitude. When formatting floating-point values, you normally specify width and/or precision modifiers. A width modifier is a number right after the % that gives the minimum width for the resulting conversion; you generally use a width modifier if you're formatting a table for display in a fixed-width font. A precision modifier is a number following a dot (.) just before the conversion type letter; you generally use a precision modifier in order to fix the number of decimal digits displayed for a number to avoid giving a misleading impression of excessive precision and wasting display space. For example:

'%.2f'%(1/3.0)                          # results in: '0.33'
'%s'%(1/3.0)                            # results in: '0.333333333333'

With %s, you cannot specify how many digits to display after the decimal point. It is important to avoid giving a mistaken impression of high precision when your numeric results are accurate only to a few digits. Showing many digits may mislead people examining the results into believing the results are more accurate than is the case.

9.3.3. Template Strings

Python 2.4 introduced the class string.Template, which in some simple cases affords handier formatting facilities than strings' % operator.


class Template(template)

Builds and returns a new instance t of Template, with read-only attribute t.template set to the string argument template.

An instance t of Template supplies the following two methods.



Returns a string that is a copy of t.template with:

  • Each occurrence of $$ changed into a single $

  • Each occurrence of $identifier or ${identifier } (where identifier is any valid Python identifier that is a key into mapping and/or is one of the argument names in k) changed into mapping.update(**k)[identifier]

Occurrences of $identifier or ${identifier } (where identifier is not a valid Python identifier, or not a key into mapping nor one of the argument names in k) are just copied from t.template into the string result of safe_substitute.



Like safe_substitute, except that if there are any occurrences of $identifier or ${identifier } (where identifier is not a valid Python identifier, or not a key into mapping nor one of the argument names in k), substitute raises a KeyError exception.

For more advanced (and rarely needed) uses of string.Template, see all the details at

9.3.4. Text Wrapping and Filling

The textwrap module supplies a class and a few functions to format a string by breaking it into lines of a given maximum length. To fine-tune the filling and wrapping, you can instantiate the TextWrapper class supplied by module textwrap and apply detailed control. Most of the time, however, one of the two main functions exposed by module textwrap suffices.


wrap(s,width =70)

Returns a list of strings (without terminating newlines), each of which is no longer than width characters, and which (put back together with whitespaces) equal s. wrap also supports other named arguments (equivalent to attributes of instances of class TextWrapper); for such advanced uses, see


fill(s,width =70)

Returns a single multiline string that is exactly equal to '\n'.join(fill(s,width)).

Previous Page
Next Page