深入 ty 类型检查器：Python 3.14 模板字符串（t-string）的解析与类型推断实现

深入 ty 类型检查器：Python 3.14 模板字符串（t-string）的解析与类型推断实现

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

本篇技术指南围绕 Ruff 仓库中 ty 类型检查器的文档测试用例 t_strings.md，系统讲解 Python 3.14 新增的模板字符串（Template String，简称 t-string）在 ty 中的 AST 表示、类型推断行为与测试验证方式。读完本文，你将理解t"..."字面量为何被推断为string.templatelib.Template类型、ty 如何在源码层面处理 t-string 的插值元素与格式说明符，以及如何通过 mdtest 文档测试体系验证这一行为。

t-string 是什么：Python 3.14 的新字符串形态

模板字符串（t-string）是 Python 3.14 引入的新字符串字面量，语法形如t"..."（前缀为小写t）。与 f-string 的"求值后拼接"不同，t-string 将字符串的字面量片段与插值表达式分别保留，构造出可被安全消费的模板对象，供模板引擎等场景使用。

按关联文档 t_strings.md 的说明，t-string 具有两个核心事实：

1. 以字面量形式书写，是 Python 3.14 的新增语法；
2. 其对象类型为string.templatelib.Template，即标准库string.templatelib模块中的Template类。

文档开头特别标注了(NB:blackdoes not support Python 3.14 at the time of this writing)，提醒读者当前 Black 格式化器尚不支持 Python 3.14 语法，因此在 mdtest 用例中通过<!-- fmt:off -->指令关闭该代码块的格式化处理。

测试环境声明：锁定 Python 3.14

关联文档通过 TOML frontmatter 声明了 mdtest 用例的运行环境：

[environment] python-version = "3.14"

这是 mdtest（Markdown 文档测试）系统的标准环境配置：python-version指定类型检查器模拟的 Python 版本。ty 的类型推断逻辑会随目标 Python 版本动态切换——例如在 known.rs 中，KnownClass::Template被标注为PythonVersion::PY314起才可用的已知类，这意味着只有在 Python 3.14+ 的目标环境下，ty 才会把 t-string 推断为已知的Template类型。这也解释了该用例必须显式声明python-version = "3.14"的原因。

核心行为验证：空模板字符串的类型

关联文档给出的验证样例极为精简，却是整个测试用例的灵魂：

reveal_type(t"") # revealed: Template

reveal_type是类型检查器提供的特殊内建函数，mdtest 会解析该行注释中# revealed:后的期望类型，并与类型检查器的实际推断结果比对。这里验证的是空模板字符串t""的推断类型为Template——即使没有任何插值内容，t-string 字面量也不会退化为str，而是始终产生string.templatelib.Template的实例。

源码剖析一：t-string 的 AST 表示

要理解 ty 为何能得出Template这一结论，需要先看解析器对 t-string 的 AST 建模。在 nodes.rs 中，t-string 由一组相互关联的节点表示：

• ExprTString：t-string 表达式节点，其值由TStringValue承载；
• TStringValue：单个TString或多个TString（隐式拼接）的容器，内部通过TStringValueInner::Single/Concatenated区分，并提供as_slice()、iter()、is_empty()等遍历与判断方法；
• TString：单个 t-string 片段，包含flags（TStringFlags）与elements（插值元素列表）等字段；
• TStringFlags：描述 t-string 的修饰标志，如引号风格、是否三引号、前缀类型；
• TStringPrefix：前缀枚举，定义在 str_prefix.rs 中，分为Regular（普通t"..."）与Raw（原始 t-string，如tr"..."、tR"..."）。

从源码结构看，t-string 的 AST 设计与 f-string 高度对称：二者的插值元素都使用ast::InterpolatedStringElement枚举，分为Interpolation（插值片段）与Literal（字面量片段）两种。这为类型检查器复用 f-string 的遍历逻辑奠定了基础。

源码剖析二：infer_tstring_expression的推断流程

ty 对 t-string 的类型推断实现在 builder.rs 的infer_tstring_expression方法中，完整流程如下：

fn infer_tstring_expression(&mut self, tstring: &ast::ExprTString) -> Type<'db> { let db = self.db(); let ast::ExprTString { value, .. } = tstring; for tstring in value { for element in &tstring.elements { match element { ast::InterpolatedStringElement::Interpolation( tstring_interpolation_element, ) => { let ast::InterpolatedElement { expression, format_spec, .. } = tstring_interpolation_element; self.infer_expression(expression, TypeContext::default()); if let Some(format_spec) = format_spec { for element in format_spec.elements.interpolations() { self.infer_expression(&element.expression, TypeContext::default()); } } } ast::InterpolatedStringElement::Literal(_) => {} } } } KnownClass::Template.to_instance(db, self.program_environment()) }

这段实现揭示了三个关键行为：

1. 遍历所有插值表达式：对 t-string 的每个Interpolation元素，调用self.infer_expression推断其内嵌表达式的类型（例如t"{x}"中的x），保证 t-string 内部引用被正确纳入类型检查的范围；
2. 递归处理格式说明符：若插值元素携带format_spec（格式说明符），还会继续遍历其中的嵌套插值表达式——这与 f-string 的嵌套格式说明符处理保持一致；
3. 返回固定类型Template：无论插值内容如何，整个 t-string 表达式最终都构造KnownClass::Template的实例作为推断结果。

在 known.rs 中，KnownClass::Template被映射到KnownModule::Templatelib（即string.templatelib），由此完成了"t-string 字面量 →string.templatelib.Template实例"的类型链路，与关联文档中的# revealed: Template完全对应。

边界约束：t-string 不能用作类型表达式

ty 对 t-string 的推断并非处处放行。在类型表达式（type expression）推断路径 type_expression.rs 中，ExprTString分支会先执行infer_tstring_expression（当不在字符串注解上下文中时），随后立即上报诊断：

"T-strings are not allowed in {}s"

也就是说，t-string 与 f-string、函数调用、比较表达式、切片等一样，被明确禁止出现在注解（annotation）等类型表达式上下文中，相应位置推断为Type::unknown()。这是类型检查器对"哪些语法可以出现在类型位置"的硬性约束，值得在使用t"..."时注意。

mdtest 的验证机制：文档即测试

关联文档所在的crates/ty_python_semantic/resources/mdtest/目录是 ty 的 mdtest 测试语料库。mdtest 是一种将 Markdown 文档中的代码片段作为测试用例运行的体系（实现位于 crates/mdtest），ty 侧通过 mdtest.py 驱动执行。

其工作方式可概括为：

1. 解析 Markdown 文件中的 TOML frontmatter（如[environment]配置），确定 Python 版本等环境参数；
2. 对代码块中的reveal_type(...)调用执行类型检查；
3. 将实际推断结果与注释中# revealed: ...声明的期望类型比对，不一致即测试失败。

因此 t_strings.md 不只是一篇文档，更是一个可运行的回归测试：它保证了任何未来对字符串推断逻辑的改动，都不能破坏"t-string 推断为Template"这一契约。

小结

围绕 ty 的 t-string 支持，我们可以梳理出如下事实链：

对于希望扩展类型检查器、实现 t-string 相关 lint 规则或编写类似测试用例的开发者，t_strings.md 是一份精炼但完整的入门样板：一条环境声明、一个空字符串用例，就锁定了 t-string 类型推断的核心契约。

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff