Formatting Strings

bogotobogo.com site search:

Formatting Strings

Two flavors of string formatting:

string formatting expressions: this is based on the C type printf.
string formatting method calls: this is newer and added since Python 2.6.

String formatting by expressions

% operator

The % provides a compact way to code several string substitutions all at once.

>>> 'I am using %s %d.%d' %('Python', 3, 2)
'I am using Python 3.2'

Format specification

Code	Meaning
b	Binary format. Outputs the number in base 2.
c	Character. Converts the integer to the corresponding unicode character before printing.
d	Decimal Integer. Outputs the number in base 10. Default.
e, E	Exponent notation. Prints the number in scientific notation using the letter e/E to indicate the exponent.
f, F	Fixed point. Displays the number as a fixed-point number.
g	General format. For a given precision p >= 1, this rounds the number to p significant digits and then formats the result in either fixed-point format or in scientific notation, depending on its magnitude. The precise rules are as follows: suppose that the result formatted with presentation type e and precision p-1 would have exponent exp. Then if -4 <= exp < p, the number is formatted with presentation type f and precision p-1-exp. Otherwise, the number is formatted with presentation type e and precision p-1. In both cases insignificant trailing zeros are removed from the significant, and the decimal point is also removed if there are no remaining digits following it. Positive and negative infinity, positive and negative zero, and nans, are formatted as inf, -inf, 0, -0 and nan respectively, regardless of the precision. A precision of 0 is treated as equivalent to a precision of 1. Default.
G	General format. Same as g except switches to E if the number gets too large. The representations of infinity and NaN are uppercased, too.
n	Number. This is the same as g, except that it uses the current locale setting to insert the appropriate number separator characters.
o	Octal format. Outputs the number in base 8.
s	String format. This is the default type for strings and may be omitted.
x, X	Hex format. Outputs the number in base 16, using lower/upper- case letters for the digits above 9.
%	Percentage. Multiplies the number by 100 and displays in fixed (f) format, followed by a percent sign.

Target syntax format

The example below is using left justification(-) and zero(0) fills.

>>> n = 6789
>>> a = "...%d...%-6d...%06d" %(n, n, n)
>>> a
'...6789...6789  ...006789'
>>>
>>> m = 9.876543210
>>> '%e | %E | %f | %g' %(m, m, m, m)
'9.876543e+00 | 9.876543E+00 | 9.876543 | 9.87654'
>>>

For floating point number, in the following example, we're using left justification, zero padding, numeric + signs, field width, and digits after the decimal point.

>>> '%6.2f | %05.2f | %+06.1f' %(m, m, m)
'  9.88 | 09.88 | +009.9'

We can simply convert them to string using a format expression or str built-in function:

>>> '%s' % m, str(m)
('9.87654321', '9.87654321')

In case when the sizes are unknown until runtime, we can have the width and precision computed by specifying them with a * in the format string to force their values to be taken from the next item in the inputs to the right of the %. In the example, the 4 in the tuple gives precision:

>>> '%f, %.3f, %.*f' % (9.87654321, 9.87654321, 4, 9.87654321)
'9.876543, 9.877, 9.8765'

Formatting dictionary strings

Targets on the left can refer to the keys in a dictionary on the right so that they can fetch the corresponding values. In the example below, the (m) and (w) in the format string refers to the keys in the dictionary on the right and fetch their corresponding values.

>>> '%(m)d %(w)s' %{'m':101, 'w':'Freeway'}
'101 Freeway'

We can build a dictionary of values and substitute them all at once with a single formatting expression that uses key-based references. This technique can be used to generate text:

>>> greetings = '''
Hello %(name)s!
Merry Christmas.
I hope %(year)d will be a good year.
'''
>>> replace = {'name' : 'Scala', 'year' : 2013}
>>> print(greetings % replace)

Hello Scala!
Merry Christmas.
I hope 2013 will be a good year.

As an another example, we can use it for build-in function, vars():

>>> language = 'Python'
>>> version = 320
>>> vars()
{'language': 'Python', '__builtins__': , 
'__package__': None, 'version': 320, '__name__': '__main__', '__doc__': None}
>>> '%(language)s %(version)d' % vars()
'Python 320'

String formatting by method calls

Unlike formatting using expressions which is based on C's printf, string formatting using method calls is regarded as more Python-specific.

Template basics

This new string object's format method uses the subject string as a template and takes any number of arguments that represent values to the substituted according to the template. Within the subject string, curly braces designate substitution targets and arguments to be inserted either by position such as {1} or keyword such as language.

