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#