This is the documentation for the latest development branch of MicroPython and may refer to features that are not available in released versions.

If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

`string.templatelib` – Template String Support

This module provides support for template strings (t-strings) as defined in PEP 750. Template strings are created using the t prefix and provide access to both the literal string parts and interpolated values before they are combined.

Availability: template strings require MICROPY_PY_TSTRINGS to be enabled at compile time. They are enabled by default at the full feature level, which includes the alif, mimxrt and samd (SAMD51 only) ports, the unix coverage variant and the webassembly pyscript variant.

Classes

class string.templatelib.Template(*args)

Represents a template string. Template objects are typically created by t-string syntax (t"...") but can also be constructed directly using the constructor.

strings: A tuple of string literals that appear between interpolations.

interpolations: A tuple of Interpolation objects representing the interpolated expressions.

values: A read-only property that returns a tuple containing the value attribute from each interpolation in the template.

__iter__(): Iterate over the template contents, yielding string parts and Interpolation objects in the order they appear. Empty strings are omitted.

__add__(other)

Concatenate two templates. Returns a new Template combining the strings and interpolations from both templates.

Raises:: TypeError – if other is not a Template

Template concatenation with str is prohibited to avoid ambiguity about whether the string should be treated as a literal or interpolation:

t1 = t"Hello "
t2 = t"World"
result = t1 + t2  # Valid

# TypeError: cannot concatenate str to Template
result = t1 + "World"

class string.templatelib.Interpolation(value, expression='', conversion=None, format_spec='')

Represents an interpolated expression within a template string. All arguments can be passed as keyword arguments.

value: The evaluated value of the interpolated expression.

expression: The string representation of the expression as it appeared in the template string.

conversion: The conversion specifier ('s' or 'r') if present, otherwise None. Note that MicroPython does not support the 'a' conversion.

format_spec: The format specification string if present, otherwise an empty string.

Template String Syntax

Template strings use the same syntax as f-strings but with a t prefix:

name = "World"
template = t"Hello {name}!"

# Access template components
print(template.strings)        # ('Hello ', '!')
print(template.values)         # ('World',)
print(template.interpolations[0].expression)  # 'name'

Conversion Specifiers

Template strings store conversion specifiers as metadata. Unlike f-strings, the conversion is not applied automatically:

value = "test"
t = t"{value!r}"
# t.interpolations[0].value == "test" (not repr(value))
# t.interpolations[0].conversion == "r"

Processing code must explicitly apply conversions when needed.

Format Specifications

Format specifications are stored as metadata in the Interpolation object. Unlike f-strings, formatting is not applied automatically:

pi = 3.14159
t = t"{pi:.2f}"
# t.interpolations[0].value == 3.14159 (not formatted)
# t.interpolations[0].format_spec == ".2f"

Per PEP 750, processing code is not required to use format specifications, but when present they should be respected and match f-string behavior where possible.

Debug Format

The debug format {expr=} is supported:

x = 42
t = t"{x=}"
# t.strings == ("x=", "")
# t.interpolations[0].expression == "x"
# t.interpolations[0].conversion == "r"

Important

As per PEP 750, unlike f-strings, template strings do not automatically apply conversions or format specifications. This is by design to allow processing code to control how these are handled. Processing code must explicitly handle these attributes.

MicroPython does not provide the format() built-in function. Use string formatting methods like str.format() instead.

Example Usage

Basic processing without format support:

def simple_process(template):
    """Simple template processing"""
    parts = []
    for item in template:
        if isinstance(item, str):
            parts.append(item)
        else:
            parts.append(str(item.value))
    return "".join(parts)

Processing template with format support:

from string.templatelib import Template, Interpolation

def convert(value, conversion):
    """Apply conversion specifier to value"""
    if conversion == "r":
        return repr(value)
    elif conversion == "s":
        return str(value)
    return value

def process_template(template):
    """Process template with conversion and format support"""
    result = []
    for part in template:
        if isinstance(part, str):
            result.append(part)
        else:  # Interpolation
            value = convert(part.value, part.conversion)
            if part.format_spec:
                # Apply format specification using str.format
                value = ("{:" + part.format_spec + "}").format(value)
            else:
                value = str(value)
            result.append(value)
    return "".join(result)

pi = 3.14159
name = "Alice"
t = t"{name!r}: {pi:.2f}"
print(process_template(t))
# Output: "'Alice': 3.14"

# Other format specifications work too
value = 42
print(process_template(t"{value:>10}"))  # "        42"
print(process_template(t"{value:04d}"))  # "0042"

HTML escaping example:

def html_escape(value):
    """Escape HTML special characters"""
    if not isinstance(value, str):
        value = str(value)
    return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

def safe_html(template):
    """Convert template to HTML-safe string"""
    result = []
    for part in template:
        if isinstance(part, str):
            result.append(part)
        else:
            result.append(html_escape(part.value))
    return "".join(result)

user_input = "<script>alert('xss')</script>"
t = t"User said: {user_input}"
print(safe_html(t))
# Output: "User said: &lt;script&gt;alert('xss')&lt;/script&gt;"

string.templatelib – Template String Support