Python 3.14 t-string 怎么用：别把 Template 当成普通字符串

给内部日志加一层脱敏时，很多项目最初的写法都是先拼好 f-string，再用正则补救。字段一多就容易出问题：哪些片段是固定文案、哪些值来自插值、某个 !r 或 :.2f 该不该保留，早就混在一条普通字符串里分不清了。Python 3.14 新增的 t-string 刚好把这层边界留了下来：花括号里的值已经完成计算，但静态文本和插值对象还没被自动合并成 str。

日志脱敏场景里，f-string 为什么已经来不及了

假设接口日志需要展示服务名和重试次数，但手机号、令牌一类字段要按规则隐藏。用 f-string 时，f"service={service}, token={token}" 在赋值那一刻已经变成完整文本，后续处理函数看到的只是一堆字符。你当然可以重新解析字符串，可那意味着还要自行适配等号、逗号和各种转义规则，格式稍有改动就容易匹配失败。

t-string 的目标不是替换所有 f-string，而是在「拼接前还要检查一遍插值」的位置，给处理函数一个可靠的操作入口。官方文档把它定义为自定义字符串处理机制：静态字符串片段和花括号里的插值会以 Template 对象暴露出来。

最小写法：t 前缀返回的是 Template

先把它和 f-string 区分开。下面的 message 不是 str，所以不要直接把它传给只接受普通字符串的旧接口。它自带静态文本、插值对象以及插值值的完整列表。

from string.templatelib import Template

service = "billing-api"
retry = 3
message = t"service={service}, retry={retry:02d}"

print(isinstance(message, Template))
print(message.strings)
print(message.values)
print(message.interpolations[1].format_spec)

运行后你会得到一个 Template、两个以上静态片段、两个插值值，以及第二个插值的 02d 格式说明。官方文档还做了明确约定：strings 的元素数始终比 interpolations 和 values 多一个，因为每个插值都夹在相邻的文本片段中间。

真正的变化在处理函数：由它决定怎样合并

t-string 不会替你自动套用 !r、!s 或格式说明，这是特意留出的控制点。一个最小的纯文本处理函数可以使用标准库的 convert，再把格式说明交给 format。生产环境如果要做 HTML、SQL 或其他领域的专用文本处理，还要按对应场景的规则自行设计，不要直接照搬这段演示函数。

from string.templatelib import Template, convert

def render_text(template: Template) -> str:
    parts: list[str] = []
    for item in template:
        if isinstance(item, str):
            parts.append(item)
            continue

        value = convert(item.value, item.conversion)
        parts.append(format(value, item.format_spec))
    return "".join(parts)

service = "billing-api"
retry = 3
result = render_text(t"service={service}, retry={retry:02d}")
print(result)  # service=billing-api, retry=03

这段代码写得很精简，仅用来展示「谁负责合并」的分工。对于普通纯文本场景，直接用 f-string 的写法通常更省事；当处理函数需要逐个检查 Interpolation 的值、表达式文本、转换标记或格式说明时，换成 t-string 才能体现出优势。

三个容易误判的边界

花括号里的表达式没有延后执行

t-string 的字面量外观和 f-string 很像，插值表达式同样在创建模板的那一刻就立即计算。不要把它当成「先收集、后面再运算」的任务队列，它提供的是对已经拿到的插值信息的二次处理能力。

Template 不能和 str 直接相加

官方文档明确说明，Template + Template 之间可以互相组合，但 Template + str 不被支持，因为这类操作没法判断普通字符串应该被当成静态片段还是动态插值。需要拼接常量的时候，显式构造 Template；需要拼接动态值的时候，使用 Interpolation，就能保持语义清晰不混淆。

外部用户文本不等于 t-string 模板

t-string 是 Python 源码层面的字面量语法，适合开发者直接写在代码里、交给指定处理函数的模板。内容管理系统、数据库或者文件里存放的外部文本，仍然要走对应模板引擎的转义规则和权限逻辑处理；不要误以为「能看到插值结构」就自动解决了所有输入安全问题。

版本条件和迁移检查要写清楚

string.templatelib 与 t-string 在 Python 3.14 才加入标准库。如果项目的最低兼容版本低于 3.14，解释器在读取 t"..." 语法的阶段就会直接报错，没法靠运行时分支绕过。更稳妥的做法是把使用范围限制在已经统一升级的模块里，同时在持续集成流程中把 Python 版本固定下来。

1. 先确认部署环境、本地开发环境与 CI 流程都使用 Python 3.14 或更高版本。
2. 挑选一个确实需要插值审阅或上下文渲染的小模块试用，不要全项目替换现有 f-string。
3. 为处理函数补充完整的输入输出测试，覆盖普通值、!r、格式说明及敏感字段替换场景。
4. 保留原有模板方案的测试用例，尤其是外部文本、HTML 和数据库查询这类边界场景。

相关问题

t-string 能直接 print 吗？

不要默认它会像 f-string 一样自动转成最终文本。t-string 的结果是 Template，应该先交给对应场景的处理函数；只是简单展示内容的话，用 f-string 会更直接。

format_spec 一定会自动生效吗？

不会。它会被保存在 Interpolation.format_spec 中，要不要采用、怎么采用全由处理函数决定。上文的 render_text 用了 format，只是其中一种纯文本处理策略。

能把所有 f-string 改成 t-string 吗？

完全没必要。绝大多数 f-string 本来就是一次性生成文本的场景，改成 t-string 反而多了一步处理流程。只有需要观察或者转换插值的场景，Template 的结构才有引入的价值。

更完整的对象属性、拼接限制与转换辅助函数，可以查看 Python 官方 string.templatelib 文档；设计背景可以对照 PEP 750 了解。把 t-string 当成「可自定义处理的插值结构」，而不是新的字符串语法糖，使用边界自然就清晰了。