Python's Format Mini-Language for Tidy Strings

Using String Interpolation and Replacement Fields

When you’re working with strings, it’s common that you need to embed or insert values and objects into your strings so that you can build new strings dynamically. This task is commonly known as string interpolation.

In Python, you’ll find three popular tools that allow you to perform string interpolation:

1. The modulo operator (%)
2. The str.format() method
3. F-string literals

The modulo operator is sort of an old-fashioned tool. It was the first string interpolation tool in Python. Unfortunately, it doesn’t provide many string formatting features. So, in this tutorial, you’ll focus on the str.format() method and f-strings.

To dynamically interpolate a value into a string, you need something called replacement fields. In both str.format() and f-strings, curly braces ({}) delimit replacement fields. Inside these braces, you can put a variable, expression, or any object. When you run the code, Python replaces the field with the actual value.

Anything not contained in braces is considered literal text, and Python copies it unchanged to the output.

In the following sections, you’ll learn how replacement fields work in str.format() and f-strings.

>>> "Hello, {}!".format("Pythonista")
'Hello, Pythonista!'

>>> "Hello, {0}! Good {1}!".format("Pythonista", "morning")
'Hello, Pythonista! Good morning!'

>>> "Hello, {name}! Good {moment}!".format(
...    name="Pythonista", moment="morning"
... )
'Hello, Pythonista! Good morning!'

replacement_field ::=  "{"
                            [field_name]
                            ["!" conversion]
                            [":" format_spec]
                       "}"

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __str__(self):
        return f"I'm {self.name}, and I'm {self.age} years old."

    def __repr__(self):
        return f"{type(self).__name__}(name='{self.name}', age={self.age})"

>>> from person import Person

>>> jane = Person("Jane Doe", 25)

>>> "Hi! {!s}".format(jane)
"Hi! I'm Jane Doe, and I'm 25 years old."

>>> "An instance: {!r}".format(jane)
"An instance: Person(name='Jane Doe', age=25)"

>>> name = "Pythonista"
>>> moment = "morning"

>>> f"Hello, {name}! Good {moment}!"
'Hello, Pythonista! Good morning!'

replacement_field ::=  "{"
                             f_expression
                             ["="]
                             ["!" conversion]
                             [":" format_spec]
                       "}"

>>> from person import Person

>>> jane = Person("Jane Doe", 25)

>>> f"Hi! {jane!s}"
"Hi! I'm Jane Doe, and I'm 25 years old."

>>> f"An instance: {jane!r}"
"An instance: Person(name='Jane Doe', age=25)"

Understanding the Python Format Mini-Language

You can use format specifiers within replacement fields to format the object that you want to interpolate into your strings. In general, an empty format specifier produces the same result as if you had called str() with the value as an argument. Meanwhile, a non-empty format specification typically modifies the result.

The syntax to define working format specifiers is a bit involved. Because of that, the syntax is considered a whole mini-language. Here’s the BNF notation that defines it:

format_spec     ::=  [[fill]align][sign]["z"]["#"]["0"][width]
                     [grouping_option]["." precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
type            ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" |
                     "G" | "n" | "o" | "s" | "x" | "X" | "%"

The first BNF rule defines the general syntax, while the following rules define every independent field. For example, the fill field accepts any character. The align field can be one of the following characters: <, >, =, or ^. The rest of the rules have other possible values as well.

Reading and understanding the BNF notation can be challenging. So, in the following sections, you’ll learn how all the above fields work in practice and how you can combine them to create a suitable format specifier. To kick things off, you’ll start with the fields closely related to the output alignment.

Aligning and Filling the Output

When you start writing your own format specifiers, you’ll find that the fill, width, and align fields are closely related. With them, you can align the interpolated value in the final string.

The width field provides the working space, which consists of a given number of allowed characters. The align field allows you to position the interpolated value within the working space. Finally, the fill field lets you fill out the leftover space with the character of your preference.

To provide a value to fill, you can use any character. Python will use this character to fill the space around the interpolated value. Similarly, to provide a value to width, you can use an integer number.

The align field requires a bit of explanation, which you’ll find in the following table:

These alignment values allow you to control how a given value is displayed in the resulting string. To illustrate how the fill, width, and align fields work in practice, consider the following examples:

>>> text = "Hello!"

>>> # width=30
>>> f"{text:30}"
'Hello!                        '

>>> # align="<" and width=30
>>> f"{text:<30}"
'Hello!                        '

>>> # align="^" and width=30
>>> f"{text:^30}"
'            Hello!            '

>>> # align=">" and width=30
>>> f"{text:>30}"
'                        Hello!'

>>> # fill="=", align="^" and width=30
>>> f"{text:=^30}"
'============Hello!============'

With the width field, you can define the number of total characters that your replacement field will have. In this example, you use a width of 30 characters in total. The following three examples use different align values to align the word "Hello!" to the left, center, and right within the space defined by the width field.

In the final example, you use an equal sign (=) to fill the space on both sides of the interpolated value. How does that look?

Note that you need to follow the specified order of fields for your format specifier to work. As the syntax defines, you need to have fill, align, and then width, in that order. If you violate the order, then you get an error:

>>> f"{text:30>}"
Traceback (most recent call last):
    ...
ValueError: Unknown format code '>' for object of type 'str'

In this case, you place the width field before the align field. This ordering causes Python to raise a ValueError exception.

Converting Between Type Representations

A common requirement when you’re formatting your strings with format specifiers is to display an object using a different type representation. To represent string values, you can use the s representation type. Because this is the default, you can also omit it:

>>> name = "Pythonista"

>>> f"Hello, {name:s}!"
'Hello, Pythonista!'

>>> f"Hello, {name:}!"
'Hello, Pythonista!'

In this example, you use the s representation type to display a string. Note that if you provide the s representation type, then your format specifier won’t accept other types:

>>> f"{42:s}"
Traceback (most recent call last):
    ...
ValueError: Unknown format code 's' for object of type 'int'

When you set the s representation type in a format specifier, then you’ll get a ValueError when you try to pass an object of a different type, like the integer value in the above example.

When it comes to numeric values, you may want to display an integer value as a hexadecimal value or maybe as a binary value. To achieve this, the format mini-language offers you several type modifiers. The available type modifiers for representing integer values are the following, with decimal (d) as the default:

You can convert integer values using different representation types with all these type modifiers. Note that you shouldn’t confuse None in the table above with Python’s None object. In this context, None means that you can omit the type specifier.

Here’s a small example:

>>> number = 42

>>> f"int: {number:d},  hex: {number:x},  oct: {number:o},  bin: {number:b}"
'int: 42,  hex: 2a,  oct: 52,  bin: 101010'

This f-string uses different type modifiers to convert an integer number to other types. Note that the type modifiers do the hard work for you, converting the value from one representation to another.

The type modifiers that you saw above aren’t the only ones available in Python’s format mini-language. It also provides modifiers for decimal types:

You can use the above type modifiers to express floating-point numbers using different representations. Here are a few toy examples of how these modifiers work in practice:

>>> large = 1234567890
>>> f"{large:e}"
'1.234568e+09'
>>> f"{large:E}"
'1.234568E+09'

>>> number = 42.42
>>> f"{number:f}"
'42.420000'
>>> inf = float("inf")
>>> f"{inf:f}"
'inf'
>>> f"{inf:F}"
'INF'

>>> f"{large:g}"
'1.23457e+09'
>>> f"{large:G}"
'1.23457E+09'
>>> f"{number:g}"
'42.42'

In the first set of examples, you use e and E to represent a large number using scientific notation.

Next, you use the f and F type modifiers. The difference between these two is that the inf and nan values will use lowercase letters with f and uppercase letters with F.

Finally, g and G represent larger numbers in scientific notation and smaller numbers in fixed-point notation. The difference between g and G is that when you use them with large numbers, the scientific notation separator will be in lowercase or uppercase, respectively.

Formatting Numeric Values to Improve Presentation

The format specifier mini-language has several options to format numeric values. You can use these options to tweak how you display numbers in your program’s output. You’ll have options to control the decimal precision, add thousand separators, express the numbers as percentages, and add leading signs to your numeric values.

In the following sections, you’ll learn about all these options and how to use them as part of your format specifiers.

>>> from math import pi

>>> pi
3.141592653589793

>>> f"{pi:.4f}"
'3.1416'

>>> f"{pi:.8f}"
'3.14159265'

>>> number = 1234567890

>>> f"{number:,}"
'1,234,567,890'

>>> f"{number:_}"
'1_234_567_890'

>>> f"{number:,.2f}"
'1,234,567,890.00'

>>> f"{number:_.2f}"
'1_234_567_890.00'

>>> positive = 42
>>> negative = -42

>>> f"{positive:+}"
'+42'
>>> f"{negative:+}"
'-42'

>>> f"{positive:-}"
'42'
>>> f"{negative:-}"
'-42'

>>> f"{positive: }"
' 42'
>>> f"{negative: }"
'-42'

Providing Formatting Fields Dynamically

Up to this point, you’ve learned the basics of Python’s string formatting mini-language. In all the examples you’ve seen so far, you’ve hard-coded the format specifiers using a string. However, sometimes you’ll need to build the format specifier dynamically.

To do this, you can embed variables and expressions in the format specifier using curly brackets. Consider the following example:

>>> total = 123456.99

>>> # Formatting values
>>> width = 30
>>> align = ">"
>>> fill = "."
>>> precision = 2
>>> sep = ","

>>> f"Total{total:{fill}{align}{width}{sep}.{precision}f}"
'Total....................123,456.99'

In this example, you build a format specifier using variables within curly brackets. To improve readability, you use mostly the same names as those in the format specifier syntax, except for sep, which represents the grouping option.

The possibility of dynamically creating format specifiers is a powerful tool that allows you to add flexibility to your string formatting code.

Formatting Strings: Practical Examples

Now that you’ve learned the basic syntax of format specifiers and seen how to generate them dynamically, it’s time to dive into some practical examples of when you’d like to use format specifiers in your strings.

To kick things off, you’ll start with a pretty common use case of string formatting: representing currency values. Then, you’ll explore other common use cases of format specifiers.

>>> inventory = [
...     {"product": "Apple", "price": 5.70},
...     {"product": "Orange", "price": 4.50},
...     {"product": "Banana", "price": 6.00},
...     {"product": "Mango", "price": 8.60},
...     {"product": "Pepper", "price": 4.20},
...     {"product": "Carrot", "price": 3.57},
... ]

>>> for item in inventory:
...     product = item["product"]
...     price = item["price"]
...     print(f"{product:.<30}${price:.2f}")
...
Apple.........................$5.70
Orange........................$4.50
Banana........................$6.00
Mango.........................$8.60
Pepper........................$4.20
Carrot........................$3.57

>>> from datetime import datetime

>>> now = datetime.now()
>>> now
datetime.datetime(2024, 1, 31, 14, 6, 53, 251170)

>>> >>> f"Today is {now:%a %b %d, %Y} and it's {now:%H:%M} hours"
"Today is Wed Jan 31, 2024 and it's 14:06 hours"

>>> wins = 25
>>> games = 35

>>> f"Team's winning percentage: {wins / games:.2%}"
"Team's winning percentage: 71.43%"

Exploring Other Options in the Mini-Language

At this point, you’ve learned the string format mini-language’s major features. But there’s still more to discover! In this section, you’ll learn some more options that might come in handy when you’re creating your own format specifiers. In practice, you’ll learn about two additional modifiers:

• z coerces negative zeros.
• # adds type representation prefixes.

In Python 3.11 the format specifier syntax was extended to include z. The z modifier coerces negative zero floating-point values to positive zero after rounding to the format precision. This option works only for floating-point presentation types.

Yes, Python has negative zero values:

>>> neg_zero = -0.0
>>> neg_zero
-0.0

This may be a weird behavior in some situations. So, you may need to remove the negative sign. To do this, you can use the z option:

>>> neg_zero = -0.0
>>> f"{neg_zero:z.4f}"
'0.0000'

In this example, you use the z option to coerce the negative zero to positive zero. Note that this only works for fixed-point representation types, f or F. Also, the z option appends zeros to the output to fill the intended precision. In the example, you use a precision of 4, so you get four zeros after the decimal point.

Another useful option that you’ll find in the format specifier syntax is the # modifier. This option allows you to present numeric values using their alternate form. Different numeric data types have different alternate forms. The following table summarizes what the # modifier does in each data type:

As you can see, the alternate form modifier (#) impacts the representation of numeric types in different ways. To understand how this modifier works, consider the following examples:

>>> number = 42

>>> f"hex: {number:#x};  oct: {number:#o};  bin: {number:#b}"
'hex: 0x2a;  oct: 0o52;  bin: 0b101010'

>>> f"float: {number:#.0f}"
'float: 42.'

In the first example, you use different integer variations to represent a number. The # specifier adds the appropriate prefix to the output.

In the second example, you represent a number as a floating-point value. In this case, you have a precision of 0, meaning that you don’t want to display decimal values. However, the # modifier appends the decimal point, so anybody can know that this is a floating-point value.

Conclusion

Now you know how to create format specifiers to format the values that you interpolate into your strings using Python’s format mini-language. A format specifier is a string that follows a syntax defined in this mini-language. With a proper format specifier, you can format numbers as currency values, use scientific notation, express a value as a percentage, and more.

In this tutorial, you’ve learned how to:

• Use the format mini-language syntax in your strings
• Align and fill textual output in your Python code
• Convert between data types in your outputs
• Provide formatting fields dynamically using variables and expressions
• Format numeric values in different ways to solve different problems

With this knowledge, you’re now ready to start creating nicely formatted strings and messages in your Python code.