string.templatelib — Suporte a Template Strings

Este módulo fornece suporte a template strings (t-strings) conforme definido na PEP 750. As template strings são criadas usando o prefixo t e fornecem acesso tanto às partes literais da string quanto aos valores interpolados antes de serem combinados.

Disponibilidade: As template strings não são suportadas nas OpenMV Cams baseadas em STM32. Elas estão disponíveis apenas nas OpenMV Cams baseadas em Alif e i.MX RT.

Classes

class string.templatelib.Template(*args)

Representa uma template string. Objetos Template são tipicamente criados pela sintaxe de t-string (t"..."), mas também podem ser construídos diretamente usando o construtor.

strings

Uma tupla de literais de string que aparecem entre as interpolações.

interpolations

Uma tupla de objetos Interpolation representando as expressões interpoladas.

values

Uma propriedade somente leitura que retorna uma tupla contendo o atributo value de cada interpolação no template.

__iter__() → Iterator

Itera sobre o conteúdo do template, produzindo partes de string e objetos Interpolation na ordem em que aparecem. Strings vazias são omitidas.

__add__(other: Template) → Template

Concatena dois templates. Retorna um novo Template combinando as strings e interpolações de ambos os templates.

Levanta:

TypeError – se other não for um Template

A concatenação de template com str é proibida para evitar ambiguidade sobre se a string deve ser tratada como literal ou como interpolação:

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

# TypeError: cannot concatenate str to Template
result = t1 + "World"
class string.templatelib.Interpolation(value: Any, expression: str = '', conversion: str | None = None, format_spec: str = '')

Representa uma expressão interpolada dentro de uma template string. Todos os argumentos podem ser passados como argumentos nomeados.

value

O valor avaliado da expressão interpolada.

expression

A representação em string da expressão como ela apareceu na template string.

conversion

O especificador de conversão ('s' ou 'r') se presente, caso contrário None. Observe que o MicroPython não suporta a conversão 'a'.

format_spec

A string de especificação de formato, se presente, caso contrário uma string vazia.

Sintaxe das Template Strings

As template strings usam a mesma sintaxe das f-strings, mas com um prefixo t

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

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

Especificadores de Conversão

As template strings armazenam os especificadores de conversão como metadados. Ao contrário das f-strings, a conversão não é aplicada automaticamente:

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

O código de processamento deve aplicar as conversões explicitamente quando necessário.

Especificações de Formato

As especificações de formato são armazenadas como metadados no objeto Interpolation. Ao contrário das f-strings, a formatação não é aplicada automaticamente:

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

Conforme a PEP 750, o código de processamento não é obrigado a usar as especificações de formato, mas, quando presentes, elas devem ser respeitadas e corresponder ao comportamento das f-strings sempre que possível.

Formato de Depuração

O formato de depuração {expr=} é suportado:

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

Importante

Conforme a PEP 750, ao contrário das f-strings, as template strings não aplicam automaticamente conversões ou especificações de formato. Isso é intencional, para permitir que o código de processamento controle como essas são tratadas. O código de processamento deve tratar esses atributos explicitamente.

O MicroPython não fornece a função embutida format(). Use métodos de formatação de string como str.format() em vez disso.

Exemplo de Uso

Processamento básico sem suporte a formato:

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)

Processamento de template com suporte a formato:

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"

Exemplo de escape de HTML:

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;"

Veja Também