Value Selection

'[str]{[selector]}[str]'.format(*args, **kwargs)

The format selector can handle positional (automatic or numbered) and named arguments. The simplest replacement field is the empty pair of braces ({}). With no indication of which argument is to be interpolated, each such replacement field automatically refers to the value of the next positional argument to format:

>>> 'First: {} second: {}'.format(1, 'two')
'First: 1 second: two'

To repeatedly select an argument, or use it out of order, use the argument’s number to specify its position in the list of arguments:

>>> 'Second: {1} first: {0}'.format(1, 'two')
'Second: two first: 1'

You cannot mix automatic and numbered replacement fields: it’s an either-or choice. For named arguments, you can use argument names and mix them with (automatic or numbered) positional arguments:

>>> 'a: {a}, 1st: {}, 2nd: {}, a again: {a}'.format(1, 'two', a=3)
'a: 3, 1st: 1, 2nd: two, a again: 3'
>>> 'a: {a} first:{0} second: {1} first: {0}'.format(1, 'two', a=3)
'a: 3 first:1 second: two first: 1'

If an argument is a sequence, you can use numeric indexes within it to select a specific element of the argument as the value to be formatted. This applies to both positional (automatic or numbered) and named arguments.

>>> 'p0[1]: {[1]} p1[0]: {[0]}'.format(('zero', 'one'),
                                       ('two', 'three'))
'p0[1]: one p1[0]: two'
>>> 'p1[0]: {1[0]} p0[1]: {0[1]}'.format(('zero', 'one'), 
                                         ('two', 'three'))
'p1[0]: two p0[1]: one'
>>> '{} {} {a[2]}'.format(1, 2, a=(5, 4, 3))
'1 2 3'

If an argument is a composite object, you can select its individual attributes as values to be formatted by applying attribute-access dot notation to the argument selector. Here is an example using complex numbers, which have real and imag attributes that hold the real and imaginary parts, respectively:

>>> 'First r: {.real} Second i: {a.imag}'.format(1+2j, a=3+4j)
'First r: 1.0 Second i: 4.0'

Indexing and attribute-selection operations can be used multiple times, if required.

Value Conversion

You may apply a default conversion to the value via one of its methods. You indicate this by following any selector with !s to apply the object’s __str__ method, !r for its __repr__ method, or!a for the ascii built-in (v3 only).

If you apply any conversion, the converted value replaces the originally selected value in the remainder of the formatting process.

Value Formatting

'{[selector][conversion]:[format_specifier]}'.format(value)

The formatting of the value (if any further formatting is required) is determined by a final (optional) portion of the replacement field, following a colon (:), known as the format specifier. The absence of a colon in the replacement field means that the converted value is used with no further formatting. Format specifiers may include one or more of the following: fill, alignment, sign, #, width, comma, precision, type.

>>> s = 'a string'
>>> '{:^12s}'.format(s)
'  a string  '
>>> '{:.>12s}'.format(s)
'....a string'

print('{:,}'.format(12345678))
# prints 12,345,678

>>> s = 'a string'
>>> x = 1.12345 
>>> 'as f: {:.4f}'.format(x) 
'as f: 1.1235' 
>>> 'as g: {:.4g}'.format(x) 
'as g: 1.123'
>>> 'as s: {:.6s}'.format(s)
'as s: a stri'

>>> n = [3.1415, -42, 1024.0] 
>>> for num in n:
...     '{:>+9,.2f}'.format(num)
... 
'    +3.14'
'   -42.00'
'+1,024.00'

>>> s = 'a string'
>>> '{0:>{1}s}'.format(s, len(s)+4)
'    a string'
>>> '{0:_^{1}s}'.format(s, len(s)+4)
'__a string__'

def print_strings_in_columns(seq_of_strings, widths):
    for cols in seq_of_strings:
        row = ['{c:{w}.{w}s}'.format(c=c, w=w)
               for c, w in zip(cols, widths)]
        print(' '.join(row))

c = [
        'four score and'.split(),
        'seven years ago'.split(),
        'our forefathers brought'.split(),
        'forth on this'.split(),
    ]

print_strings_in_columns(c, (8, 8, 8))

four     score    and     
seven    years    ago     
our      forefath brought 
forth    on       this    

>>> object().__format__('')
'<object object at 0x110045070>'
>>> math.pi.__format__('18.6')
'           3.14159'

>>> class S(object):
...     def __format__(self, fstr):
...         print('Format string:', fstr)
...         return '42'
...
>>> my_s = S()
>>> '{:format_string}'.format(s)
Format string: format string
'42'
>>> 'The formatted value is: {:anything you like}'.format(s)
Format string: anything you like
'The formatted value is: 42'

New in 3.6: Formatted String Literals

This new feature helps use the formatting capabilities just described. It uses the same formatting syntax, but lets you specify expression values inline rather than through parameter substitution. Instead of argument specifiers, f-strings use expressions, evaluated and formatted as specified. For example, instead of:

>>> name = 'Dawn'
>>> print('{name!r} is {l} characters long'
           .format(name=name, l=len(name)))
