String Interpolation in Python: Exploring Available Tools

Interpolating Values in F-Strings

Using f-strings, you can interpolate variables and expressions directly into your strings. Then, when Python executes the f-string, the variable’s content or the expression’s result will be interpolated into the f-string literal to build the final string:

>>> x = 5
>>> y = 10

>>> f"The sum of {x} and {y} is {x + y}."
'The sum of 5 and 10 is 15.'

In this example, you have two variables, x and y. Then, you create an f-string literal with three replacement fields. The first two fields hold the variables, and the third field holds an expression.

It’s important to note that Python evaluates f-strings at runtime. So, in this example, x, y, and x + y are evaluated and interpolated into the string literal when Python runs the line of code containing the f-string.

You can embed almost any Python expression in an f-string, such as arithmetic, comparison, and Boolean expressions. You can also use functions and method calls, and even comprehensions or other more complex expressions:

>>> import math
>>> radius = 16
>>> f"The area of your circle is {math.pi * radius ** 2}"
'The area of your circle is 804.247719318987'

>>> name = "Pythonista"
>>> site = "real python"
>>> f"Hello, {name.upper()}! Welcome to {site.title()}!"
'Hello, PYTHONISTA! Welcome to Real Python!'

>>> f"{[2**n for n in range(3, 9)]}"
'[8, 16, 32, 64, 128, 256]'

In the first f-string, you embed a math expression into the replacement field. In the second example, you use the .upper() and .title() string methods in the replacement fields. Python evaluates the expression and calls the method for you. Then, it inserts the results into the resulting f-string literal. In the final example, you create an f-string that embeds a list comprehension. The comprehension creates a new list of powers of 2.

>>> f"The number is {42}"
'The number is 42'

>>> f"Pi {3.14}"
'Pi 3.14'

F-strings before Python 3.12 have a few limitations that you must consider when working with them. Inside the replacement fields, you can’t:

• Reuse quotes or string delimiters
• Embed backslashes, which means you can’t use escape sequences
• Add inline comments
• Nest f-strings beyond the available quoting variations

PEP 536 lists all these limitations. To see them in action, check out the F-Strings Had Some Limitations Before Python 3.12 section in the Python 3.12 Preview tutorial.

Self-Documenting the Interpolated Value

With f-strings, you can use a feature known as self-documenting expressions that adds an equal sign after the interpolated variable or expression. This feature can help you debug your code. For quick debugging, most people use the built-in print() function to check the value of a variable or the result of an expression:

>>> value = "Suspicious value"

>>> print(f"{value = }")
variable = 'Suspicious value'

>>> f"{2 + 3 = }"
'2 + 3 = 5'

You can use a variable or an expression followed by an equal sign (=) in an f-string to create a self-documenting expression. When Python runs the f-string, it builds an expression-like string containing the variable or expression, the equal sign, and the current result.

In these examples, the whitespaces around the equal sign aren’t required, but they make the output more readable.

The self-documenting expressions feature adds readability to your string interpolation process and can be an excellent tool for quick debugging with print().

Using Different String Representations in F-Strings

F-strings allow you to use two flags with special meaning in the interpolation process. These flags relate to how Python deals with an object’s string representation. Here are the flags and their intended meaning:

Ideally, the .__str__() special method should provide a user-friendly string representation of an object. Python falls back to calling this method when you use the str() function. Meanwhile, the .__repr__() method returns a developer-friendly representation, which you get when you use the repr() function.

To illustrate how these flags work, consider the following sample class:

class Article:
    def __init__(self, title, author, pub_date):
        self.title = title
        self.author = author
        self.pub_date = pub_date

    def __str__(self):
        return (
            f"Article: {self.title}\n"
            f"Author: {self.author}\n"
            f"Published: {self.pub_date}\n"
        )

    def __repr__(self):
        return (
            f"{type(self).__name__}("
            f"title={self.title!r}, "
            f"author={self.author!r}, "
            f"pub_date={self.pub_date!r})"
        )

This Article class has three instance attributes .title, .author, and .pub_date. The .__str__() method returns a string containing the article’s information in a user-friendly format. This message is targeted to end users rather than developers.

The .__repr__() method returns a string that’s a developer-friendly representation of the object. In short, the representation tells the developer how the current instance was created. Ideally, the developer should be able to copy this string representation and create an equivalent object.

Now your class is ready for the !s and !r flags:

>>> from article import Article

>>> article = Article(
...     title="String Interpolation in Python: Exploring Available Tools",
...     author="Real Python",
...     pub_date="2024-06-03",
... )

>>> print(f"{article!s}")
Article: String Interpolation in Python: Exploring Available Tools
Author: Real Python
Published: 2024-06-03