>>> # By position
>>> t = '{0}, {1}, {2}'
>>> t.format('Dec', '29', '2013')
'Dec, 29, 2013'
>>>
>>> # By keyword
>>> t = '{Month}, {Day}, {Year}'
>>> t.format(Month='Dec', Day='29', Year='2013')
'Dec, 29, 2013'
>>>
>>> # Mixed
>>> t = '{Year}, {Month}, {0}'
>>> t
'{Year}, {Month}, {0}'
>>> t.format('29', Year='2013', Month='Dec')
'2013, Dec, 29'
>>>

Arbitrary object type can be substituted from a temporary string:

>>> '{Month}, {Year}, {0}'.format('29', Month=['Nov', 'Dec'], Year='2013')	  
"['Nov', 'Dec'], 2013, 29"

Formatting with keys and attributes

Format strings can name object attributes and dictionary keys. Square brackets name dictionary keys and dots denote object attributes of an item referenced by position or keyword.

>>> import sys
>>>
>>> 'My {0[Machine]} is running {1.platform}'.format({'Machine': 'notebook'}, sys)
'My notebook is running win32'
>>>
>>> 'My {config[Machine]} is running {sys.platform}'.format(config={'Machine':'notebook'}, sys=sys)
'My notebook is running win32'

In the example above, the first one indexes a dictionary on the key Machine and then fetches the attribute platform from the imported sys module. Though the 2nd case in the example is doing the same thing, but names the objects by keyword not by its position.

Working with specific formatting

By adding extra syntax in the format string, we can achieve more specific layouts similar to the % expressions.

{fieldName!conversionFlag:formatSpecification}

For the formatting method, we can use a colon after the substitution target's identification, followed by a format specifier that can name the field size, justification, and a specific type code.

fieldName is a number or keyword naming an argument, followed by optional .name attribute or [index] references.
conversionFlag can be r, s, or a to call repr, str, or ascii built-in functions on the value, respectively.
formatSpecification specifies how the value should be presented.

The alignment for the formatSpecification can be <. >, =, or ^, for left alignment, right alignment, padding after a sign character, or centered alignment, respectively.

>>> '{0:10} = {1:5}'.format(3.1415, 'pi')
'    3.1415 = pi   '
>>> '{0:15} = {1:10}'.format(3.1415, 'pi')
'         3.1415 = pi        '
>>> '{0:<15} = {1:>10}'.format(3.1415, 'pi')
'3.1415          =         pi'
>>>
>>> '{0.platform:>10} is the platform of my {1[item]:<10}'.format(sys, dict(item='notebook'))
'     win32 is the platform of my notebook  '
>>>

The following example shows the specification for floating point numbers:

>>> '{0:e},{1:3e},{2:g},{3:f},{4:.2f},{5:06.2f}'.format(3.1415,3.1415,3.1415,3.1415,3.1415,3.1415)
'3.141500e+00,3.141500e+00,3.1415,3.141500,3.14,003.14'
>>>

The following example is for the review of formatting we've discussed so far:

# byte.py
UNITS = ['KB', 'MB', 'GB', 'TB', 'PB']

def sizeInByte(sz):
    if sz < 0:
        raise ValueError('number < 0')

    factor = 1024 
    for i in range(len(UNITS)):
        if sz < factor:
            if i == 0:
                return '{0:.1f} {1[0]}'.format(sz, UNITS)
            elif i == 1:
                return '{0:.1f} {1[1]}'.format(sz, UNITS)
            elif i == 2:
                return '{0:.1f} {1[2]}'.format(sz, UNITS)
            elif i == 3:
                return '{0:.1f} {1[3]}'.format(sz, UNITS)
            else:
                return '{0:.1f} {1[4]}'.format(sz, UNITS)
        else:
            sz /= factor

    raise ValueError('too big')

After importing the module, we get the following output from the interactive shell:

>>> from byte import sizeInByte
>>> sizeInByte(10000)
'9.8 MB'
>>> sizeInByte(100000000)
'95.4 GB'
>>> sizeInByte(10000000000000)
'9.1 PB'
>>> sizeInByte(1000000000000000000000)
Traceback (most recent call last):
  File "", line 1, in 
  File "byte.py", line 23, in sizeInByte
    raise ValueError('too big')
ValueError: too big
>>>

The first specification {0:.1f} is for the sz and the second one {1[0]} is for the 'KB' in UNITS list. Note that we used index to the UNITS list to get the proper byte unit. As a foot note, I try to use the variable i for the units such as {1[i]}. But I could not make it work and got an error: "list indices must be integers."