Python String Formatting: Available Tools and Their Features

Using the Formatting Mini-Language With F-Strings

When you use f-strings to create strings through interpolation, you need to use replacement fields. In f-strings, you can define a replacement field using curly brackets ({}) as in the examples below:

>>> debit = 300.00
>>> credit = 450.00

>>> f"Debit: ${debit}, Credit: ${credit}, Balance: ${credit - debit}"
'Debit: $300, Credit: $450.0, Balance: $150.0'

Inside the brackets, you can insert Python objects and expressions. In this example, you’d like the resulting string to display the currency values using a proper format. However, you get a string that shows the currency values with at most one digit on its decimal part.

To format the values and always display two digits on its decimal part, you can use a format specifier:

>>> f"Debit: ${debit:.2f}, Credit: ${credit:.2f}, Balance: ${credit - debit:.2f}"
'Debit: $300.00, Credit: $450.00, Balance: $150.00'

In this example, note that each replacement field contains a string that starts with a colon. That’s a format specifier. The .2f part tells Python that you want to format the value as a floating-point number (f) with two decimal places (.2).

The string formatting mini-language is a powerful tool with several cool features, including the following:

• Strings alignment
• Conversion between input objects’ types
• Numeric values formatting
• Dynamic formatting

In the following sections, you’ll explore how to use f-strings, the .format() method, and the string formatting mini-language to format the values that you insert into your strings through interpolation.

Formatting Strings With F-Strings: A Practical Example

You can use f-strings and the string formatting mini-language to format the values that you interpolate into your strings in multiple ways. To illustrate, say that you want to write a Python function to build a grades report for your students. The student data is in a dictionary that looks like the following:

>>> student = {
...     "name": "John Doe",
...     "subjects": [
...         {
...             "name": "Mathematics",
...             "grade": 88,
...             "comment": "Excellent improvement.",
...         },
...         {
...             "name": "Science",
...             "grade": 92,
...             "comment": "Outstanding performance.",
...         },
...         {
...             "name": "History",
...             "grade": 78,
...             "comment": "Needs to participate more.",
...         },
...         {
...             "name": "Art",
...             "grade": 85,
...             "comment": "Very creative."
...         },
...     ],
... }

The dictionary has the name key to store the student’s name. Then, it has the subjects key to hold a list of dictionaries containing the student’s performance in each subject.

Your function may look like the following:

 1def build_student_report(student):
 2    report_header = f"Progress Report. Student: {student['name']}"
 3
 4    total = sum(subject["grade"] for subject in student["subjects"])
 5    average = total / len(student["subjects"])
 6    average_report = f"Average: {average:.2f} / 100\n"
 7
 8    subject_report = "Course Details:\n"
 9    for subject in student["subjects"]:
10        subject_report += (
11            f"{subject['name']:<15} "
12            f"Grade: {subject['grade']:3d} "
13            f"Comment: {subject['comment']}\n"
14        )
15
16    return f"""
17{report_header}
18{average_report}
19{subject_report}
20Thank you for reviewing the progress report.
21    """

In this function, you’re doing several things. Here’s a line-by-line breakdown:

• Line 2 defines a heading for the report.
• Line 4 sums all the grades.
• Line 5 computes the average of the grades.
• Line 6 defines the average grade subreport. In this part of the report, you use the .2f format specifier to express the average grade as a floating-point number with two decimal places.
• Line 8 defines the first line of the subject subreport.
• Line 9 starts a loop over the subjects.
• Line 10 adds more information to the subject subreport.
• Line 11 formats the subject’s name. To do this, you use the <15 format specifier, which tells Python to align the name to the left within 15 characters.
• Line 12 formats the grade. In this case, the 3d format specifier tells Python to display the grade using up to three characters. A leading space is used if the grade doesn’t have three digits.
• Line 13 adds the comment part.
• Lines 16 to 21 build the final report and return it to the caller.

Now that you’ve gone through the complete code, it’s time to try out your function. Go ahead and run the following code:

>>> from grades_report_v1 import build_student_report

>>> print(build_student_report(student))

Progress Report. Student: John Doe
Average: 85.75 / 100

Course Details:
Mathematics     Grade:  88 Comment: Excellent improvement.
Science         Grade:  92 Comment: Outstanding performance.
History         Grade:  78 Comment: Needs to participate more.
Art             Grade:  85 Comment: Very creative.

Thank you for reviewing the progress report.

Your report looks pretty nice! It provides general information about the student at the top and grade details for every subject.

Using the Formatting Mini-Language With .format()

The str.format() method also supports the string formatting mini-language. This feature allows you to nicely format the interpolated values when you create strings through interpolation. To illustrate, consider the example you wrote in the section about using the formatting mini-language with f-strings.

Here’s how to do it with the .format() method:

>>> debit = 300.00
>>> credit = 450.00

>>> template = "Debit: ${0:.2f}, Credit: ${1:.2f}, Balance: ${2:.2f}"
>>> template.format(debit, credit, credit - debit)
'Debit: $300.00, Credit: $450.00, Balance: $150.00'

Again, the resulting string displays the currency values using a proper format that shows two decimal places.

Formatting Strings With .format(): Practical Examples

Now it’s time for a couple of practical examples of using the .format() method and the string formatting mini-language to format your strings.

For the first example, say that you need to create a sales report for your company. You’d like to create a report template and fill it with the appropriate data when someone requires it. In this situation, you can create the following report template:

REPORT_TEMPLATE = """
Monthly Sales Report
--------------------
Report Date Range: {start_date} to {end_date}

Number of Transactions: {sep:.>20} {transactions:,}
Average Transaction Value: {sep:.>11} ${avg_transaction:,.2f}

Total Sales: {sep:.>23} ${total_sales:,.2f}
"""

In this report template, you have a few format specifiers. Here’s a summary of their specific meanings:

• .>20 displays the interpolated value aligned to the right within a space of 20 characters. The dot after the colon works as the fill character. The other format specifiers, .>11 and .>23, have a similar effect. Note that the field widths were chosen by trial and error to make the report line up nicely.
• , displays the preceding number using a comma as the thousands separator.
• ,.2f shows a value as a floating-point number using two decimal places and a comma as the thousands separator.

Now, you can code a function to generate the actual report:

# ...

def build_sales_report(sales_data, report_template=REPORT_TEMPLATE):
    total_sales = sum(sale["amount"] for sale in sales_data)
    transactions = len(sales_data)
    avg_transaction = total_sales / transactions

    return report_template.format(
        sep=".",
        start_date=sales_data[0]["date"],
        end_date=sales_data[-1]["date"],
        total_sales=total_sales,
        transactions=transactions,
        avg_transaction=avg_transaction,
    )

This function takes the sales data and the report template as arguments. Then, it computes the required values and calls .format() on the template. Go ahead and give this function a try by running the following code:

>>> from sales_report import build_sales_report

>>> sales_data = [
...     {"date": "2024-04-01", "amount": 100},
...     {"date": "2024-04-02", "amount": 200},
...     {"date": "2024-04-03", "amount": 300},
...     {"date": "2024-04-04", "amount": 400},
...     {"date": "2024-04-05", "amount": 500},
... ]

>>> print(build_sales_report(sales_data))

Monthly Sales Report
--------------------
Report Date Range: 2024-04-01 to 2024-04-05

Number of Transactions: .................... 5
Average Transaction Value: ........... $300.00

Total Sales: ....................... $1,500.00

Cool! You have a nicely formatted sales report. You can experiment on your own and tweak the format specifiers further as an exercise. For example, you can improve the date format. However, note that dates have their own formatting, which you can learn about in the Formatting Dates section of the tutorial about Python’s string formatting mini-language.

You can also take advantage of the .format() method when your data is stored in dictionaries. For example, here’s how you can update the build_student_report() function using the .format() method:

SUBJECT_TEMPLATE = "{name:<15} Grade: {grade:3} Comment: {comment}"
REPORT_TEMPLATE = """
Progress Report. Student: {name}
Average: {average:.2f} / 100

Course Details:
{subjects_report}

Thank you for reviewing the progress report.
"""

def build_student_report(student):
    data = {
        "name": student["name"],
        "average": sum(subject["grade"] for subject in student["subjects"])
        / len(student["subjects"]),
        "subjects_report": "\n".join(
            SUBJECT_TEMPLATE.format(**subject)
            for subject in student["subjects"]
        ),
    }

    return REPORT_TEMPLATE.format(**data)

In the first lines of code, you create string templates to display the information about each subject and also the final report. In build_student_report(), you create a dictionary with the required data to build the student report. Next, you interpolate the data into the report template using .format() with the dictionary as an argument.

Note that to fill the string templates, you use the ** operator to unpack the data from the input dictionary.

Using Conversion Specifiers

To build a conversion specifier, you need two or more characters. Here’s a quick summary of the accepted characters and their corresponding order in the specifier:

1. The % character marks the start of the specifier.
2. An optional mapping key in parentheses allows you to use named replacement fields like (name).
3. An optional conversion flag affects how some conversion types display.
4. An optional minimum field width allows you to define the number of characters to display.
5. An optional precision consists of a dot character (.) followed by the desired precision.
6. An optional length modifier is an l or h for long and short integers.
7. A conversion type specifies how the output string will be formatted, mimicking different data types.

Several conversion types are available for the modulo operator in Python. They allow you to control the output’s format in some way. For example, you can convert numbers to hexadecimal notation or add whitespace padding to generate nicely formatted tables and reports.

Here’s a summary of the conversion types currently available in Python:

With all these conversion types, you can process your interpolated values to display them using different representation types.

Here are a few examples of how to use some of the above specifiers in your strings:

>>> "%d" % 123.123  # As an integer
'123'

>>> "%o" % 42  # As an octal
'52'

>>> "%x" % 42  # As a hex
'2a'

>>> "%e" % 1234567890  # In scientific notation
'1.234568e+09'

>>> "%f" % 42  # As a floating-point number
'42.000000'

In these examples, you’ve used different conversion types to display values using different type representations. Now, check out the examples below to see other formatting options in action:

>>> # Named replacement fields
>>> jane =  {"first_name": "Jane", "last_name": "Doe"}
>>> "Full name: %(first_name)s %(last_name)s" % jane
'Full name: Jane Doe'

>>> # Minimal width of 15 chars
>>> "%-15f" % 3.1416  # Aligned to the left
'3.141600       '
>>> "%15f" % 3.1416  # Aligned to the right
'       3.141600'

>>> # Dynamic width
>>> width = 15
>>> "%-*f" % (width, 3.1416)
'3.141600       '
>>> "%*f" % (width, 3.1416)
'       3.141600'

>>> # Precision
>>> "%.2f" % 3.141592653589793
'3.14'
>>> "%.4f" % 3.141592653589793
'3.1416'
>>> "%.8f" % 3.141592653589793
'3.14159265'

In the first example, you use named replacement fields in parentheses and a dictionary to provide the values you want to interpolate. In the second example, you provide a minimum width for your string in characters.

The third example is a dynamic variation of the second. Note how the * symbol allows you to insert the desired width dynamically.

Finally, you use the precision option to display a floating-point number using different precisions. You use two, four, and eight digits after the decimal separator, respectively.

Unfortunately, the modulo operator doesn’t support the string formatting mini-language, so if you use this tool to interpolate and format your strings, then your formatting options are more limited than when you use f-strings or format().

Using Conversion Flags

The modulo operator also supports what’s known as conversion flags. Here’s a quick summary of the currently available flags:

These flags help you apply some additional formatting options to your strings. Consider the following quick examples:

>>> "%o" % 10
'12'
>>> "%#o" % 10
'0o12'

>>> "%x" % 31
'1f'
>>> "%#x" % 31
'0x1f'

In these examples, you demonstrate the effect of the # flag, which prepends the appropriate prefix to the input number depending on the base you use. This flag is mostly used with integer values.

Here are some more examples of using different flags:

>>> "%05d" % 42
'00042'

>>> "%10d" % 42
'        42'
>>> "%-10d" % 42
'42        '

>>> "% d" % 42
' 42'
>>> "% d" % -42
'-42'

>>> "%+d" % 42
'+42'
>>> "%+d" % -42
'-42'

In the first example, you add zero padding to the input value. Next, you have an example of how to use the minus sign to align a value to the left in a width of ten characters.

The space flag allows you to add a space before positive numbers. This space disappears when the value is negative. Finally, you use the plus sign so the string always displays whether the input value is positive or negative.