Text of peps.python.org › pep-0498 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 498 – Literal String Interpolation | peps.python.org

PEP 498 – Literal String Interpolation PEP 498 – Literal String Interpolation Author : Eric V. Smith <eric at trueblade.com> Status : Final Type : Standards Track Created : 01-Aug-2015 Python-Version : 3.6 Post-History : 07-Aug-2015, 30-Aug-2015, 04-Sep-2015, 19-Sep-2015, 06-Nov-2016 Resolution : Python-Dev message Table of Contents Abstract Rationale No use of globals() or locals() Specification Escape sequences Code equivalence Expression evaluation Format specifiers Concatenating strings Error handling Leading and trailing whitespace in expressions is ignored Evaluation order of expressions Discussion python-ideas discussion How to denote f-strings How to specify the location of expressions in f-strings Supporting full Python expressions Similar support in other languages Differences between f-string and str.format expressions Triple-quoted f-strings Raw f-strings No binary f-strings !s , !r , and !a are redundant Lambdas inside expressions Can’t combine with ‘u’ Examples from Python’s source code References Copyright Abstract Python supports multiple ways to format text strings.

These include %-formatting [1] , str.format() [2] , and string.Template [3] . Each of these methods have their advantages, but in addition have disadvantages that make them cumbersome to use in practice. This PEP proposed to add a new string formatting mechanism: Literal String Interpolation. In this PEP, such strings will be referred to as “f-strings”, taken from the leading character used to denote such strings, and standing for “formatted strings”.

This PEP does not propose to remove or deprecate any of the existing string formatting mechanisms. F-strings provide a way to embed expressions inside string literals, using a minimal syntax. It should be noted that an f-string is really an expression evaluated at run time, not a constant value. In Python source code, an f-string is a literal string, prefixed with ‘f’, which contains expressions inside braces. The expressions are replaced with their values.

Some examples are: >>> import datetime >>> name = 'Fred' >>> age = 50 >>> anniversary = datetime . date ( 1991 , 10 , 12 ) >>> f 'My name is { name } , my age next year is { age + 1 } , my anniversary is { anniversary : %A, %B %d, %Y } .' 'My name is Fred, my age next year is 51, my anniversary is Saturday, October 12, 1991.' >>> f 'He said his name is { name !r} .' "He said his name is 'Fred'." A similar feature was proposed in PEP 215 .

PEP 215 proposed to support a subset of Python expressions, and did not support the type-specific string formatting (the __format__() method) which was introduced with PEP 3101 . Rationale This PEP is driven by the desire to have a simpler way to format strings in Python. The existing ways of formatting are either error prone, inflexible, or cumbersome. %-formatting is limited as to the types it supports. Only ints, strs, and doubles can be formatted.

All other types are either not supported, or converted to one of these types before formatting. In addition, there’s a well-known trap where a single value is passed: >>> msg = 'disk failure' >>> 'error: %s ' % msg 'error: disk failure' But if msg were ever to be a tuple, the same code would fail: >>> msg = ( 'disk failure' , 32 ) >>> 'error: %s ' % msg Traceback (most recent call last): File "<stdin>" , line 1 , in <module> TypeError : not all arguments converted during string formatting To be defensive, the following code should be used: >>> 'error: %s ' % ( msg ,) "error: ('disk failure', 32)" str.format() was added to address some of these problems with %-formatting.

In particular, it uses normal function call syntax (and therefore supports multiple parameters) and it is extensible through the __format__() method on the object being converted to a string. See PEP 3101 for a detailed rationale. This PEP reuses much of the str.format() syntax and machinery, in order to provide continuity with an existing Python string formatting mechanism. However, str.format() is not without its issues.

Chief among them is its verbosity. For example, the text value is repeated here: >>> value = 4 * 20 >>> 'The value is {value} .' . format ( value = value ) 'The value is 80.' Even in its simplest form there is a bit of boilerplate, and the value that’s inserted into the placeholder is sometimes far removed from where the placeholder is situated: >>> 'The value is {} .' . format ( value ) 'The value is 80.' With an f-string, this becomes: >>> f 'The value is { value } .' 'The value is 80.' F-strings provide a concise, readable way to include the value of Python expressions inside strings.

In this sense, string.Template and %-formatting have similar shortcomings to str.format() , but also support fewer formatting options. In particular, they do not support the __format__ protocol, so that there is no way to control how a specific object is converted to a string, nor can it be extended to additional types that want to control how they are converted to strings (such as Decimal and datetime ). This example is not possible with string.Template : >>> value = 1234 >>> f 'input= { value : #06x } ' 'input=0x04d2' And neither %-formatting nor string.Template can control formatting such as: >>> date = datetime . date ( 1991 , 10 , 12 ) >>> f ' { date } was on a { date : %A } ' '1991-10-12 was on a Saturday' No use of globals() or locals() In the discussions on python-dev [4] , a number of solutions where presented that used locals() and globals() or their equivalents.

All of these have various problems. Among these are referencing variables that are not otherwise used in a closure. Consider: >>> def outer ( x ): ... def inner (): ... return 'x= {x} ' . format_map ( locals ()) ... return inner ... >>> outer ( 42 )() Traceback (most recent call last): File "<stdin>" , line 1 , in <module> File "<stdin>" , line 3 , in inner KeyError : 'x' This returns an error because the compiler has not added a reference to x inside the closure.

You need to manually add a reference to x in order for this to work: >>> def outer ( x ): ... def inner (): ... x ... return 'x= {x} ' . format_map ( locals ()) ... return inner ... >>> outer ( 42 )() 'x=42' In addition, using locals() or globals() introduces an information leak. A called routine that has access to the callers locals() or globals() has access to far more information than needed to do the string interpolation.

Guido stated [5] that any solution to better string interpolation would not use locals() or globals() in its implementation. (This does not forbid users from passing locals() or globals() in, it just doesn’t require it, nor does it allow using these functions under the hood.) Specification In source code, f-strings are string literals that are prefixed by the letter ‘f’ or ‘F’. Everywhere this PEP uses ‘f’, ‘F’ may also be used. ‘f’ may be combined with ‘r’ or ‘R’, in either order, to produce raw f-string literals. ‘f’ may not be combined with ‘b’: this PEP does not propose to add binary f-strings. ‘f’ may not be combined with ‘u’.

When tokenizing source files, f-strings use the same rules as normal strings, raw strings, binary strings, and triple quoted strings. That is, the string must end with the same character that it started with: if it starts with a single quote it must end with a single quote, etc. This implies that any code that currently scans Python code looking for strings should be trivially modifiable to recognize f-strings (parsing within an f-string is another matter, of course).

Once tokenized, f-strings are parsed in to literal strings and expressions. Expressions appear within curly braces '{' and '}' . While scanning the string for expressions, any doubled braces '{{' or '}}' inside literal portions of an f-string are replaced by the corresponding single brace. Doubled literal opening braces do not signify the start of an expression. A single closing curly brace '}' in the lite

The rest of this page is on the live site.