9.3. String Formatting
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.
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:
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.
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.