String Formatting

To produce a formatted value or set of values, you create a string to be used as a format, then call the string's format() method. The format string can be made up of literal text (which becomes part of the formatted string) and replacement fields. The replacement fields are surrounded by curly brackets ({ }). You provide the values you want to format as arguments to the method. The values are interpolated into the format string to produce a formatted string, which becomes the result of the method call. The replacement fields contain either the position or the name of the argument whose value should be used (you'll learn more about named arguments later).

Let's look at some of the capabilities that this offers. Start an interactive session and enter the following commands to see how formatting works:

>>> "{2}, {1}, and {0}".format("George", "Paul", "John")
'John, Paul, and George'
>>> "{who} is a smart {what}".format(what='cookie', who='Sylvia')
'Sylvia is a smart cookie'
>>> "The fifth element of the first argument is {0[5]}".format(
...     ["Dallas", "Zorg", "Cornelius", "Ruby", "Billy", "Leelo"])
'The fifth element of the first argument is Leelo'
>>> d = {'Cher': "Sarkisian", 'Sonny': "Bono"}
>>> "Sonny's surname is {0[Sonny]}".format(d)
"Sonny's surname is Bono"
>>> "Cher's surname is {lookup[Cher]}".format(lookup=d)
"Cher's surname is Sarkisian"
>>> for first, last in d.items():
...     print("{0:10} {1:10}".format(first, last))
...
Cher       Sarkisian
Sonny      Bono
>>> fmt = "{0:>6} = {0:>#16b} = {0:#06x}"
>>> for i in 1, 23, 456, 7890:
...   print(fmt.format(i))
...
     1 =              0b1 = 0x0001
    23 =          0b10111 = 0x0017
   456 =      0b111001000 = 0x01c8
  7890 =  0b1111011010010 = 0x1ed2

You can see that Python has some very powerful string-formatting capabilities. Now we need to understand the rules and ways to write formats that will give us the output we want. We'll go over these rules in the next few sections.

The curly brackets play a vital role in formatting strings. Each sequence of characters surrounded by a pair of curly brackets is replaced by some representation of an argument to the format() method.

The format() method, like all Python functions, can be called with two types of argument. The first type, and the one you are most familiar with, is called positional, because it is identified by the position it occupies in the argument list. The second type is called keyword; it's preceded by a name and an equals sign.

If a call has any positional arguments, they must always appear before any keyword arguments. Thus, "...".format(a, b, k1=c, k2=d) is legal, but "...".format(k1=c, k2=d, a, b) is not (it will be flagged as a syntax error by the interpreter).

The arguments to the format() method call are the values to be formatted. The format string on which the method is called specifies how the values are to be represented, by including replacement fields. Other text in the format string (that does not appear between curly brackets) is simply copied to the output literally.

The first part of the replacement field, immediately following the opening curly bracket, is the field name. This tells the formatting engine which value is to be formatted. The field name begins with either a number, which specifies a positional argument to the format() method, or a name, which specifies a named argument. This can be followed by extra information that allows you to index the selected argument (which will presumably be an indexable object such as a list, tuple, or dict) or access one of its attributes.

Let's experiment now and get more comfortable programming by writing a slightly unusual program. Usually we expect to provide variable data to a program and format its results in a standard way. This time we'll provide you with standard data and let you enter format specifications that will select specific elements for display.

Type the following code as shown:

"""Accept format strings from the user and format fixed data."""
i = 42
r = 31.97
c = 2.2 + 3.3j
s = "String"
lst = ["zero", "one", "two", "three", "four", "five"]
dct = {"Jim": "Dandy",
     "Stella": "DuBois",
     1: "integer"}

while True:
    fmt = input("Format string: ")
    if not fmt:
        break
    fms = "{"+fmt+"}"
    print("Format:", fms, "output:", fms.format(i, r, c, s, e=lst, f=dct))

Save it in your /python1 folder as formatting.py and run it; verify that you get the answers shown for the inputs given in the following table:

To exit the program, press Enter. The program takes whatever you enter, wraps it inside curly brackets, and uses the constructed string as a formatting string against four positional arguments and two keyword arguments. The print() call will only output a single value, but you can vary the format to get all kinds of results.

The formatting mechanism has some pretty sophisticated ways to select what is formatted. Now let's see about actually formatting the selected value. We do that by following the field name with a colon and a format specification. This can include details about the filling mechanism to be used, how the output is to be aligned in the field, how to treat the signs of numbers, how wide the field should be, how many digits of precision to allow, or what type of conversion should be performed on the selected value.

The various components of the format specification must appear in a prescribed order. No component is required.

>>> "{0:15.5}".format(987.654)
'         987.65'
>>> "{0:15.5}".format(98765.432)
'     9.8765e+04'

The field width and the precision are numeric values. If you want these values to be reliant on program data, you can pass the width and precision as arguments to the format() method and then use a nested field name inside the format specification. This nested field name (which must refer to an integer value) is substituted for the field width or precision as the formatting takes place. So, for example, "{0:{1}.{2}f}".format(1234.5678, 18, 3) displays the number 1234.5678 to three decimal places in a field 18 characters wide.

Let's try a few examples. Start up an interactive session and enter the commands shown:

>>> "{0:010.4f}".format(-123.456)
'-0123.4560'
>>> "{0:+010.4f}".format(-123.456)
'-0123.4560'
>>> for i in 1, 2, 3, 4, 5:
...   "{0:10.{1}f}".format(123.456, i)
...
'     123.5'
'    123.46'
'   123.456'
'  123.4560'
' 123.45600'
>>> n = {'value': 987.654, 'width': 15, 'precision': 5}
>>> "{0[value]:{0[width]}.{0[precision]}}".format(n)
'         987.65'

The numerical rounding is always correct. And by using dict access, you can carry the value, field width, and precision (along with other values you might need) all within a single object.

This example program lists the names, ages, and weights of a number of individuals. Currently the data is stored as a list of tuples. We'll list the data using formatting statements. Enter this code in the editor window:

"""Produce a listing of people's names, ages and weights."""
data = [
        ("Steve", 59, 202),
        ("Dorothy", 49, 156),
        ("Simon", 39, 155),
        ("David", 61, 135)]
for row in data:
    print("{0[0]:<12s} {0[1]:4d} {0[2]:4d}".format(row))

Save it in your /python1 folder as personlist.py and run it. While this program works, the correspondence between related data items seems a little obscure. Modify the program as shown below to extract the individual items from the row and pass them as separate arguments to the format() call:

"""Produce a listing of people's names, ages and weights."""
data = [
        ("Steve", 59, 202),
        ("Dorothy", 49, 156),
        ("Simon", 39, 155),
        ("David", 61, 135)]
for roname, age, weight in data:
    print("{0[0]:<12s} {0[1]:4d} {0[2]:4d}".format(roname, age, weight))

Save and run it again. The results are the same, but which code do you think is easier to read? Readability is incredibly important in software: the easier code is to read the easier it is to understand. This applies not only to other readers, but also to you. When you return to a program after a considerable length of time, you don't want it to be a puzzle to understand.

Okay, now let's make the name field wider. We'll use the period as a pad character to help the reader follow the line from the name to the age and weight. Modify the program a third time—add a padding character before the alignment indication and increase the field width:

"""Produce a listing of people's names, ages and weights."""
data = [
        ("Steve", 59, 202),
        ("Dorothy", 49, 156),
        ("Simon", 39, 155),
        ("David", 61, 135)]
for name, age, weight in data:
    print("{0:.<1230s} {1:4d} {2:4d}".format(name, age, weight))

Save and run it again.

You've learned so much about Python's formatting features! They can really help make the output from your programs readable and usable.

In the next lesson, we'll return to functions and talk about the role of keyword arguments and parameters like the ones we used with the string format() method in this lesson.

See you there!