String Formatting in

About String Formatting

String Formatting in Python

String formatting is the process of converting values to strings and inserting them into a string template. The Zen of Python asserts there should be "one obvious way to do something in Python". But when it comes to string formatting, things are a little ... less zen. It can be surprising to find out that there are four main ways to perform string formatting in Python - each for a different scenario. Some of this is due to Python's long history and some of it is due to considerations like internationalization or input sanitation. We will start with the most recent additions to the string formatting toolbox and work our way backward to "old style" or "printf() style" string formatting.

literal string interpolation: The f-string

Introduced in Python 3.6, f-strings (short for "formatted-strings") or literal string interpolation are a way of quickly and efficiently evaluating and formatting expressions and strings to a str type using the f (or F) prefix before the brackets (like so f'{object}'). They can be used with all enclosing string types as: single-line ' or " and with multi-lines ''' or """. Any variables, expressions, or other types placed inside the {} are first evaluated, then converted to a str, then concatenated with any str outside the curly braces.

In this example, we insert two variable values in the sentence: one str and one float:

>>> name = 'eighth'
>>> value = 1/8
...
# The f-string, using the two values.
# The .2f format code truncates so the value displays as 0.12.
>>> f'An {name} is approximately {value:.2f}.'
'An eighth is approximately 0.12.'

The expressions evaluated can be almost anything. Some of the (wide range) of possibilities that can be evaluated: str, numbers, variables, arithmetic expressions, conditional expressions, built-in types, slices, functions, lambdas, comprehensions or any objects with either __str__ or __repr__ methods defined.

Some examples:

# A dictionary of key:value pairs.
>>> waves = {'water': 1, 'light': 3, 'sound': 5}

# Using the name waves in an f-string.
>>> f'"A dict can be represented with f-string: {waves}."'
'"A dict can be represented with f-string: {\'water\': 1, \'light\': 3, \'sound\': 5}."'

# Here, we pull a value from the dictionary by using the key
>>> f'Tenfold the value of "light" is {waves["light"] * 10}.'
'Tenfold the value of "light" is 30.'

Replacement fields (the {} in the f-string) support output control mechanisms such as width, alignment, precision. This specification is started in the format specification mini-language.

A more complex example of an f-string that includes output control:

# Assigning variables
>>> precision = 3
>>> verb = "see"
>>> the_end = ['end', 'of', 'transmission']

# Reassigning verb to 'meet'.
>>> verb = 'meet'

# This example includes a function, str, a nested f-string, an arithmetic expression, 
# precision formatting, bracket escaping and object formatting.
>>> f'"Have a {"NICE".lower()} day, I will {verb} you after {f"{30e8 * 111_000:6.{precision}e}"} light-years."{{{the_end}}}'
'"Have a nice day, I will meet you after 3.330e+14 light-years."{[\'end\', \'of\', \'transmission\']}'

There are a few limitations to be aware of. f-string expressions cannot be empty, they cannot contain comments.

>>> f"An empty expression will error: {}"
SyntaxError: f-string: empty expression not allowed

>>> word = 'word'
>>> f"""A comment in a triple quoted f-string will error: {
    word # I chose a nice variable
}"""
SyntaxError: f-string expression part cannot include '#'

The str.format() Method

The str.format() method replaces placeholders within the string with values fed as arguments to the function. The placeholders are identified with named ({price}), numbered ({0} or indexed) or even empty (positional) placeholders {}. For example:

# A named placeholder and a positional placeholder.
>>> 'My text: {placeholder_1} and {}.'.format(12, placeholder_1='named placeholder')
'My text: named placeholder and 12.'

As with f-strings, Pythons str.format() supports a whole range of mini language format specifier that can be used to align text, convert, etc.

The complete formatting specifier pattern is {[<name>][!<conversion>][:<format_specifier>]}:

• <name> can be a named placeholder or a number or empty.
• !<conversion> is optional and should be one of this three conversions: !s for str(), !r for repr() or !a for ascii(). By default, str() is used.
• :<format_specifier> is optional and has a lot of options, which we are listed here.

Example of conversions for a diacritical letter:

# Fills in the object at index zero, converted to a string.
>>> 'An e with an umlaut: {0!s}'.format('ë')
'An e with an umlaut: ë'


# Fills in the object at index zero, converted to a repr.
>>> 'An e with an umlaut object representation: {0!r}'.format('ë')
"An e with an umlaut object representation: 'ë'"

...

# Fills in the object at index zero, converted to ascii
>>> 'An e with an umlaut converted into ascii: {0!a}'.format('ë')
"An e with an umlaut converted into ascii: '\xeb'"


# Fills in the object in the first position.
# Then fills in the object in the second position formatted as a repr
>>> 'She said her name is not {} but {!r}.'.format('Chloe', 'Zoë')
"She said her name is not Chloe but 'Zoë'."

Example of using format specifiers:

# Formats the object at index 0 as a decimal with zero places, 
# then as a right-aligned binary number in an 8 character wide field.
>>> "The number {0:d} has a representation in binary: '{0: >8b}'.".format(42)
"The number 42 has a representation in binary: '  101010'."

More examples are shown at the end of this documentation.

% Formatting, or printf() Style Formatting

Use of the % operator for formatting is the oldest method of string formatting in Python. It comes from the C language and allows the use of positional arguments to build a str.

This method has been superseded by both f-strings and str.format(), which is why the nickname for % formatting is 'Old Style'. It can be still found in Python 2 and/or legacy code. While using this method will work in Python 3.x, % formatting is usually avoided because it can be error-prone, is less efficient, has fewer options available, and any placeholder-argument mismatch can raise an exception. Using the % operator is similar to printf(), so it is also sometimes called printf formatting.

# Assigning a variable.
>>> name = "Anna-conda"

# Building a string using %
>>> "The snake's name is %s." % name
"The snake's name is Anna-conda."

In the example above, the % operator substitutes the placeholder %s with the variable name at runtime. If you want to add multiple variables to a string, you need to supply a tuple containing one object per placeholder after the %:

# Assigning variables
>>> name = "Billy the Kid"
>>> fruit = "grapes"

# Building a string using %
>>> "Surprisingly, %ss favorite snack was %s." %(name, fruit)
"Surprisingly, Billy the Kids favorite snack was grapes."

Template Strings

string.Template() is a class from the string module (as opposed to the built-in str type), which is part of the Python standard library, but has to be imported for use. Template strings support $-based substitution and are much simpler and less capable than the other options mentioned here, but can be very useful for when complicated internationalization is needed, or outside inputs need to be sanitized.

>>> from string import Template

>>> name = "Anna-Conda"

# Creating a Template() with placeholder text
>>> template_string = Template("The snake called `$snake_name` has escaped!")

# Calling .substitute() to replace the placeholder with a value.
>>> template_string.substitute(snake_name=name)
'The snake called `Anna-Conda` has escaped!'

More information about Template string can be found in the Python documentation.

How Do You Choose which Formatting Method to Use?

With all these options and mini-languages, how do you decide what to reach for when formatting Python strings? A few quick guidelines:

1. f-strings are the newest and easiest to read. If you don't need to internationalize, they should be the Python 3.6+ preferred method.
2. str.format() is versatile, very powerful and compatible with both gnu gettext and most versions of Python.
3. If simplicity, safety, and/or heavy internationalization is what you need, string.Template() can be used to mitigate risks when inputs from users need to be handled, and for wrapping translation strings.
4. The % operator is not supported in some newer distributions of Python and should mostly be used for compatibility with old code. % formatting` can lead to issues displaying non-ascii and unicode characters and has more errors and less functionality than other methods.

If you want to go further: all about formatting and Python String Formatting Best Practices are good places to start.