CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 498 – Literal String Interpolation | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0498/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 498 – Literal String Interpolation | peps.python.org'> <meta property="og:description" content="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..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0498/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="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..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 498</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 498 – Literal String Interpolation</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Eric V. Smith <eric at trueblade.com></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">01-Aug-2015</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.6</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">07-Aug-2015, 30-Aug-2015, 04-Sep-2015, 19-Sep-2015, 06-Nov-2016</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2015-September/141526.html">Python-Dev message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#no-use-of-globals-or-locals">No use of globals() or locals()</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#escape-sequences">Escape sequences</a></li> <li><a class="reference internal" href="#code-equivalence">Code equivalence</a></li> <li><a class="reference internal" href="#expression-evaluation">Expression evaluation</a></li> <li><a class="reference internal" href="#format-specifiers">Format specifiers</a></li> <li><a class="reference internal" href="#concatenating-strings">Concatenating strings</a></li> <li><a class="reference internal" href="#error-handling">Error handling</a></li> <li><a class="reference internal" href="#leading-and-trailing-whitespace-in-expressions-is-ignored">Leading and trailing whitespace in expressions is ignored</a></li> <li><a class="reference internal" href="#evaluation-order-of-expressions">Evaluation order of expressions</a></li> </ul> </li> <li><a class="reference internal" href="#discussion">Discussion</a><ul> <li><a class="reference internal" href="#python-ideas-discussion">python-ideas discussion</a><ul> <li><a class="reference internal" href="#how-to-denote-f-strings">How to denote f-strings</a></li> <li><a class="reference internal" href="#how-to-specify-the-location-of-expressions-in-f-strings">How to specify the location of expressions in f-strings</a></li> <li><a class="reference internal" href="#supporting-full-python-expressions">Supporting full Python expressions</a></li> </ul> </li> <li><a class="reference internal" href="#similar-support-in-other-languages">Similar support in other languages</a></li> <li><a class="reference internal" href="#differences-between-f-string-and-str-format-expressions">Differences between f-string and str.format expressions</a></li> <li><a class="reference internal" href="#triple-quoted-f-strings">Triple-quoted f-strings</a></li> <li><a class="reference internal" href="#raw-f-strings">Raw f-strings</a></li> <li><a class="reference internal" href="#no-binary-f-strings">No binary f-strings</a></li> <li><a class="reference internal" href="#s-r-and-a-are-redundant"><code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> are redundant</a></li> <li><a class="reference internal" href="#lambdas-inside-expressions">Lambdas inside expressions</a></li> <li><a class="reference internal" href="#can-t-combine-with-u">Can’t combine with ‘u’</a></li> </ul> </li> <li><a class="reference internal" href="#examples-from-python-s-source-code">Examples from Python’s source code</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Python supports multiple ways to format text strings. These include %-formatting <a class="footnote-reference brackets" href="#id11" id="id1">[1]</a>, <code class="docutils literal notranslate">str.format()</code> <a class="footnote-reference brackets" href="#id12" id="id2">[2]</a>, and <code class="docutils literal notranslate">string.Template</code> <a class="footnote-reference brackets" href="#id13" id="id3">[3]</a>. 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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'." </pre></div> </div> A similar feature was proposed in <a class="pep reference internal" href="../pep-0215/" title="PEP 215 – String Interpolation">PEP 215</a>. <a class="pep reference internal" href="../pep-0215/" title="PEP 215 – String Interpolation">PEP 215</a> proposed to support a subset of Python expressions, and did not support the type-specific string formatting (the <code class="docutils literal notranslate">__format__()</code> method) which was introduced with <a class="pep reference internal" href="../pep-3101/" title="PEP 3101 – Advanced String Formatting">PEP 3101</a>. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> msg = 'disk failure' >>> 'error: %s' % msg 'error: disk failure' </pre></div> </div> But if msg were ever to be a tuple, the same code would fail: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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 </pre></div> </div> To be defensive, the following code should be used: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 'error: %s' % (msg,) "error: ('disk failure', 32)" </pre></div> </div> <code class="docutils literal notranslate">str.format()</code> 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 <code class="docutils literal notranslate">__format__()</code> method on the object being converted to a string. See <a class="pep reference internal" href="../pep-3101/" title="PEP 3101 – Advanced String Formatting">PEP 3101</a> for a detailed rationale. This PEP reuses much of the <code class="docutils literal notranslate">str.format()</code> syntax and machinery, in order to provide continuity with an existing Python string formatting mechanism. However, <code class="docutils literal notranslate">str.format()</code> is not without its issues. Chief among them is its verbosity. For example, the text <code class="docutils literal notranslate">value</code> is repeated here: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> value = 4 * 20 >>> 'The value is {value}.'.format(value=value) 'The value is 80.' </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 'The value is {}.'.format(value) 'The value is 80.' </pre></div> </div> With an f-string, this becomes: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'The value is {value}.' 'The value is 80.' </pre></div> </div> F-strings provide a concise, readable way to include the value of Python expressions inside strings. In this sense, <code class="docutils literal notranslate">string.Template</code> and %-formatting have similar shortcomings to <code class="docutils literal notranslate">str.format()</code>, but also support fewer formatting options. In particular, they do not support the <code class="docutils literal notranslate">__format__</code> 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 <code class="docutils literal notranslate">Decimal</code> and <code class="docutils literal notranslate">datetime</code>). This example is not possible with <code class="docutils literal notranslate">string.Template</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> value = 1234 >>> f'input={value:#06x}' 'input=0x04d2' </pre></div> </div> And neither %-formatting nor <code class="docutils literal notranslate">string.Template</code> can control formatting such as: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> date = datetime.date(1991, 10, 12) >>> f'{date} was on a {date:%A}' '1991-10-12 was on a Saturday' </pre></div> </div> <section id="no-use-of-globals-or-locals"> <h3><a class="toc-backref" href="#no-use-of-globals-or-locals" role="doc-backlink">No use of globals() or locals()</a></h3> In the discussions on python-dev <a class="footnote-reference brackets" href="#id14" id="id4">[4]</a>, 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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' </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> def outer(x): ... def inner(): ... x ... return 'x={x}'.format_map(locals()) ... return inner ... >>> outer(42)() 'x=42' </pre></div> </div> 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 <a class="footnote-reference brackets" href="#id15" id="id5">[5]</a> 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.) </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> 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 <code class="docutils literal notranslate">'{'</code> and <code class="docutils literal notranslate">'}'</code>. While scanning the string for expressions, any doubled braces <code class="docutils literal notranslate">'{{'</code> or <code class="docutils literal notranslate">'}}'</code> 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 <code class="docutils literal notranslate">'}'</code> in the literal portion of a string is an error: literal closing curly braces must be doubled <code class="docutils literal notranslate">'}}'</code> in order to represent a single closing brace. The parts of the f-string outside of braces are literal strings. These literal portions are then decoded. For non-raw f-strings, this includes converting backslash escapes such as <code class="docutils literal notranslate">'\n'</code>, <code class="docutils literal notranslate">'\"'</code>, <code class="docutils literal notranslate">"\'"</code>, <code class="docutils literal notranslate">'\xhh'</code>, <code class="docutils literal notranslate">'\uxxxx'</code>, <code class="docutils literal notranslate">'\Uxxxxxxxx'</code>, and named unicode characters <code class="docutils literal notranslate">'\N{name}'</code> into their associated Unicode characters <a class="footnote-reference brackets" href="#id16" id="id6">[6]</a>. Backslashes may not appear anywhere within expressions. Comments, using the <code class="docutils literal notranslate">'#'</code> character, are not allowed inside an expression. Following each expression, an optional type conversion may be specified. The allowed conversions are <code class="docutils literal notranslate">'!s'</code>, <code class="docutils literal notranslate">'!r'</code>, or <code class="docutils literal notranslate">'!a'</code>. These are treated the same as in <code class="docutils literal notranslate">str.format()</code>: <code class="docutils literal notranslate">'!s'</code> calls <code class="docutils literal notranslate">str()</code> on the expression, <code class="docutils literal notranslate">'!r'</code> calls <code class="docutils literal notranslate">repr()</code> on the expression, and <code class="docutils literal notranslate">'!a'</code> calls <code class="docutils literal notranslate">ascii()</code> on the expression. These conversions are applied before the call to <code class="docutils literal notranslate">format()</code>. The only reason to use <code class="docutils literal notranslate">'!s'</code> is if you want to specify a format specifier that applies to <code class="docutils literal notranslate">str</code>, not to the type of the expression. F-strings use the same format specifier mini-language as <code class="docutils literal notranslate">str.format</code>. Similar to <code class="docutils literal notranslate">str.format()</code>, optional format specifiers maybe be included inside the f-string, separated from the expression (or the type conversion, if specified) by a colon. If a format specifier is not provided, an empty string is used. So, an f-string looks like: <div class="highlight-default notranslate"><div class="highlight"><pre>f ' <text> { <expression> <optional !s, !r, or !a> <optional : format specifier> } <text> ... ' </pre></div> </div> The expression is then formatted using the <code class="docutils literal notranslate">__format__</code> protocol, using the format specifier as an argument. The resulting value is used when building the value of the f-string. Note that <code class="docutils literal notranslate">__format__()</code> is not called directly on each value. The actual code uses the equivalent of <code class="docutils literal notranslate">type(value).__format__(value, format_spec)</code>, or <code class="docutils literal notranslate">format(value, format_spec)</code>. See the documentation of the builtin <code class="docutils literal notranslate">format()</code> function for more details. Expressions cannot contain <code class="docutils literal notranslate">':'</code> or <code class="docutils literal notranslate">'!'</code> outside of strings or parentheses, brackets, or braces. The exception is that the <code class="docutils literal notranslate">'!='</code> operator is allowed as a special case. <section id="escape-sequences"> <h3><a class="toc-backref" href="#escape-sequences" role="doc-backlink">Escape sequences</a></h3> Backslashes may not appear inside the expression portions of f-strings, so you cannot use them, for example, to escape quotes inside f-strings: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{\'quoted string\'}' File "<stdin>", line 1 SyntaxError: f-string expression part cannot include a backslash </pre></div> </div> You can use a different type of quote inside the expression: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{"quoted string"}' 'quoted string' </pre></div> </div> Backslash escapes may appear inside the string portions of an f-string. Note that the correct way to have a literal brace appear in the resulting string value is to double the brace: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{{ {4*10} }}' '{ 40 }' >>> f'{{{4*10}}}' '{40}' </pre></div> </div> Like all raw strings in Python, no escape processing is done for raw f-strings: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> fr'x={4*10}\n' 'x=40\\n' </pre></div> </div> Due to Python’s string tokenizing rules, the f-string <code class="docutils literal notranslate">f'abc {a['x']} def'</code> is invalid. The tokenizer parses this as 3 tokens: <code class="docutils literal notranslate">f'abc {a['</code>, <code class="docutils literal notranslate">x</code>, and <code class="docutils literal notranslate">']} def'</code>. Just like regular strings, this cannot be fixed by using raw strings. There are a number of correct ways to write this f-string: with a different quote character: <div class="highlight-default notranslate"><div class="highlight"><pre>f"abc {a['x']} def" </pre></div> </div> Or with triple quotes: <div class="highlight-default notranslate"><div class="highlight"><pre>f'''abc {a['x']} def''' </pre></div> </div> </section> <section id="code-equivalence"> <h3><a class="toc-backref" href="#code-equivalence" role="doc-backlink">Code equivalence</a></h3> The exact code used to implement f-strings is not specified. However, it is guaranteed that any embedded value that is converted to a string will use that value’s <code class="docutils literal notranslate">__format__</code> method. This is the same mechanism that <code class="docutils literal notranslate">str.format()</code> uses to convert values to strings. For example, this code: <div class="highlight-default notranslate"><div class="highlight"><pre>f'abc{expr1:spec1}{expr2!r:spec2}def{expr3}ghi' </pre></div> </div> Might be evaluated as: <div class="highlight-default notranslate"><div class="highlight"><pre>'abc' + format(expr1, spec1) + format(repr(expr2), spec2) + 'def' + format(expr3) + 'ghi' </pre></div> </div> </section> <section id="expression-evaluation"> <h3><a class="toc-backref" href="#expression-evaluation" role="doc-backlink">Expression evaluation</a></h3> The expressions that are extracted from the string are evaluated in the context where the f-string appeared. This means the expression has full access to local and global variables. Any valid Python expression can be used, including function and method calls. Because the f-strings are evaluated where the string appears in the source code, there is no additional expressiveness available with f-strings. There are also no additional security concerns: you could have also just written the same expression, not inside of an f-string: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> def foo(): ... return 20 ... >>> f'result={foo()}' 'result=20' </pre></div> </div> Is equivalent to: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 'result=' + str(foo()) 'result=20' </pre></div> </div> Expressions are parsed with the equivalent of <code class="docutils literal notranslate">ast.parse('(' + expression + ')', '<fstring>', 'eval')</code> <a class="footnote-reference brackets" href="#id17" id="id7">[7]</a>. Note that since the expression is enclosed by implicit parentheses before evaluation, expressions can contain newlines. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> x = 0 >>> f'''{x ... +1}''' '1' >>> d = {0: 'zero'} >>> f'''{d[0 ... ]}''' 'zero' </pre></div> </div> </section> <section id="format-specifiers"> <h3><a class="toc-backref" href="#format-specifiers" role="doc-backlink">Format specifiers</a></h3> Format specifiers may also contain evaluated expressions. This allows code such as: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> width = 10 >>> precision = 4 >>> value = decimal.Decimal('12.34567') >>> f'result: {value:{width}.{precision}}' 'result: 12.35' </pre></div> </div> Once expressions in a format specifier are evaluated (if necessary), format specifiers are not interpreted by the f-string evaluator. Just as in <code class="docutils literal notranslate">str.format()</code>, they are merely passed in to the <code class="docutils literal notranslate">__format__()</code> method of the object being formatted. </section> <section id="concatenating-strings"> <h3><a class="toc-backref" href="#concatenating-strings" role="doc-backlink">Concatenating strings</a></h3> Adjacent f-strings and regular strings are concatenated. Regular strings are concatenated at compile time, and f-strings are concatenated at run time. For example, the expression: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> x = 10 >>> y = 'hi' >>> 'a' 'b' f'{x}' '{c}' f'str<{y:^4}>' 'd' 'e' </pre></div> </div> yields the value: <div class="highlight-default notranslate"><div class="highlight"><pre>'ab10{c}str< hi >de' </pre></div> </div> While the exact method of this run time concatenation is unspecified, the above code might evaluate to: <div class="highlight-default notranslate"><div class="highlight"><pre>'ab' + format(x) + '{c}' + 'str<' + format(y, '^4') + '>de' </pre></div> </div> Each f-string is entirely evaluated before being concatenated to adjacent f-strings. That means that this: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{x' f'}' </pre></div> </div> Is a syntax error, because the first f-string does not contain a closing brace. </section> <section id="error-handling"> <h3><a class="toc-backref" href="#error-handling" role="doc-backlink">Error handling</a></h3> Either compile time or run time errors can occur when processing f-strings. Compile time errors are limited to those errors that can be detected when scanning an f-string. These errors all raise <code class="docutils literal notranslate">SyntaxError</code>. Unmatched braces: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'x={x' File "<stdin>", line 1 SyntaxError: f-string: expecting '}' </pre></div> </div> Invalid expressions: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'x={!x}' File "<stdin>", line 1 SyntaxError: f-string: empty expression not allowed </pre></div> </div> Run time errors occur when evaluating the expressions inside an f-string. Note that an f-string can be evaluated multiple times, and work sometimes and raise an error at other times: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d = {0:10, 1:20} >>> for i in range(3): ... print(f'{i}:{d[i]}') ... 0:10 1:20 Traceback (most recent call last): File "<stdin>", line 2, in <module> KeyError: 2 </pre></div> </div> or: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> for x in (32, 100, 'fifty'): ... print(f'x = {x:+3}') ... 'x = +32' 'x = +100' Traceback (most recent call last): File "<stdin>", line 2, in <module> ValueError: Sign not allowed in string format specifier </pre></div> </div> </section> <section id="leading-and-trailing-whitespace-in-expressions-is-ignored"> <h3><a class="toc-backref" href="#leading-and-trailing-whitespace-in-expressions-is-ignored" role="doc-backlink">Leading and trailing whitespace in expressions is ignored</a></h3> For ease of readability, leading and trailing whitespace in expressions is ignored. This is a by-product of enclosing the expression in parentheses before evaluation. </section> <section id="evaluation-order-of-expressions"> <h3><a class="toc-backref" href="#evaluation-order-of-expressions" role="doc-backlink">Evaluation order of expressions</a></h3> The expressions in an f-string are evaluated in left-to-right order. This is detectable only if the expressions have side effects: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> def fn(l, incr): ... result = l[0] ... l[0] += incr ... return result ... >>> lst = [0] >>> f'{fn(lst,2)} {fn(lst,3)}' '0 2' >>> f'{fn(lst,2)} {fn(lst,3)}' '5 7' >>> lst [10] </pre></div> </div> </section> </section> <section id="discussion"> <h2><a class="toc-backref" href="#discussion" role="doc-backlink">Discussion</a></h2> <section id="python-ideas-discussion"> <h3><a class="toc-backref" href="#python-ideas-discussion" role="doc-backlink">python-ideas discussion</a></h3> Most of the discussions on python-ideas <a class="footnote-reference brackets" href="#id18" id="id8">[8]</a> focused on three issues: <ul class="simple"> <li>How to denote f-strings,</li> <li>How to specify the location of expressions in f-strings, and</li> <li>Whether to allow full Python expressions.</li> </ul> <section id="how-to-denote-f-strings"> <h4><a class="toc-backref" href="#how-to-denote-f-strings" role="doc-backlink">How to denote f-strings</a></h4> Because the compiler must be involved in evaluating the expressions contained in the interpolated strings, there must be some way to denote to the compiler which strings should be evaluated. This PEP chose a leading <code class="docutils literal notranslate">'f'</code> character preceding the string literal. This is similar to how <code class="docutils literal notranslate">'b'</code> and <code class="docutils literal notranslate">'r'</code> prefixes change the meaning of the string itself, at compile time. Other prefixes were suggested, such as <code class="docutils literal notranslate">'i'</code>. No option seemed better than the other, so <code class="docutils literal notranslate">'f'</code> was chosen. Another option was to support special functions, known to the compiler, such as <code class="docutils literal notranslate">Format()</code>. This seems like too much magic for Python: not only is there a chance for collision with existing identifiers, the PEP author feels that it’s better to signify the magic with a string prefix character. </section> <section id="how-to-specify-the-location-of-expressions-in-f-strings"> <h4><a class="toc-backref" href="#how-to-specify-the-location-of-expressions-in-f-strings" role="doc-backlink">How to specify the location of expressions in f-strings</a></h4> This PEP supports the same syntax as <code class="docutils literal notranslate">str.format()</code> for distinguishing replacement text inside strings: expressions are contained inside braces. There were other options suggested, such as <code class="docutils literal notranslate">string.Template</code>’s <code class="docutils literal notranslate">$identifier</code> or <code class="docutils literal notranslate">${expression}</code>. While <code class="docutils literal notranslate">$identifier</code> is no doubt more familiar to shell scripters and users of some other languages, in Python <code class="docutils literal notranslate">str.format()</code> is heavily used. A quick search of Python’s standard library shows only a handful of uses of <code class="docutils literal notranslate">string.Template</code>, but hundreds of uses of <code class="docutils literal notranslate">str.format()</code>. Another proposed alternative was to have the substituted text between <code class="docutils literal notranslate">\{</code> and <code class="docutils literal notranslate">}</code> or between <code class="docutils literal notranslate">\{</code> and <code class="docutils literal notranslate">\}</code>. While this syntax would probably be desirable if all string literals were to support interpolation, this PEP only supports strings that are already marked with the leading <code class="docutils literal notranslate">'f'</code>. As such, the PEP is using unadorned braces to denoted substituted text, in order to leverage end user familiarity with <code class="docutils literal notranslate">str.format()</code>. </section> <section id="supporting-full-python-expressions"> <h4><a class="toc-backref" href="#supporting-full-python-expressions" role="doc-backlink">Supporting full Python expressions</a></h4> Many people on the python-ideas discussion wanted support for either only single identifiers, or a limited subset of Python expressions (such as the subset supported by <code class="docutils literal notranslate">str.format()</code>). This PEP supports full Python expressions inside the braces. Without full expressions, some desirable usage would be cumbersome. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'Column={col_idx+1}' >>> f'number of items: {len(items)}' </pre></div> </div> would become: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> col_number = col_idx+1 >>> f'Column={col_number}' >>> n_items = len(items) >>> f'number of items: {n_items}' </pre></div> </div> While it’s true that very ugly expressions could be included in the f-strings, this PEP takes the position that such uses should be addressed in a linter or code review: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'mapping is { {a:b for (a, b) in ((1, 2), (3, 4))} }' 'mapping is {1: 2, 3: 4}' </pre></div> </div> </section> </section> <section id="similar-support-in-other-languages"> <h3><a class="toc-backref" href="#similar-support-in-other-languages" role="doc-backlink">Similar support in other languages</a></h3> Wikipedia has a good discussion of string interpolation in other programming languages <a class="footnote-reference brackets" href="#id19" id="id9">[9]</a>. This feature is implemented in many languages, with a variety of syntaxes and restrictions. </section> <section id="differences-between-f-string-and-str-format-expressions"> <h3><a class="toc-backref" href="#differences-between-f-string-and-str-format-expressions" role="doc-backlink">Differences between f-string and str.format expressions</a></h3> There is one small difference between the limited expressions allowed in <code class="docutils literal notranslate">str.format()</code> and the full expressions allowed inside f-strings. The difference is in how index lookups are performed. In <code class="docutils literal notranslate">str.format()</code>, index values that do not look like numbers are converted to strings: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d = {'a': 10, 'b': 20} >>> 'a={d[a]}'.format(d=d) 'a=10' </pre></div> </div> Notice that the index value is converted to the string <code class="docutils literal notranslate">'a'</code> when it is looked up in the dict. However, in f-strings, you would need to use a literal for the value of <code class="docutils literal notranslate">'a'</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'a={d["a"]}' 'a=10' </pre></div> </div> This difference is required because otherwise you would not be able to use variables as index values: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> a = 'b' >>> f'a={d[a]}' 'a=20' </pre></div> </div> See <a class="footnote-reference brackets" href="#id20" id="id10">[10]</a> for a further discussion. It was this observation that led to full Python expressions being supported in f-strings. Furthermore, the limited expressions that <code class="docutils literal notranslate">str.format()</code> understands need not be valid Python expressions. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> '{i[";]}'.format(i={'";':4}) '4' </pre></div> </div> For this reason, the str.format() “expression parser” is not suitable for use when implementing f-strings. </section> <section id="triple-quoted-f-strings"> <h3><a class="toc-backref" href="#triple-quoted-f-strings" role="doc-backlink">Triple-quoted f-strings</a></h3> Triple quoted f-strings are allowed. These strings are parsed just as normal triple-quoted strings are. After parsing and decoding, the normal f-string logic is applied, and <code class="docutils literal notranslate">__format__()</code> is called on each value. </section> <section id="raw-f-strings"> <h3><a class="toc-backref" href="#raw-f-strings" role="doc-backlink">Raw f-strings</a></h3> Raw and f-strings may be combined. For example, they could be used to build up regular expressions: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> header = 'Subject' >>> fr'{header}:\s+' 'Subject:\\s+' </pre></div> </div> In addition, raw f-strings may be combined with triple-quoted strings. </section> <section id="no-binary-f-strings"> <h3><a class="toc-backref" href="#no-binary-f-strings" role="doc-backlink">No binary f-strings</a></h3> For the same reason that we don’t support <code class="docutils literal notranslate">bytes.format()</code>, you may not combine <code class="docutils literal notranslate">'f'</code> with <code class="docutils literal notranslate">'b'</code> string literals. The primary problem is that an object’s <code class="docutils literal notranslate">__format__()</code> method may return Unicode data that is not compatible with a bytes string. Binary f-strings would first require a solution for <code class="docutils literal notranslate">bytes.format()</code>. This idea has been proposed in the past, most recently in <a class="pep reference internal" href="../pep-0461/#proposed-variations" title="PEP 461 – Adding % formatting to bytes and bytearray § Proposed variations">PEP 461</a>. The discussions of such a feature usually suggest either <ul class="simple"> <li>adding a method such as <code class="docutils literal notranslate">__bformat__()</code> so an object can control how it is converted to bytes, or</li> <li>having <code class="docutils literal notranslate">bytes.format()</code> not be as general purpose or extensible as <code class="docutils literal notranslate">str.format()</code>.</li> </ul> Both of these remain as options in the future, if such functionality is desired. </section> <section id="s-r-and-a-are-redundant"> <h3><a class="toc-backref" href="#s-r-and-a-are-redundant" role="doc-backlink"><code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> are redundant</a></h3> The <code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> conversions are not strictly required. Because arbitrary expressions are allowed inside the f-strings, this code: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> a = 'some string' >>> f'{a!r}' "'some string'" </pre></div> </div> Is identical to: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{repr(a)}' "'some string'" </pre></div> </div> Similarly, <code class="docutils literal notranslate">!s</code> can be replaced by calls to <code class="docutils literal notranslate">str()</code> and <code class="docutils literal notranslate">!a</code> by calls to <code class="docutils literal notranslate">ascii()</code>. However, <code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> are supported by this PEP in order to minimize the differences with <code class="docutils literal notranslate">str.format()</code>. <code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> are required in <code class="docutils literal notranslate">str.format()</code> because it does not allow the execution of arbitrary expressions. </section> <section id="lambdas-inside-expressions"> <h3><a class="toc-backref" href="#lambdas-inside-expressions" role="doc-backlink">Lambdas inside expressions</a></h3> Because lambdas use the <code class="docutils literal notranslate">':'</code> character, they cannot appear outside of parentheses in an expression. The colon is interpreted as the start of the format specifier, which means the start of the lambda expression is seen and is syntactically invalid. As there’s no practical use for a plain lambda in an f-string expression, this is not seen as much of a limitation. If you feel you must use lambdas, they may be used inside of parentheses: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> f'{(lambda x: x*2)(3)}' '6' </pre></div> </div> </section> <section id="can-t-combine-with-u"> <h3><a class="toc-backref" href="#can-t-combine-with-u" role="doc-backlink">Can’t combine with ‘u’</a></h3> The ‘u’ prefix was added to Python 3.3 in <a class="pep reference internal" href="../pep-0414/" title="PEP 414 – Explicit Unicode Literal for Python 3.3">PEP 414</a> as a means to ease source compatibility with Python 2.7. Because Python 2.7 will never support f-strings, there is nothing to be gained by being able to combine the ‘f’ prefix with ‘u’. </section> </section> <section id="examples-from-python-s-source-code"> <h2><a class="toc-backref" href="#examples-from-python-s-source-code" role="doc-backlink">Examples from Python’s source code</a></h2> Here are some examples from Python source code that currently use <code class="docutils literal notranslate">str.format()</code>, and how they would look with f-strings. This PEP does not recommend wholesale converting to f-strings, these are just examples of real-world usages of <code class="docutils literal notranslate">str.format()</code> and how they’d look if written from scratch using f-strings. <code class="docutils literal notranslate">Lib/asyncio/locks.py</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>extra = '{},waiters:{}'.format(extra, len(self._waiters)) extra = f'{extra},waiters:{len(self._waiters)}' </pre></div> </div> <code class="docutils literal notranslate">Lib/configparser.py</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>message.append(" [line {0:2d}]".format(lineno)) message.append(f" [line {lineno:2d}]") </pre></div> </div> <code class="docutils literal notranslate">Tools/clinic/clinic.py</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>methoddef_name = "{}_METHODDEF".format(c_basename.upper()) methoddef_name = f"{c_basename.upper()}_METHODDEF" </pre></div> </div> <code class="docutils literal notranslate">python-config.py</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>print("Usage: {0} [{1}]".format(sys.argv[0], '|'.join('--'+opt for opt in valid_opts)), file=sys.stderr) print(f"Usage: {sys.argv[0]} [{'|'.join('--'+opt for opt in valid_opts)}]", file=sys.stderr) </pre></div> </div> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id11" role="doc-footnote"> <dt class="label" id="id11">[<a href="#id1">1</a>]</dt> <dd>%-formatting (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting">https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting</a>)</aside> <aside class="footnote brackets" id="id12" role="doc-footnote"> <dt class="label" id="id12">[<a href="#id2">2</a>]</dt> <dd>str.format (<a class="reference external" href="https://docs.python.org/3/library/string.html#formatstrings">https://docs.python.org/3/library/string.html#formatstrings</a>)</aside> <aside class="footnote brackets" id="id13" role="doc-footnote"> <dt class="label" id="id13">[<a href="#id3">3</a>]</dt> <dd>string.Template documentation (<a class="reference external" href="https://docs.python.org/3/library/string.html#template-strings">https://docs.python.org/3/library/string.html#template-strings</a>)</aside> <aside class="footnote brackets" id="id14" role="doc-footnote"> <dt class="label" id="id14">[<a href="#id4">4</a>]</dt> <dd>Formatting using locals() and globals() (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2015-July/034671.html">https://mail.python.org/pipermail/python-ideas/2015-July/034671.html</a>)</aside> <aside class="footnote brackets" id="id15" role="doc-footnote"> <dt class="label" id="id15">[<a href="#id5">5</a>]</dt> <dd>Avoid locals() and globals() (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2015-July/034701.html">https://mail.python.org/pipermail/python-ideas/2015-July/034701.html</a>)</aside> <aside class="footnote brackets" id="id16" role="doc-footnote"> <dt class="label" id="id16">[<a href="#id6">6</a>]</dt> <dd>String literal description (<a class="reference external" href="https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals">https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals</a>)</aside> <aside class="footnote brackets" id="id17" role="doc-footnote"> <dt class="label" id="id17">[<a href="#id7">7</a>]</dt> <dd>ast.parse() documentation (<a class="reference external" href="https://docs.python.org/3/library/ast.html#ast.parse">https://docs.python.org/3/library/ast.html#ast.parse</a>)</aside> <aside class="footnote brackets" id="id18" role="doc-footnote"> <dt class="label" id="id18">[<a href="#id8">8</a>]</dt> <dd>Start of python-ideas discussion (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2015-July/034657.html">https://mail.python.org/pipermail/python-ideas/2015-July/034657.html</a>)</aside> <aside class="footnote brackets" id="id19" role="doc-footnote"> <dt class="label" id="id19">[<a href="#id9">9</a>]</dt> <dd>Wikipedia article on string interpolation (<a class="reference external" href="https://en.wikipedia.org/wiki/String_interpolation">https://en.wikipedia.org/wiki/String_interpolation</a>)</aside> <aside class="footnote brackets" id="id20" role="doc-footnote"> <dt class="label" id="id20">[<a href="#id10">10</a>]</dt> <dd>Differences in str.format() and f-string expressions (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2015-July/034726.html">https://mail.python.org/pipermail/python-ideas/2015-July/034726.html</a>)</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0498.rst">https://github.com/python/peps/blob/main/peps/pep-0498.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0498.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#no-use-of-globals-or-locals">No use of globals() or locals()</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#escape-sequences">Escape sequences</a></li> <li><a class="reference internal" href="#code-equivalence">Code equivalence</a></li> <li><a class="reference internal" href="#expression-evaluation">Expression evaluation</a></li> <li><a class="reference internal" href="#format-specifiers">Format specifiers</a></li> <li><a class="reference internal" href="#concatenating-strings">Concatenating strings</a></li> <li><a class="reference internal" href="#error-handling">Error handling</a></li> <li><a class="reference internal" href="#leading-and-trailing-whitespace-in-expressions-is-ignored">Leading and trailing whitespace in expressions is ignored</a></li> <li><a class="reference internal" href="#evaluation-order-of-expressions">Evaluation order of expressions</a></li> </ul> </li> <li><a class="reference internal" href="#discussion">Discussion</a><ul> <li><a class="reference internal" href="#python-ideas-discussion">python-ideas discussion</a><ul> <li><a class="reference internal" href="#how-to-denote-f-strings">How to denote f-strings</a></li> <li><a class="reference internal" href="#how-to-specify-the-location-of-expressions-in-f-strings">How to specify the location of expressions in f-strings</a></li> <li><a class="reference internal" href="#supporting-full-python-expressions">Supporting full Python expressions</a></li> </ul> </li> <li><a class="reference internal" href="#similar-support-in-other-languages">Similar support in other languages</a></li> <li><a class="reference internal" href="#differences-between-f-string-and-str-format-expressions">Differences between f-string and str.format expressions</a></li> <li><a class="reference internal" href="#triple-quoted-f-strings">Triple-quoted f-strings</a></li> <li><a class="reference internal" href="#raw-f-strings">Raw f-strings</a></li> <li><a class="reference internal" href="#no-binary-f-strings">No binary f-strings</a></li> <li><a class="reference internal" href="#s-r-and-a-are-redundant"><code class="docutils literal notranslate">!s</code>, <code class="docutils literal notranslate">!r</code>, and <code class="docutils literal notranslate">!a</code> are redundant</a></li> <li><a class="reference internal" href="#lambdas-inside-expressions">Lambdas inside expressions</a></li> <li><a class="reference internal" href="#can-t-combine-with-u">Can’t combine with ‘u’</a></li> </ul> </li> <li><a class="reference internal" href="#examples-from-python-s-source-code">Examples from Python’s source code</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0498.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>