Python string.templatelib 怎样读取模板中的插值对象

如果你需要在模板合并之前检查每一个动态值，Python 3.14 的 string.templatelib 已经把这条路径直接暴露出来：先用 t'' 创建 Template，再通过 template.interpolations 取得完整的 Interpolation 对象，或者用 template.values 只取得已经计算好的值。

官方地址：https://docs.python.org/3/library/string.templatelib.html

想读取插值对象时优先使用 interpolations；它同时保留值、原表达式、转换标记和格式规格。只需要动态值时才使用 values。注意 t-string 不会像 f-string 一样自动执行转换和格式化，最终解释权属于你的处理器。

先区分 Template 的静态片段和动态片段

模板字符串和 f-string 的写法很像，但前缀从 f 换成了 t。f-string 会马上得到一个普通字符串，t-string 则返回一个不可变的 Template，让静态文本和花括号里的插值保持可观察状态。

from string.templatelib import Template

name = "Ada"
score = 98.5
template = t"用户 {name} 的分数是 {score:.1f}"

# strings 保存模板中的静态片段，顺序与插值位置交错对应。
print(template.strings)
# interpolations 保存完整的 Interpolation 对象。
print(template.interpolations)
# values 只保留每个插值已经计算出的 value。
print(template.values)

这个例子中，strings 类似 ("用户 ", " 的分数是 ", "")，它永远比插值数量多一个；values 则类似 ("Ada", 98.5)。如果两个插值紧挨着，中间的空字符串也会保留在 strings 元组里，这对需要复原模板结构的处理器很重要。

用 interpolations 读取完整插值对象

template.interpolations 返回一个元组，元组里的每一项都是 Interpolation。它不是普通的字符串，而是一个不可变对象，专门记录某一个花括号表达式在创建模板时得到的结果。

price = 12.5
template = t"价格：{price!s:.2f}"
item = template.interpolations[0]

# value 是表达式计算后的对象，这里仍然是浮点数。
print(item.value)
# expression 是花括号中的表达式文本，不包含花括号和格式分隔符。
print(item.expression)
# conversion 是 !s、!r 或 !a；没有转换时为 None。
print(item.conversion)
# format_spec 保存冒号后的格式字符串，可以是任意文本。
print(item.format_spec)

对于 t"价格：{price!s:.2f}"，可以把四个属性理解成 value=12.5、expression="price"、conversion="s"、format_spec=".2f"。表达式文本适合日志、审计或自定义模板语法；value 才是当前作用域里已经求值后的对象。

官方文档还允许手动构造 Interpolation(value, expression, conversion, format_spec)。手动构造时，expression 建议使用合法 Python 表达式或空字符串，但运行时不会替你强制解析它。

理解转换和格式规格不会自动执行

这是 t-string 与 f-string 最容易混淆的地方。f-string 在求值时会执行 !s、!r、!a，并通过 format() 处理格式规格；t-string 只把这些意图记录在 Interpolation 中，交给后续处理代码决定是否采用。

from string.templatelib import convert

value = "Ada"
template = t"名称：{value!r:>10}"
item = template.interpolations[0]

# t-string 不会自动把 !r 和 >10 应用到结果上。
converted = convert(item.value, item.conversion)
# 格式规格也要由处理器显式执行，才能得到最终展示文本。
rendered = format(converted, item.format_spec)
print(rendered)

# 不接受模板格式化规则时，可以直接使用原始 value。
print(item.value)

convert() 是标准库提供的辅助函数，支持 None、s、r 和 a。但是否调用它、是否调用 format()，应由你的模板处理策略决定。例如日志系统可能希望保留原对象，安全输出器则可能只允许一组受控的格式规格。

另外，format_spec 在 Interpolation 中只是字符串，可以是任意内容，不保证符合 format() 协议。因此，面对外部输入时要先限制可接受的格式规格，再交给格式化函数。

封装一个可控的模板读取器

实际项目通常不会只打印一个字段，而是把模板转换成审计记录、渲染节点或消息队列事件。下面的读取器保留插值顺序，并把每个对象的四个属性整理成普通字典；它只读取，不执行表达式，也不擅自格式化。

def collect_interpolations(template):
    """提取模板中的插值元数据，不执行二次求值。"""
    records = []
    for index, item in enumerate(template.interpolations):
        # value 已在创建 t-string 时求值，读取它不会重新运行 expression。
        records.append({
            "index": index,
            "value": item.value,
            "expression": item.expression,
            "conversion": item.conversion,
            "format_spec": item.format_spec,
        })
    return records

user = {"name": "Ada", "score": 98.5}
template = t"{user['name']} 得分 {user['score']:.1f}"
for record in collect_interpolations(template):
    # 结构化输出便于日志、审计或后续渲染器继续处理。
    print(record)

这里有一个值得强调的生命周期边界：插值表达式在创建 t-string 时已经计算，读取 item.value 不会重新执行 item.expression。所以如果你要做延迟渲染，应该保存表达式文本和业务上下文，另行设计安全的求值规则，而不是把 expression 再交给 eval()。

按场景选择 values、interpolations 还是迭代 Template

三个入口解决的问题不同，可以按下面的方式选择：

迭代 Template 时，空字符串不会被产出，但 strings 属性仍然会保留它们。需要精确重建片段位置时使用 strings 和 interpolations；只需要顺序消费非空节点时，直接迭代更简洁。

def render_plain(template):
    """按模板顺序生成最简单的字符串，不应用 conversion 和 format_spec。"""
    parts = []
    for node in template:
        # 字符串直接保留，插值只取 value，避免隐式改变处理策略。
        if isinstance(node, str):
            parts.append(node)
        else:
            parts.append(str(node.value))
    return "".join(parts)

message = t"欢迎，{name}!"
print(render_plain(message))

如果要实现与 f-string 相近的效果，可以在处理插值节点时先调用 convert()，再根据受控规则调用 format()。不要因为看到 conversion 或 format_spec 就默认它们已经生效。

排查读取结果时的四个检查点

1. 确认运行环境是 Python 3.14 或更高版本，因为 string.templatelib 与 template string literal 是 3.14 引入的。
2. 只要需要表达式、转换或格式规格，就读取 interpolations，不要只看 values。
3. 把 value 当作已经求值的对象，把 expression 当作记录文本；不要把文本重新交给不受控的动态执行器。
4. 在自定义渲染器中显式决定是否执行 convert() 和 format()，并对格式规格设置允许范围。

归纳起来，读取模板中的插值对象并不需要解析字符串本身：Template.interpolations 已经提供了有序、不可变的对象集合；Template.values 则是只取结果的快捷路径。先按业务需要选择入口，再把转换和格式化放进自己的处理策略，模板结构就能保持清晰可控。

相关问题

Template.values 和 Interpolation.value 有什么区别？

values 是所有插值值组成的元组，Interpolation.value 是某一个插值对象里的对应单项；前者适合批量读取，后者适合连同表达式和格式元数据一起处理。

t-string 会自动把格式规格应用到值上吗？

不会。格式规格只记录在 format_spec 中，处理器需要自行决定是否调用 format()。

能否通过 expression 重新执行插值？

不应直接这样做。expression 是记录下来的文本，不是让程序重新执行的授权；需要延迟渲染时应设计受控的数据映射或明确的模板语言。