>>> print(f"{article!r}")
Article(
    title='String Interpolation in Python: Exploring Available Tools',
    author='Real Python',
    pub_date='2024-06-03'
)

In the first f-string, you use the !s tag to interpolate the string representation that .__str__() returns. In the second f-string, you use the !r flag to interpolate the developer-friendly string representation of your object. Notice that, in the latter case, the resulting string object represents a valid Python code that you can evaluate.

Using Positional and Named Arguments

To interpolate objects into a string using the .format() method, you can use three different approaches. You can use:

1. Empty replacement fields, {}
2. Replacement fields with zero-based indices, {0} ... {n}
3. Replacement fields with named arguments, {arg_1} ... {arg_n}

To illustrate how these options work, say that you need to automate the process of generating emails for the customers who purchase products from your company. You can create an email template and then interpolate the customer data dynamically:

>>> template = """
... Dear {},
...
... Thank you for your recent purchase of {}.
...
... Remember, our support team is always here to assist you.
...
... Best regards,
... {}
... """

>>> print(template.format("Emily", "MacBook Pro 16-inch", "John"))

Dear Emily,

Thank you for your recent purchase of MacBook Pro 16-inch.

Remember, our support team is always here to assist you.

Best regards,
John

In this example, you create an email template with three empty replacement fields. The .format() method inserts the passed values in the appropriate field using their relative position. If you want to have a bit more control over how the values are interpolated, then you can use integer indices:

>>> template = """
... Dear {0},
...
... Thank you for your recent purchase of {1}.
...
... Remember, our support team is always here to assist you.
...
... Best regards,
... {2}
... """

>>> print(template.format("Linda", "Samsung Galaxy S22", "Jane"))

Dear Linda,

Thank you for your recent purchase of Samsung Galaxy S22.

Remember, our support team is always here to assist you.

Best regards,
Jane

In this example, the result is similar. However, now you’re certain that the first argument, "Linda", will go to index 0, the second argument, "Samsung Galaxy S22" will go to index 1, and so on. This way of handling the arguments can be useful when the arguments’ original order isn’t the same as the order in the final string:

>>> template = """
... Dear {1},
...
... Thank you for your recent purchase of {0}.
...
... Remember, our support team is always here to assist you.
...
... Best regards,
... {2}
... """

>>> purchase = ("Samsung Galaxy S22", "Linda", "Jane")

>>> print(template.format(*purchase))

Dear Linda,

Thank you for your recent purchase of Samsung Galaxy S22.

Remember, our support team is always here to assist you.

Best regards,
Jane

Here, the order of the items in the purchase tuple doesn’t match the natural order in the template. So, you move the indices according to the new order and get the desired result.

>>> prefix = "re"
>>> template = "{0}-create and {0}start"

>>> template.format(prefix)
're-create and restart'

Even though the above options work okay, they aren’t completely readable. Fortunately, there’s a better way. You can use keyword arguments with .format(). Here’s how:

>>> template = """
... Dear {customer},
...
... Thank you for your recent purchase of {product}.
...
... Remember, our support team is always here to assist you.
...
... Best regards,
... {employee}
... """

>>> print(
...     template.format(
...         customer="Bob",
...         product="Canon EOS R5",
...         employee="Kate"
...     )
... )

Dear Bob,

Thank you for your recent purchase of Canon EOS R5.

Remember, our support team is always here to assist you.

Best regards,
Kate

In this update, you’ve used explicit names in the replacement fields. These names match the keyword arguments you used when calling .format(). Your code now looks much more readable.

Finally, it’s also possible to use dictionaries to feed the .format() method. Say that you’re retrieving your data from a CSV file that looks something like this:

product,customer,employee
MacBook Pro 16-inch,Emily,John
Samsung Galaxy S22,Linda,Jane
Canon EOS R5,Bob,Kate

You can use the csv module from the standard library to process this file and load its content so that you can create emails for each sale. The csv.DictReader is a good tool for this task. This reader allows you to read every line in a CSV file into a dictionary. The keys will be the file headings, and the values will be the values in each row.

Here’s the code that you can use to do the job:

import csv

template = """
Dear {customer},

Thank you for your recent purchase of {product}.

Remember, our support team is always here to assist you.

Best regards,
{employee}
"""

def display_emails(template, path):
    with open(path) as file:
        for customer in csv.DictReader(file):
            print(template.format(**customer))

display_emails(template, "sales.csv")

In this code, you first import csv from the standard library. Then, you have the usual email template with names in the replacement fields. The names match the headings in the CSV file.

Next, you have the display_emails() function. This function takes two arguments: the email template and the path to the CSV file. Inside the function, you open the input file for reading using a with statement.

The for loop iterates over the lines of the file using the DictReader class. Finally, you use the .format() method to interpolate the values in the current line into the email template. In this example, you use the dictionary unpacking operator (**) to provide the arguments to .format().

Go ahead and run this script from your command line to check the output.

There’s another interesting behavior of .format() when you use it with dictionaries. Here’s a quick toy example:

>>> numbers = {"one": 1, "two": 2, "three": 3}

>>> "{one}-{two}".format(**numbers)
'1-2'

>>> "{one}-{two}-{three}".format(**numbers)
'1-2-3'

>>> "{one}-{two}-{three}-{four}".format(**numbers)
Traceback (most recent call last):
    ...
KeyError: 'four'

When the keys in the input dictionary match the named arguments in the string, the interpolation works even if you have unused keys. When the keys don’t match the named arguments, then you get a KeyError exception.

Using Different String Representations With .format()

Like with f-strings, you can also use the !s and !r flags with .format() to insert objects into your strings using different string representations. Reusing the Article class from the Using Different String Representations in F-Strings section, here are two examples that show how the flags work:

>>> from article import Article

>>> article = Article(
...     title="String Interpolation in Python: Exploring Available Tools",
...     author="Real Python",
...     pub_date="2024-06-03",
... )

>>> print("{article!s}".format(article=article))
Article: String Interpolation in Python: Exploring Available Tools
Author: Real Python
Published: 2024-06-03

>>> print("{article!r}".format(article=article))
Article(
    title='String Interpolation in Python: Exploring Available Tools',
    author='Real Python',
    pub_date='2024-06-03'
)

Again, the !s flag allows you to use the user-friendly string representation of the object at hand. In contrast, the !r flag allows you to use the developer-friendly representation. You’ll decide which flag to use in your code by considering the target audience of your code.

Interpolating One or More Values

In the previous section, you saw an example where you interpolated several values or expressions into a string using the modulo operator. If you need to insert only one value, then you can skip the tuple or use a single-item tuple:

>>> "Hello, %s!" % "Pythonista"
'Hello, Pythonista!'

>>> "Hello, %s!" % ("Pythonista",)
'Hello, Pythonista!'

The first syntax is a bit cleaner than the second syntax. However, for consistency throughout your code, you may want to use the second syntax.

Now, what happens when you need to interpolate a tuple object? Here’s an example:

>>> "Interpolating a tuple: %s" % (1, 2, 3)
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    "Interpolating a tuple: %s" % (1, 2, 3)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~
TypeError: not all arguments converted during string formatting

In this example, Python interprets the tuple as three different values, and you get an error because the string has only one replacement field. To work around this issue, you need to use a single-item tuple:

>>> "Interpolating a tuple: %s" % ((1, 2, 3),)
'Interpolating a tuple: (1, 2, 3)'

Now, the interpolation works correctly, and you end up with the tuple inserted into the string. It’s important to note that you must use tuples if you intend to feed multiple values into the modulo operator:

>>> "Hello, %s! Today is %s." % [name, day]
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    "Hello, %s! Today is %s." % [name, day]
     ~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~
TypeError: not enough arguments for format string

>>> "The sum of %d and %d is %d." % [x, y, x + y]
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    "The sum of %d and %d is %d." % [x, y, x + y]
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~
TypeError: %d format: a real number is required, not list

If you use a list object, or another iterable, then Python will interpret it as a single object, and the interpolation will fail with a TypeError exception.

Using Named Replacement Fields

In the previous section, you learned that you should use a tuple to provide multiple arguments to the modulo operator for string interpolation. This way, the operator inserts the values in the tuple into the target string by their position, but this isn’t that readable.

Fortunately, there’s a better way. You can also use dictionaries and named replacement fields:

>>> jane = {"name": "Jane", "job": "Python Dev"}

>>> "My name is %(name)s. I'm a %(job)s." % jane
"My name is Jane. I'm a Python Dev."

In this example, the modulo operator inserts each value using the corresponding key, which is way more readable and intuitive. To build the named replacement fields, you need to insert the name in parentheses between the % sign and the format specifier.

Using Different String Representations

You can also use the different string representations of objects with the modulo operator for string interpolation. You already learned that the %s conversion specifier converts the object into strings. To do this, the specifier uses the user-friendly representation from the .__str__() special method.

To use the developer-friendly string representation provided in .__repr__(), you can use the %r conversion specifier.

To illustrate how to do this, you can use the Article class again:

>>> from article import Article

>>> article = Article(
...     title="String Interpolation in Python: Exploring Available Tools",
...     author="Real Python",
...     pub_date="2024-06-03",
... )

>>> print("%s" % article)
Article: String Interpolation in Python: Exploring Available Tools
Author: Real Python
Published: 2024-06-03

>>> print("%r" % article)
Article(
    title='String Interpolation in Python: Exploring Available Tools',
    author='Real Python',
    pub_date='2024-06-03'
)

The resulting behavior is the same as with f-strings and the .format() method. Again, the choice of which string representation to use will depend on your code’s target audience.

Building Template Strings

To create valid template strings that you can feed to the Template class, you consider some basic rules. Here’s how PEP 292 describes these rules:

1. $$ is an escape; it is replaced with a single $
2. $identifier names a substitution placeholder matching a mapping key of “identifier”. By default, “identifier” must spell a Python identifier as defined in [2]. The first non-identifier character after the $ character terminates this placeholder specification.
3. ${identifier} is equivalent to $identifier. It is required when valid identifier characters follow the placeholder but are not part of the placeholder, e.g. "${noun}ification". (Source)

To kick things off, you’ll start with an example of how to escape the dollar sign ($), which is required to express currency values, for example:

>>> from string import Template

>>> Template("$$$amount").substitute(amount="1,000.00")
'$1,000.00'

In this string template, the first two dollar signs escape the required dollar sign, and the last dollar sign defines the placeholder.

The second rule states that every placeholder needs a $ character followed by a valid Python identifier. Here’s an example:

>>> Template("$greeting, $who!").substitute(greeting="Hello", who="World")
'Hello, World!'

In this example, you form the placeholders using valid Python identifiers, greeting and who. As the second rule states, the first non-identifier character terminates the placeholder, so that’s the case of the comma after $greeting and the exclamation point after $who.

The third rule applies to situations where you need to substitute a word in a string, and the characters that follow the identifier are valid for building identifiers. In this situation, Python won’t know where the identifier finishes.

For example, say that you need a template that allows you to display an amount of money in USD. In this situation, you can do something like the following:

>>> Template("${amount}USD").substitute(amount="100")
'100USD'

>>> Template("$amountUSD").substitute(amount="100")
Traceback (most recent call last):
    ...
KeyError: 'amountUSD'

Because USD are all characters that you can use in a valid Python identifier, you need to use the ${identifier} placeholder style. Otherwise, you get a KeyError.

Finally, the template string that you supply to the Template() constructor is stored in the .template attribute. This allows you to modify the template dynamically:

>>> greeting = Template("Hello, $name! Today is $day.")
>>> greeting.substitute(name="John", day="Friday")
'Hello, John! Today is Friday.'

>>> greeting.template = "Hello, $name! Welcome!"
>>> greeting.substitute(name="John")
'Hello, John! Welcome!'

You can modify the .template attribute whenever you need to. However, it’s best to create new instances of Template for every different template string in your code. This way, you’ll prevent subtle bugs or even breaking your templates.

Substituting Values With .substitute()

Up to this point, you’ve used the .substitute() method with keyword arguments to interpolate values in your string templates. You can also use the methods with dictionaries:

>>> from string import Template

>>> numbers = {"one": 1, "two": 2, "three": 3}

>>> Template("$one-$two-$three").substitute(**numbers)
'1-2-3'

Again, when you use a dictionary as an argument to substitute(), you need to use the dictionary unpacking operator (**). This operator will unpack the key-value pairs into keyword arguments that will be inserted into the appropriate placeholders in the template string.

Note that the placeholder names have to match the dictionary keys. If a placeholder doesn’t match any key or if the number of keys doesn’t match the number of placeholders, then you get an error:

>>> numbers = {"one": 1, "two": 2}

>>> Template("$one-$two-$three").substitute(**numbers)
Traceback (most recent call last):
    ...
KeyError: 'three'

If you call .substitute() with a dictionary whose keys don’t match all the placeholders in the template string, then you get a KeyError.

Substituting Values With .safe_substitute()

Template has another method that you can use to interpolate the values into the string template. The method is called .safe_substitute() and works similarly to .substitute(). However, when you use an incomplete or non-matching set of arguments, the method doesn’t raise a KeyError:

>>> from string import Template

>>> numbers = {"one": 1, "two": 2}

>>> Template("$one-$two-$three").safe_substitute(**numbers)
'1-2-$three'

In this code snippet, you call .safe_substitute() using a dictionary whose keys don’t match all the existing placeholders. Rather than getting a KeyError exception, you get a string that literally shows the missing placeholder. It can be useful in identifying the missing values inside a view of an HTML page to render.

The .safe_substitute() method might be an advantage of using Template over the .format() method:

>>> "{one}-{two}-{three}".format(**numbers)
Traceback (most recent call last):
    ...
KeyError: 'three'

The .format() method doesn’t have a safe way to perform the interpolation when you use an incomplete or non-matching set of arguments.