string.templatelib — Suporte a Strings de Modelo

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

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

Classes

class string.templatelib.Template(*args)

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

strings

Um tuplo de literais de string que aparecem entre interpolações.

interpolations

Um tuplo de objetos Interpolation que representam as expressões interpoladas.

values

Uma propriedade somente de leitura que devolve um tuplo contendo o atributo value de cada interpolação no modelo.

__iter__() → Iterator

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

__add__(other: Template) → Template

Concatena dois modelos. Devolve um novo Template que combina as strings e interpolações de ambos os modelos.

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 um literal ou 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 string de modelo. Todos os argumentos podem ser passados como argumentos de palavra-chave.

value

O valor avaliado da expressão interpolada.

expression

A representação em string da expressão tal como apareceu na string de modelo.

conversion

O especificador de conversão ('s' ou 'r') se presente, caso contrário None. Note 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 de Strings de Modelo

As strings de modelo usam a mesma sintaxe que as 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 strings de modelo armazenam 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 explicitamente as conversões 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"

De acordo com a PEP 750, o código de processamento não é obrigado a utilizar especificações de formato, mas quando presentes 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

De acordo com a PEP 750, ao contrário das f-strings, as strings de modelo não aplicam automaticamente conversões nem especificações de formato. Isto é intencional para permitir que o código de processamento controle como estes são tratados. O código de processamento deve tratar explicitamente estes atributos.

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

Exemplo de Utilização

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

Consulte Também