'Dawn' is 4 characters long

from 3.6 onward you can use the more concise form:

>>> print(f'{name!r} is {len(name)} characters long')
'Dawn' is 4 characters long

You can use nested braces to specify components of formatting expressions:

>>> for width in 8, 11:
...     for precision in 2, 3, 4, 5:
...         print(f'{3.14159:{width}.{precision}}')
...
     3.1
    3.14
   3.142
  3.1416
        3.1
       3.14
      3.142
     3.1416

Do remember, though, that these string literals are not constants—they evaluate each time a statement containing them runs, potentially implying runtime overhead.

Legacy String Formatting with %

A legacy form of string formatting expression in Python has the syntax:

format % values

where format is a string containing format specifiers and values are the values to format, usually as a tuple (in this book we cover only the subset of this legacy feature, the format specifier, that you must know to properly use the logging module, covered in “The logging package”).

The equivalent use in logging would be, for example:

logging.info(format, *values)

with the values coming as positional arguments after the first, format one.

The legacy string-formatting approach 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 8-6.

The r, s, and % conversion characters are the ones most often used with the logging module. Between the % and the conversion character, you can specify a number of optional modifiers, as we’ll discuss shortly.

What is logged with a formatting expression is 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:

import logging
logging.getLogger().setLevel(logging.INFO)
x = 42
y = 3.14
z = 'george'
logging.info('result = %d', x)        # logs: result = 42
logging.info('answers: %d %f', x, y)  # logs: answers: 42 3.140000
logging.info('hello %s', z)           # logs: hello george

Format Specifier Syntax

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

1. The mandatory leading % character that marks the start of the specifier

2. Zero or more optional conversion flags:

   #

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

   0

   The conversion is zero-padded.

   -

   The conversion is left-justified.

   A space

   A space is placed before a positive number.

   +

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

3. 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

4. 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

5. A mandatory conversion type from Table 8-6

Each format specifier corresponds to an item in values by position, and there must be exactly as many values as format has specifiers (plus one extra for each width or precision given by *). When a width or precision 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 that conversion.

The codecs Module

The mapping of codec names to codec objects is handled by the codecs module. This module also lets you develop your own codec objects and register them so that they can be looked up by name, just like built-in codecs. The codecs module also lets you look up any codec explicitly, obtaining the functions the codec uses for encoding and decoding, as well as factory functions to wrap file-like objects. Such advanced facilities of the module codecs are rarely used, and we do not cover them in this book.

The codecs module, together with the encodings package of the standard Python library, supplies built-in codecs useful to Python developers dealing with internationalization issues. Python comes with over 100 codecs; a list of these codecs, with a brief explanation of each, is in the online docs. It’s technically possible to install any supplied codec as the site-wide default in the module sitecustomize, but this is not good practice: rather, the preferred usage is to always specify the codec by name whenever you are converting between byte and Unicode strings. The codec installed by default in v2 is 'ascii', which accepts only characters with codes between 0 and 127, the 7-bit range of the American Standard Code for Information Interchange (ASCII) that is common to almost all encodings. A popular codec in Western Europe is 'latin-1', a fast, built-in implementation of the ISO 8859-1 encoding that offers a one-byte-per-character encoding of special characters found in Western European languages (note that 'latin-1' lacks the Euro currency character '€'; if you need that, use 'iso8859-15').

The codecs module also supplies codecs implemented in Python for most ISO 8859 encodings, with codec names from 'iso8859-1' to 'iso8859-15'. For example, if you use ASCII plus some Greek letters, as is common in scientific papers, you might choose 'iso8859-7'. On Windows systems only, the codec named 'mbcs' wraps the platform’s multibyte character set conversion procedures. Many codecs specifically support Asian languages. The codecs module also supplies several standard code pages (codec names from 'cp037' to 'cp1258'), old Mac-specific encodings (codec names from 'mac-cyrillic' to 'mac-turkish'), and Unicode standard encodings 'utf-8' (likely to be most often the best choice, thus recommended, and the default in v3) and 'utf-16' (the latter also has specific big-endian and little-endian variants: 'utf-16-be' and 'utf-16-le'). For use with UTF-16, codecs also supplies attributes BOM_BE and BOM_LE, byte-order marks for big-endian and little-endian machines, respectively, and BOM, the byte-order mark for the current platform.

The codecs module also supplies a function to let you register your own conversion-error-handling functions, as described in Table 8-7.

The codecs module also supplies a function to help with files of encoded text:

import sys, codecs
sys.stdout = codecs.EncodedFile(sys.stdout,'latin-1',
'utf-8')

It’s normally sufficient to use, instead, io.open, covered in “Creating a “file” Object with io.open”.

The unicodedata Module

The unicodedata module supplies easy access to the Unicode Character Database. Given any Unicode character, you can use functions supplied by unicodedata to obtain the character’s Unicode category, official name (if any), and other, more exotic information. You can also look up the Unicode character (if any) that corresponds to a given official name. Such advanced facilities are rarely needed, and we do not cover them further in this book.