Files
FootPrint/Python/pythoncore-3.15-64/Doc/html/library/string.templatelib.html
T

727 lines
61 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="string.templatelib — Support for template string literals" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/string.templatelib.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/string/templatelib.py Template strings: Template strings are a mechanism for custom string processing. They have the full flexibility of Python’s f-strings, but return a Template i..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/string/templatelib.py Template strings: Template strings are a mechanism for custom string processing. They have the full flexibility of Python’s f-strings, but return a Template i..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>string.templatelib — Support for template string literals &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="re — Regular expression operations" href="re.html" />
<link rel="prev" title="string — Common string operations" href="string.html" />
<link rel="canonical" href="https://docs.python.org/3/library/string.templatelib.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">string.templatelib</span></code> — Support for template string literals</a><ul>
<li><a class="reference internal" href="#template-strings">Template strings</a></li>
<li><a class="reference internal" href="#types">Types</a></li>
<li><a class="reference internal" href="#helper-functions">Helper functions</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="string.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">string</span></code> — Common string operations</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="re.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">re</span></code> — Regular expression operations</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/string.templatelib.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/string.templatelib.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="re.html" title="re — Regular expression operations"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="string.html" title="string — Common string operations"
accesskey="P">previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="text.html" accesskey="U">Text Processing Services</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">string.templatelib</span></code> — Support for template string literals</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-string.templatelib">
<span id="string-templatelib-support-for-template-string-literals"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">string.templatelib</span></code> — Support for template string literals<a class="headerlink" href="#module-string.templatelib" title="Link to this heading"></a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/string/templatelib.py">Lib/string/templatelib.py</a></p>
<hr class="docutils" />
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<ul class="simple">
<li><p><a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">Format strings</span></a></p></li>
<li><p><a class="reference internal" href="../reference/lexical_analysis.html#t-strings"><span class="std std-ref">Template string literal (t-string) syntax</span></a></p></li>
<li><p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0750/"><strong>PEP 750</strong></a></p></li>
</ul>
</div>
<section id="template-strings">
<span id="id1"></span><h2>Template strings<a class="headerlink" href="#template-strings" title="Link to this heading"></a></h2>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
<p>Template strings are a mechanism for custom string processing.
They have the full flexibility of Python’s <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">f-strings</span></a>,
but return a <a class="reference internal" href="#string.templatelib.Template" title="string.templatelib.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> instance that gives access
to the static and interpolated (in curly brackets) parts of a string
<em>before</em> they are combined.</p>
<p>To write a t-string, use a <code class="docutils literal notranslate"><span class="pre">'t'</span></code> prefix instead of an <code class="docutils literal notranslate"><span class="pre">'f'</span></code>, like so:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">pi</span> <span class="o">=</span> <span class="mf">3.14</span>
<span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'t-strings are new in Python </span><span class="si">{</span><span class="n">pi</span><span class="si">!s}</span><span class="s1">!'</span>
<span class="go">Template(</span>
<span class="go"> strings=('t-strings are new in Python ', '!'),</span>
<span class="go"> interpolations=(Interpolation(3.14, 'pi', 's', ''),)</span>
<span class="go">)</span>
</pre></div>
</div>
</section>
<section id="types">
<h2>Types<a class="headerlink" href="#types" title="Link to this heading"></a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="string.templatelib.Template">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">string.templatelib.</span></span><span class="sig-name descname"><span class="pre">Template</span></span><a class="headerlink" href="#string.templatelib.Template" title="Link to this definition"></a></dt>
<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> class describes the contents of a template string.
It is immutable, meaning that attributes of a template cannot be reassigned.</p>
<p>The most common way to create a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> instance is to use the
<a class="reference internal" href="../reference/lexical_analysis.html#t-strings"><span class="std std-ref">template string literal syntax</span></a>.
This syntax is identical to that of <a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">f-strings</span></a>,
except that it uses a <code class="docutils literal notranslate"><span class="pre">t</span></code> prefix in place of an <code class="docutils literal notranslate"><span class="pre">f</span></code>:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Red Leicester'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s2">"We're fresh out of </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s2">, sir."</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">template</span><span class="p">)</span>
<span class="go">&lt;class 'string.templatelib.Template'&gt;</span>
</pre></div>
</div>
<p>Templates are stored as sequences of literal <a class="reference internal" href="#string.templatelib.Template.strings" title="string.templatelib.Template.strings"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strings</span></code></a>
and dynamic <a class="reference internal" href="#string.templatelib.Template.interpolations" title="string.templatelib.Template.interpolations"><code class="xref py py-attr docutils literal notranslate"><span class="pre">interpolations</span></code></a>.
A <a class="reference internal" href="#string.templatelib.Template.values" title="string.templatelib.Template.values"><code class="xref py py-attr docutils literal notranslate"><span class="pre">values</span></code></a> attribute holds the values of the interpolations:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('Ah! We do have ', '.')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">interpolations</span>
<span class="go">(Interpolation('Camembert', ...),)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">values</span>
<span class="go">('Camembert',)</span>
</pre></div>
</div>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">strings</span></code> tuple has one more element than <code class="xref py py-attr docutils literal notranslate"><span class="pre">interpolations</span></code>
and <code class="xref py py-attr docutils literal notranslate"><span class="pre">values</span></code>; the interpolations “belong” between the strings.
This may be easier to understand when tuples are aligned</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">template</span><span class="o">.</span><span class="n">strings</span><span class="p">:</span> <span class="p">(</span><span class="s1">'Ah! We do have '</span><span class="p">,</span> <span class="s1">'.'</span><span class="p">)</span>
<span class="n">template</span><span class="o">.</span><span class="n">values</span><span class="p">:</span> <span class="p">(</span> <span class="s1">'Camembert'</span><span class="p">,</span> <span class="p">)</span>
</pre></div>
</div>
<p class="rubric">Attributes</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Template.strings">
<span class="sig-name descname"><span class="pre">strings</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/stdtypes.html#tuple" title="tuple"><span class="pre">tuple</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#string.templatelib.Template.strings" title="Link to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../builtins/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> of the static strings in the template.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('Ah! We do have ', '.')</span>
</pre></div>
</div>
<p>Empty strings <em>are</em> included in the tuple:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">response</span> <span class="o">=</span> <span class="s1">'We do have '</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! </span><span class="si">{</span><span class="n">response</span><span class="si">}{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('Ah! ', '', '.')</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">strings</span></code> tuple is never empty, and always contains one more
string than the <code class="docutils literal notranslate"><span class="pre">interpolations</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code> tuples:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">''</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('',)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">''</span><span class="o">.</span><span class="n">values</span>
<span class="go">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="s1">'cheese'</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('', '')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="s1">'cheese'</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">values</span>
<span class="go">('cheese',)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Template.interpolations">
<span class="sig-name descname"><span class="pre">interpolations</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/stdtypes.html#tuple" title="tuple"><span class="pre">tuple</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#string.templatelib.Interpolation" title="string.templatelib.Interpolation"><span class="pre">Interpolation</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#string.templatelib.Template.interpolations" title="Link to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../builtins/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> of the interpolations in the template.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">interpolations</span>
<span class="go">(Interpolation('Camembert', 'cheese', None, ''),)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">interpolations</span></code> tuple may be empty and always contains one fewer
values than the <code class="docutils literal notranslate"><span class="pre">strings</span></code> tuple:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'Red Leicester'</span><span class="o">.</span><span class="n">interpolations</span>
<span class="go">()</span>
</pre></div>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Template.values">
<span class="sig-name descname"><span class="pre">values</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/stdtypes.html#tuple" title="tuple"><span class="pre">tuple</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="../builtins/functions.html#object" title="object"><span class="pre">object</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="p"><span class="pre">...</span></span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#string.templatelib.Template.values" title="Link to this definition"></a></dt>
<dd><p>A tuple of all interpolated values in the template.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">values</span>
<span class="go">('Camembert',)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">values</span></code> tuple always has the same length as the
<code class="docutils literal notranslate"><span class="pre">interpolations</span></code> tuple. It is always equivalent to
<code class="docutils literal notranslate"><span class="pre">tuple(i.value</span> <span class="pre">for</span> <span class="pre">i</span> <span class="pre">in</span> <span class="pre">template.interpolations)</span></code>.</p>
</dd></dl>
<p class="rubric">Methods</p>
<dl class="py method">
<dt class="sig sig-object py" id="string.templatelib.Template.__new__">
<span class="sig-name descname"><span class="pre">__new__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="#string.templatelib.Interpolation" title="string.templatelib.Interpolation"><span class="pre">Interpolation</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#string.templatelib.Template.__new__" title="Link to this definition"></a></dt>
<dd><p>While literal syntax is the most common way to create a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code>,
it is also possible to create them directly using the constructor:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">string.templatelib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Interpolation</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span>
<span class="gp">... </span> <span class="s1">'Ah! We do have '</span><span class="p">,</span> <span class="n">Interpolation</span><span class="p">(</span><span class="n">cheese</span><span class="p">,</span> <span class="s1">'cheese'</span><span class="p">),</span> <span class="s1">'.'</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">template</span><span class="p">)</span>
<span class="go">['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']</span>
</pre></div>
</div>
<p>If multiple strings are passed consecutively, they will be concatenated
into a single value in the <a class="reference internal" href="#string.templatelib.Template.strings" title="string.templatelib.Template.strings"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strings</span></code></a> attribute. For example,
the following code creates a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> with a single final string:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">string.templatelib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s1">'Ah! We do have '</span><span class="p">,</span> <span class="s1">'Camembert'</span><span class="p">,</span> <span class="s1">'.'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('Ah! We do have Camembert.',)</span>
</pre></div>
</div>
<p>If multiple interpolations are passed consecutively, they will be treated
as separate interpolations and an empty string will be inserted between them.
For example, the following code creates a template with empty placeholders
in the <a class="reference internal" href="#string.templatelib.Template.strings" title="string.templatelib.Template.strings"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strings</span></code></a> attribute:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">string.templatelib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Interpolation</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">Interpolation</span><span class="p">(</span><span class="s1">'Camembert'</span><span class="p">,</span> <span class="s1">'cheese'</span><span class="p">),</span>
<span class="gp">... </span> <span class="n">Interpolation</span><span class="p">(</span><span class="s1">'.'</span><span class="p">,</span> <span class="s1">'punctuation'</span><span class="p">),</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">strings</span>
<span class="go">('', '', '')</span>
</pre></div>
</div>
</dd></dl>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">iter(template)</span></span></dt>
<dd><p>Iterate over the template, yielding each non-empty string and
<a class="reference internal" href="#string.templatelib.Interpolation" title="string.templatelib.Interpolation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Interpolation</span></code></a> in the correct order:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="sa">t</span><span class="s1">'Ah! We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span><span class="p">)</span>
<span class="go">['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']</span>
</pre></div>
</div>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Empty strings are <strong>not</strong> included in the iteration:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">response</span> <span class="o">=</span> <span class="s1">'We do have '</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="sa">t</span><span class="s1">'Ah! </span><span class="si">{</span><span class="n">response</span><span class="si">}{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span><span class="p">)</span>
<span class="go">['Ah! ',</span>
<span class="go"> Interpolation('We do have ', 'response', None, ''),</span>
<span class="go"> Interpolation('Camembert', 'cheese', None, ''),</span>
<span class="go"> '.']</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">template</span> <span class="pre">+</span> <span class="pre">other</span></span></dt>
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">template</span> <span class="pre">+=</span> <span class="pre">other</span></span></dt>
<dd><p>Concatenate this template with another, returning a new
<code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> instance:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="sa">t</span><span class="s1">'Ah! '</span> <span class="o">+</span> <span class="sa">t</span><span class="s1">'We do have </span><span class="si">{</span><span class="n">cheese</span><span class="si">}</span><span class="s1">.'</span><span class="p">)</span>
<span class="go">['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']</span>
</pre></div>
</div>
<p>Concatenating a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> and a <code class="docutils literal notranslate"><span class="pre">str</span></code> is <strong>not</strong> supported.
This is because it is unclear whether the string should be treated as
a static string or an interpolation.
If you want to concatenate a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> with a string,
you should either wrap the string directly in a <code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code>
(to treat it as a static string)
or use an <code class="xref py py-class docutils literal notranslate"><span class="pre">Interpolation</span></code> (to treat it as dynamic):</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">string.templatelib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Interpolation</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'Ah! '</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Treat 'We do have ' as a static string</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">+=</span> <span class="n">Template</span><span class="p">(</span><span class="s1">'We do have '</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Treat cheese as an interpolation</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cheese</span> <span class="o">=</span> <span class="s1">'Camembert'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">+=</span> <span class="n">Template</span><span class="p">(</span><span class="n">Interpolation</span><span class="p">(</span><span class="n">cheese</span><span class="p">,</span> <span class="s1">'cheese'</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">template</span><span class="p">)</span>
<span class="go">['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')]</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="string.templatelib.Interpolation">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">string.templatelib.</span></span><span class="sig-name descname"><span class="pre">Interpolation</span></span><a class="headerlink" href="#string.templatelib.Interpolation" title="Link to this definition"></a></dt>
<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Interpolation</span></code> type represents an expression inside a template string.
It is immutable, meaning that attributes of an interpolation cannot be reassigned.</p>
<p>Interpolations support pattern matching, allowing you to match against
their attributes with the <a class="reference internal" href="../reference/compound_stmts.html#match"><span class="std std-ref">match statement</span></a>:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">string.templatelib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Interpolation</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">interpolation</span> <span class="o">=</span> <span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="mf">1.</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">2.</span><span class="si">:</span><span class="s1">.2f</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">interpolations</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">interpolation</span>
<span class="go">Interpolation(3.0, '1. + 2.', None, '.2f')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">match</span> <span class="n">interpolation</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">case</span> <span class="n">Interpolation</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">conversion</span><span class="p">,</span> <span class="n">format_spec</span><span class="p">):</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">conversion</span><span class="p">,</span> <span class="n">format_spec</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s1">' | '</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">3.0 | 1. + 2. | None | .2f</span>
</pre></div>
</div>
<p>Interpolations are <a class="reference internal" href="typing.html#generics"><span class="std std-ref">generic</span></a> over the types of their values.</p>
<p class="rubric">Attributes</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Interpolation.value">
<span class="sig-name descname"><span class="pre">value</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/functions.html#object" title="object"><span class="pre">object</span></a></em><a class="headerlink" href="#string.templatelib.Interpolation.value" title="Link to this definition"></a></dt>
<dd><p>The evaluated value of the interpolation.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="mi">1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">2</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">interpolations</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">value</span>
<span class="go">3</span>
</pre></div>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Interpolation.expression">
<span class="sig-name descname"><span class="pre">expression</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#string.templatelib.Interpolation.expression" title="Link to this definition"></a></dt>
<dd><p>For interpolations created by t-string literals, <code class="xref py py-attr docutils literal notranslate"><span class="pre">expression</span></code>
is the expression text found inside the curly brackets (<code class="docutils literal notranslate"><span class="pre">{</span></code> &amp; <code class="docutils literal notranslate"><span class="pre">}</span></code>),
including any whitespace, excluding the curly brackets themselves,
and ending before the first <code class="docutils literal notranslate"><span class="pre">!</span></code>, <code class="docutils literal notranslate"><span class="pre">:</span></code>, or <code class="docutils literal notranslate"><span class="pre">=</span></code> if any is present.
For manually created interpolations, <code class="xref py py-attr docutils literal notranslate"><span class="pre">expression</span></code> is the arbitrary
string provided when constructing the interpolation instance.</p>
<p>We recommend using valid Python expressions or the empty string for the
<code class="docutils literal notranslate"><span class="pre">expression</span></code> field of manually created <code class="xref py py-class docutils literal notranslate"><span class="pre">Interpolation</span></code>
instances, although this is not enforced at runtime.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="mi">1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">2</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">interpolations</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">expression</span>
<span class="go">'1 + 2'</span>
</pre></div>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Interpolation.conversion">
<span class="sig-name descname"><span class="pre">conversion</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="typing.html#typing.Literal" title="typing.Literal"><span class="pre">Literal</span></a><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'a'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'r'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'s'</span></span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="../builtins/constants.html#None" title="None"><span class="pre">None</span></a></em><a class="headerlink" href="#string.templatelib.Interpolation.conversion" title="Link to this definition"></a></dt>
<dd><p>The conversion to apply to the value, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">conversion</span></code> is the optional conversion to apply
to the value:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="mi">1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">2</span><span class="si">!a}</span><span class="s1">'</span><span class="o">.</span><span class="n">interpolations</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">conversion</span>
<span class="go">'a'</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unlike f-strings, where conversions are applied automatically,
the expected behavior with t-strings is that code that <em>processes</em> the
<code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code> will decide how to interpret and whether to apply
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">conversion</span></code>.
For convenience, the <a class="reference internal" href="#string.templatelib.convert" title="string.templatelib.convert"><code class="xref py py-func docutils literal notranslate"><span class="pre">convert()</span></code></a> function can be used to mimic
f-string conversion semantics.</p>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="string.templatelib.Interpolation.format_spec">
<span class="sig-name descname"><span class="pre">format_spec</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#string.templatelib.Interpolation.format_spec" title="Link to this definition"></a></dt>
<dd><p>The format specification to apply to the value.</p>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">format_spec</span></code> is an optional, arbitrary string
used as the format specification to present the value:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="sa">t</span><span class="s1">'</span><span class="si">{</span><span class="mi">1</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">2</span><span class="si">:</span><span class="s1">.2f</span><span class="si">}</span><span class="s1">'</span><span class="o">.</span><span class="n">interpolations</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">format_spec</span>
<span class="go">'.2f'</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unlike f-strings, where format specifications are applied automatically
via the <a class="reference internal" href="../builtins/functions.html#format" title="format"><code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code></a> protocol, the expected behavior with
t-strings is that code that <em>processes</em> the interpolation will
decide how to interpret and whether to apply the format specification.
As a result, <code class="xref py py-attr docutils literal notranslate"><span class="pre">format_spec</span></code> values in interpolations
can be arbitrary strings,
including those that do not conform to the <code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code> protocol.</p>
</div>
</dd></dl>
<p class="rubric">Methods</p>
<dl class="py method">
<dt class="sig sig-object py" id="string.templatelib.Interpolation.__new__">
<span class="sig-name descname"><span class="pre">__new__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="../builtins/functions.html#object" title="object"><span class="pre">object</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">expression</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">conversion</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="typing.html#typing.Literal" title="typing.Literal"><span class="pre">Literal</span></a><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'a'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'r'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'s'</span></span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="../builtins/constants.html#None" title="None"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format_spec</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><span class="pre">str</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#string.templatelib.Interpolation.__new__" title="Link to this definition"></a></dt>
<dd><p>Create a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Interpolation</span></code> object from component parts.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>value</strong> – The evaluated, in-scope result of the interpolation.</p></li>
<li><p><strong>expression</strong> – The text of a valid Python expression,
or an empty string.</p></li>
<li><p><strong>conversion</strong> – The <a class="reference internal" href="string.html#formatstrings"><span class="std std-ref">conversion</span></a> to be used,
one of <code class="docutils literal notranslate"><span class="pre">None</span></code>, <code class="docutils literal notranslate"><span class="pre">'a'</span></code>, <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, or <code class="docutils literal notranslate"><span class="pre">'s'</span></code>.</p></li>
<li><p><strong>format_spec</strong> – An optional, arbitrary string used as the
<a class="reference internal" href="string.html#formatspec"><span class="std std-ref">format specification</span></a> to present the value.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
</section>
<section id="helper-functions">
<h2>Helper functions<a class="headerlink" href="#helper-functions" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="string.templatelib.convert">
<span class="sig-prename descclassname"><span class="pre">string.templatelib.</span></span><span class="sig-name descname"><span class="pre">convert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">conversion</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#string.templatelib.convert" title="Link to this definition"></a></dt>
<dd><p>Applies formatted string literal <a class="reference internal" href="string.html#formatstrings-conversion"><span class="std std-ref">conversion</span></a>
semantics to the given object <em>obj</em>.
This is frequently useful for custom template string processing logic.</p>
<p>Three conversion flags are currently supported:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">'s'</span></code> which calls <a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> on the value (like <code class="docutils literal notranslate"><span class="pre">!s</span></code>),</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> which calls <a class="reference internal" href="../builtins/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> (like <code class="docutils literal notranslate"><span class="pre">!r</span></code>), and</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'a'</span></code> which calls <a class="reference internal" href="../builtins/functions.html#ascii" title="ascii"><code class="xref py py-func docutils literal notranslate"><span class="pre">ascii()</span></code></a> (like <code class="docutils literal notranslate"><span class="pre">!a</span></code>).</p></li>
</ul>
<p>If the conversion flag is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <em>obj</em> is returned unchanged.</p>
</dd></dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">string.templatelib</span></code> — Support for template string literals</a><ul>
<li><a class="reference internal" href="#template-strings">Template strings</a></li>
<li><a class="reference internal" href="#types">Types</a></li>
<li><a class="reference internal" href="#helper-functions">Helper functions</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="string.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">string</span></code> — Common string operations</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="re.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">re</span></code> — Regular expression operations</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/string.templatelib.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/string.templatelib.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="re.html" title="re — Regular expression operations"
>next</a> |</li>
<li class="right" >
<a href="string.html" title="string — Common string operations"
>previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="text.html" >Text Processing Services</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">string.templatelib</span></code> — Support for template string literals</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>