ty 诊断系统深度指南富上下文报错、规则体系与编辑器实战【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/tyty 是 Astral 团队用 Rust 编写的高性能 Python 类型检查器与语言服务器其诊断Diagnostics系统是项目的核心亮点之一它不仅报告哪里错了还会附带源码片段、类型注解、出错原因说明甚至直接给出修复建议。本文基于仓库中的 诊断文档 展开结合 规则文档、抑制文档、编辑器设置参考 与 CLI 参考 等一手资料带你系统掌握 ty 诊断的构成要素、四大典型场景、背后的规则体系以及如何在终端与编辑器里高效利用这些诊断信息。读完本文你将能够看懂 ty 每条诊断的完整信息结构理解 TypedDict、参数类型、版本兼容性等高频错误的报错逻辑通过规则级别、抑制注释和编辑器设置精确控制诊断的展示范围并在 CI 中输出适合 GitLab、GitHub Actions 或 JUnit 的格式化诊断。诊断系统总览不只是报错ty 提供的诊断diagnostics包含以下要素源码片段snippets定位到出错行的上下文而非孤立的一行错误摘要注解annotations在出错位置标注实际类型、期望类型等关键信息解释explanations说明为什么这是一个错误修复建议suggestions部分诊断还会给出如何修复的提示在支持语言服务器的编辑器中可以直接以 quick fix 形式一键应用。README 的项目亮点中也明确将带有丰富上下文信息的全面诊断列为 ty 的核心能力。这套诊断同时服务于两个场景终端命令行ty check输出以及编辑器内的内联展示由语言服务器推送/拉取。诊断的信息结构一次完整的 ty 诊断通常由以下部分构成下文截图均有体现错误定位文件路径、行号、出错的具体源码行上下文片段出错行周围的相关代码类型注解标注实际类型 vs 期望类型例如Expected str, found bytes规则标识diagnostic ID每个诊断关联一个规则名如invalid-argument-type、unresolved-import用于配置严重级别或按规则抑制引用跳转诊断可指向相关定义位置如 TypedDict 中键的声明、函数定义中的参数在编辑器中可直接跳转。在语言服务器场景下ty 还支持一个非标准的 LSP 扩展——fullDiagnosticOutput客户端能力当客户端声明该能力为true时ty 会在诊断的data字段中附带人类可读的多行渲染文本rendered以及原始规则标识diagnostic_id。其中rendered使用 ANSI SGR 转义序列着色客户端展示前需自行解析或剥离。这为编辑器实现展开查看完整诊断提供了标准途径。详见 语言服务器文档。案例一TypedDict 键的无效赋值ty 检测到对TypedDict键的无效赋值时诊断不仅包含出错行周围的上下文还会引用TypedDict定义中该键的声明。以下图为例Person[age]的声明类型为int | None而赋值处传入的是str来自input的返回值ty 在源码片段中同时标出value of typestr与key has declared typeint | None并附上Item declaration注解指向定义处的age字段。深色主题版本见 diagnostics1.dark.png。这种报错处 定义处的双重定位让开发者无需跳转即可判断问题根源是赋值方类型错误还是键声明类型不当。案例二TypedDict 键拼写错误与编辑器快速修复当TypedDict的键拼写错误时ty 会直接给出正确的拼写建议。例如访问Person[naem]时ty 会提示Did you mean name?。如果你使用的是支持语言服务器的编辑器还可以直接以quick fix形式应用这个建议一键把naem修正为name无需手动修改。深色主题版本见 diagnostics2.dark.png。这是 ty 诊断附修复建议能力的典型体现——建议由规则自身携带语言服务器通过textDocument/codeAction暴露给编辑器。正如 语言服务器文档 所述ty 支持的 code action 中Quick fixes为部分诊断提供一键修复是核心能力之一。案例三无效参数Invalid Argument诊断当传入参数类型与函数签名不匹配时ty 会同时指出类型不匹配并包含函数定义中对应参数的信息。例如文件以文本模式open(..., w)打开后调用f.write(data)而data的类型是bytesty 会标注Expected str, found bytes并给出Method defined here注解指向io.TextIOWrapper.write的声明位置参数s: str。深色主题版本见 diagnostics3.dark.png。这种诊断把调用方实参与被调方形参声明绑定在一起呈现即使面对标准库或第三方库的签名约束也能一眼看清期望。案例四向后兼容性诊断版本条件导入ty 的一大特色是当某个模块无法解析时它会尝试解释为什么不可用而不是简单报一个unresolved-import。例如tomllib只在 Python 3.11 中加入标准库而项目pyproject.toml中声明了requires-python 3.10ty 就会提示当前项目目标版本是 Python 3.10而tomllib自 Python 3.11 才可用。深色主题版本见 diagnostics4.dark.png。这一能力依赖 ty 对目标 Python 版本的解析逻辑。根据 配置参考 与 README 的说明ty 通过environment.python-version配置项或命令行--python-version指定分析所用 Python 版本未显式指定时会依次尝试读取pyproject.toml的project.requires-python取范围下限、推断激活环境中的 Python 版本最后回退到默认值。typeshed 中的标准库桩stub也大量使用sys.version_info条件分支反映不同 Python 版本的标准库差异这正是 ty 能精准判断该导入在该版本下不存在的底层依据。官方明确支持的目标版本为 Python 3.10 及以上。诊断背后的规则体系ty 的每条类型检查诊断都关联一个规则rule。规则可以按项目需求调整严重级别详见 规则文档error违规按错误报告存在错误时 ty 以退出码 1 结束warn违规按警告报告默认配置下仅有警告时以退出码 0 结束可通过--error-on-warning收紧为退出码 1ignore关闭该规则。命令行调整规则级别ty check \ --warn unused-ignore-comment \ # 将 unused-ignore-comment 设为警告 --ignore redundant-cast \ # 关闭 redundant-cast --error possibly-missing-attribute \ # 将 possibly-missing-attribute 设为错误 --error possibly-missing-import # 将 possibly-missing-import 设为错误选项可重复后续选项覆盖先前选项也可以使用--error all、--warn all、--ignore all批量设置全部规则。配置文件调整规则级别pyproject.toml与独立ty.toml两种写法等价与上面的命令行完全等效[tool.ty.rules] unused-ignore-comment warn redundant-cast ignore possibly-missing-attribute error possibly-missing-import error[rules] unused-ignore-comment warn redundant-cast ignore possibly-missing-attribute error possibly-missing-import error在 配置参考 中rules支持ignore | warn | error三种严重级别键既可以是规则名也可以是all。诊断携带的规则标识如invalid-argument-type就是你在配置和抑制注释中使用的名字终端里还可以用ty explain rule 规则名查看某条规则的详细说明见 CLI 参考。抑制诊断的多种方式并非所有违规都需要立即修复——遗留代码、已知的第三方限制等场景下精确抑制比全局关闭规则更可取。ty 提供多种抑制手段详见 抑制文档ty 专属抑制注释在行尾添加# ty: ignore[rule]a 10 test # ty: ignore[unsupported-operator]多行违规可在首行或末行抑制同一行可枚举多个规则逗号分隔也可在文件顶部用独立注释行整文件抑制sum_three_numbers(one, 5) # ty: ignore[missing-argument, invalid-argument-type]# ty: ignore[invalid-argument-type] sum_three_numbers(3, 2, 1)标准type: ignorety 支持 PEP 484 定义的type: ignore注释不带规则代码时抑制该行全部类型错误type: ignore[ty:rule]则与ty: ignore[rule]等价只抑制匹配规则。不带ty:前缀的代码会被忽略因此可以在同一条注释中组合多个类型检查器的抑制sum_three_numbers(one, 5, 2) # type: ignore[arg-type, ty:invalid-argument-type]未使用抑制注释的检测开启unused-ignore-comment规则后ty 会报告未被实际使用的ty: ignore与type: ignore注释帮助你在修复问题后及时清理冗余抑制。注意unused-ignore-comment违规只能用# ty: ignore[unused-ignore-comment]抑制不能用无规则代码的# ty: ignore或# type: ignore。在编辑器中管理诊断范围ty 作为语言服务器运行时会持续产出诊断并随输入实时更新。编辑器默认展示当前打开文件的诊断如需覆盖整个工作区可通过diagnosticMode设置调整详见 编辑器设置参考off完全关闭诊断适合只用 ty 做补全、跳转等语言服务场景openFilesOnly仅报告当前打开文件的诊断默认值workspace报告整个工作区的诊断。{ ty.diagnosticMode: workspace }ty 同时支持 LSP 的pull与push两种诊断模型大多数现代编辑器使用按需拉取的 pull 模型以获得更好性能。此外showSyntaxErrors默认true控制是否展示语法错误诊断——当与其他语言服务器共存时可关闭它以免语法错误重复提示。终端输出格式与 CI 集成在终端中ty check默认以full格式冗长输出诊断带上下文与提示也可通过--output-format切换为适合不同场景的格式详见 CLI 参考full默认详尽的诊断输出包含上下文和提示concise每行一条的精简输出gitlabGitLab Code Quality 报告所需的 JSON 格式githubGitHub Actions 工作流错误注解格式junitJUnit 风格 XML 报告。CI 中配合退出码即可实现门禁--error-on-warning让警告也导致非零退出码--exit-zero/--exit-zero-on-warning则用于放宽门禁。开发时还可以用ty check --watch进入增量监听模式借助 ty 细粒度的增量分析fine-grained incrementality实现毫秒级重检相关说明见 语言服务器文档。小结ty 的诊断系统把错误报告升级为问题解释源码片段提供上下文注解标出类型差异解释说明原因建议与 quick fix 给出出路。在此基础上规则级别、抑制注释与输出格式的组合让开发者既能在 IDE 中获得沉浸式反馈也能在 CI 中落地精确、可读的类型检查门禁。想进一步深入了解可以继续阅读仓库内的 规则参考、配置参考、抑制文档 与 语言服务器文档。【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ty 诊断系统深度指南：富上下文报错、规则体系与编辑器实战
ty 诊断系统深度指南富上下文报错、规则体系与编辑器实战【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/tyty 是 Astral 团队用 Rust 编写的高性能 Python 类型检查器与语言服务器其诊断Diagnostics系统是项目的核心亮点之一它不仅报告哪里错了还会附带源码片段、类型注解、出错原因说明甚至直接给出修复建议。本文基于仓库中的 诊断文档 展开结合 规则文档、抑制文档、编辑器设置参考 与 CLI 参考 等一手资料带你系统掌握 ty 诊断的构成要素、四大典型场景、背后的规则体系以及如何在终端与编辑器里高效利用这些诊断信息。读完本文你将能够看懂 ty 每条诊断的完整信息结构理解 TypedDict、参数类型、版本兼容性等高频错误的报错逻辑通过规则级别、抑制注释和编辑器设置精确控制诊断的展示范围并在 CI 中输出适合 GitLab、GitHub Actions 或 JUnit 的格式化诊断。诊断系统总览不只是报错ty 提供的诊断diagnostics包含以下要素源码片段snippets定位到出错行的上下文而非孤立的一行错误摘要注解annotations在出错位置标注实际类型、期望类型等关键信息解释explanations说明为什么这是一个错误修复建议suggestions部分诊断还会给出如何修复的提示在支持语言服务器的编辑器中可以直接以 quick fix 形式一键应用。README 的项目亮点中也明确将带有丰富上下文信息的全面诊断列为 ty 的核心能力。这套诊断同时服务于两个场景终端命令行ty check输出以及编辑器内的内联展示由语言服务器推送/拉取。诊断的信息结构一次完整的 ty 诊断通常由以下部分构成下文截图均有体现错误定位文件路径、行号、出错的具体源码行上下文片段出错行周围的相关代码类型注解标注实际类型 vs 期望类型例如Expected str, found bytes规则标识diagnostic ID每个诊断关联一个规则名如invalid-argument-type、unresolved-import用于配置严重级别或按规则抑制引用跳转诊断可指向相关定义位置如 TypedDict 中键的声明、函数定义中的参数在编辑器中可直接跳转。在语言服务器场景下ty 还支持一个非标准的 LSP 扩展——fullDiagnosticOutput客户端能力当客户端声明该能力为true时ty 会在诊断的data字段中附带人类可读的多行渲染文本rendered以及原始规则标识diagnostic_id。其中rendered使用 ANSI SGR 转义序列着色客户端展示前需自行解析或剥离。这为编辑器实现展开查看完整诊断提供了标准途径。详见 语言服务器文档。案例一TypedDict 键的无效赋值ty 检测到对TypedDict键的无效赋值时诊断不仅包含出错行周围的上下文还会引用TypedDict定义中该键的声明。以下图为例Person[age]的声明类型为int | None而赋值处传入的是str来自input的返回值ty 在源码片段中同时标出value of typestr与key has declared typeint | None并附上Item declaration注解指向定义处的age字段。深色主题版本见 diagnostics1.dark.png。这种报错处 定义处的双重定位让开发者无需跳转即可判断问题根源是赋值方类型错误还是键声明类型不当。案例二TypedDict 键拼写错误与编辑器快速修复当TypedDict的键拼写错误时ty 会直接给出正确的拼写建议。例如访问Person[naem]时ty 会提示Did you mean name?。如果你使用的是支持语言服务器的编辑器还可以直接以quick fix形式应用这个建议一键把naem修正为name无需手动修改。深色主题版本见 diagnostics2.dark.png。这是 ty 诊断附修复建议能力的典型体现——建议由规则自身携带语言服务器通过textDocument/codeAction暴露给编辑器。正如 语言服务器文档 所述ty 支持的 code action 中Quick fixes为部分诊断提供一键修复是核心能力之一。案例三无效参数Invalid Argument诊断当传入参数类型与函数签名不匹配时ty 会同时指出类型不匹配并包含函数定义中对应参数的信息。例如文件以文本模式open(..., w)打开后调用f.write(data)而data的类型是bytesty 会标注Expected str, found bytes并给出Method defined here注解指向io.TextIOWrapper.write的声明位置参数s: str。深色主题版本见 diagnostics3.dark.png。这种诊断把调用方实参与被调方形参声明绑定在一起呈现即使面对标准库或第三方库的签名约束也能一眼看清期望。案例四向后兼容性诊断版本条件导入ty 的一大特色是当某个模块无法解析时它会尝试解释为什么不可用而不是简单报一个unresolved-import。例如tomllib只在 Python 3.11 中加入标准库而项目pyproject.toml中声明了requires-python 3.10ty 就会提示当前项目目标版本是 Python 3.10而tomllib自 Python 3.11 才可用。深色主题版本见 diagnostics4.dark.png。这一能力依赖 ty 对目标 Python 版本的解析逻辑。根据 配置参考 与 README 的说明ty 通过environment.python-version配置项或命令行--python-version指定分析所用 Python 版本未显式指定时会依次尝试读取pyproject.toml的project.requires-python取范围下限、推断激活环境中的 Python 版本最后回退到默认值。typeshed 中的标准库桩stub也大量使用sys.version_info条件分支反映不同 Python 版本的标准库差异这正是 ty 能精准判断该导入在该版本下不存在的底层依据。官方明确支持的目标版本为 Python 3.10 及以上。诊断背后的规则体系ty 的每条类型检查诊断都关联一个规则rule。规则可以按项目需求调整严重级别详见 规则文档error违规按错误报告存在错误时 ty 以退出码 1 结束warn违规按警告报告默认配置下仅有警告时以退出码 0 结束可通过--error-on-warning收紧为退出码 1ignore关闭该规则。命令行调整规则级别ty check \ --warn unused-ignore-comment \ # 将 unused-ignore-comment 设为警告 --ignore redundant-cast \ # 关闭 redundant-cast --error possibly-missing-attribute \ # 将 possibly-missing-attribute 设为错误 --error possibly-missing-import # 将 possibly-missing-import 设为错误选项可重复后续选项覆盖先前选项也可以使用--error all、--warn all、--ignore all批量设置全部规则。配置文件调整规则级别pyproject.toml与独立ty.toml两种写法等价与上面的命令行完全等效[tool.ty.rules] unused-ignore-comment warn redundant-cast ignore possibly-missing-attribute error possibly-missing-import error[rules] unused-ignore-comment warn redundant-cast ignore possibly-missing-attribute error possibly-missing-import error在 配置参考 中rules支持ignore | warn | error三种严重级别键既可以是规则名也可以是all。诊断携带的规则标识如invalid-argument-type就是你在配置和抑制注释中使用的名字终端里还可以用ty explain rule 规则名查看某条规则的详细说明见 CLI 参考。抑制诊断的多种方式并非所有违规都需要立即修复——遗留代码、已知的第三方限制等场景下精确抑制比全局关闭规则更可取。ty 提供多种抑制手段详见 抑制文档ty 专属抑制注释在行尾添加# ty: ignore[rule]a 10 test # ty: ignore[unsupported-operator]多行违规可在首行或末行抑制同一行可枚举多个规则逗号分隔也可在文件顶部用独立注释行整文件抑制sum_three_numbers(one, 5) # ty: ignore[missing-argument, invalid-argument-type]# ty: ignore[invalid-argument-type] sum_three_numbers(3, 2, 1)标准type: ignorety 支持 PEP 484 定义的type: ignore注释不带规则代码时抑制该行全部类型错误type: ignore[ty:rule]则与ty: ignore[rule]等价只抑制匹配规则。不带ty:前缀的代码会被忽略因此可以在同一条注释中组合多个类型检查器的抑制sum_three_numbers(one, 5, 2) # type: ignore[arg-type, ty:invalid-argument-type]未使用抑制注释的检测开启unused-ignore-comment规则后ty 会报告未被实际使用的ty: ignore与type: ignore注释帮助你在修复问题后及时清理冗余抑制。注意unused-ignore-comment违规只能用# ty: ignore[unused-ignore-comment]抑制不能用无规则代码的# ty: ignore或# type: ignore。在编辑器中管理诊断范围ty 作为语言服务器运行时会持续产出诊断并随输入实时更新。编辑器默认展示当前打开文件的诊断如需覆盖整个工作区可通过diagnosticMode设置调整详见 编辑器设置参考off完全关闭诊断适合只用 ty 做补全、跳转等语言服务场景openFilesOnly仅报告当前打开文件的诊断默认值workspace报告整个工作区的诊断。{ ty.diagnosticMode: workspace }ty 同时支持 LSP 的pull与push两种诊断模型大多数现代编辑器使用按需拉取的 pull 模型以获得更好性能。此外showSyntaxErrors默认true控制是否展示语法错误诊断——当与其他语言服务器共存时可关闭它以免语法错误重复提示。终端输出格式与 CI 集成在终端中ty check默认以full格式冗长输出诊断带上下文与提示也可通过--output-format切换为适合不同场景的格式详见 CLI 参考full默认详尽的诊断输出包含上下文和提示concise每行一条的精简输出gitlabGitLab Code Quality 报告所需的 JSON 格式githubGitHub Actions 工作流错误注解格式junitJUnit 风格 XML 报告。CI 中配合退出码即可实现门禁--error-on-warning让警告也导致非零退出码--exit-zero/--exit-zero-on-warning则用于放宽门禁。开发时还可以用ty check --watch进入增量监听模式借助 ty 细粒度的增量分析fine-grained incrementality实现毫秒级重检相关说明见 语言服务器文档。小结ty 的诊断系统把错误报告升级为问题解释源码片段提供上下文注解标出类型差异解释说明原因建议与 quick fix 给出出路。在此基础上规则级别、抑制注释与输出格式的组合让开发者既能在 IDE 中获得沉浸式反馈也能在 CI 中落地精确、可读的类型检查门禁。想进一步深入了解可以继续阅读仓库内的 规则参考、配置参考、抑制文档 与 语言服务器文档。【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考