ty 类型检查器 CLI 完整参考命令、选项、退出码与规则管理实战【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff导读ty是本仓库中随 Astral 工具链一同开发的超高速 Python 类型检查器源码位于 crates/ty相关 crate 还包括类型语义分析 crates/ty_python_semantic 与项目解析 crates/ty_project其核心日常操作全部集中在ty这一个命令及其子命令上。本文以官方文档 crates/ty/docs/cli.md 为骨架逐条详解ty check的全部参数、ty server、ty version、ty explain等命令的语义并结合 crates/ty/src/args.rs 与 crates/ty/src/lib.rs 的源码实现说明参数背后的真实行为如规则覆盖顺序、退出码判定逻辑、配置优先级。读完本文你将能够熟练配置出适合本地开发与 CI 的类型检查命令。文档一致性说明cli.md是自动生成文件文件头部注明由cargo dev generate-all生成所有命令与参数的真实「唯一事实源」是 crates/ty/src/args.rs 中基于 clap 的 doc 注释与参数声明。若需修改 CLI 行为正确做法是修改该文件后重新生成文档。ty 顶层命令结构ty本身不带子命令以外的直接参数整体用法为ty COMMAND顶层子命令共 5 个外加 1 个隐藏命令在 args.rs 的Command枚举中声明子命令说明对应文档章节ty check检查项目中的类型错误核心命令# ty checkty server启动语言服务器# ty serverty version显示 ty 版本# ty versionty generate-shell-completion生成 shell 补全在 args.rs 中被标记为隐藏见下文ty explain解释规则及 ty 的其他组成部分# ty explainty help打印本消息或给定子命令的帮助# ty help同时ty --help与ty -h的区别在 clap 中表现为-h输出精简版帮助--help输出完整帮助。整个 CLI 采用 clap 定义入口在 crates/ty/src/lib.rs 的run()先进行通配符展开与file参数文件展开再按子命令分发执行。ty check项目类型检查主命令ty check用于对一个 Python 项目或一组路径做全量类型检查是本工具被调用频率最高的命令ty check [OPTIONS] [PATH]...PATHS 参数与项目发现PATHS要检查的文件或目录列表。不传时默认检查「项目根目录」传多个路径时逐个检查。--project project在给定的项目目录内运行命令。ty 会从该目录向上逐级发现pyproject.toml并在未设置venv-path选项时顺带发现项目的虚拟环境.venv但其他命令行参数如相对路径仍相对当前工作目录解析。从源码 lib.rs 可以看到所有传入路径在解析阶段都会被转换为相对当前工作目录的绝对路径若命令行传入的是文件而非目录ty 会按独立脚本处理例如uv run --script场景不继承外层 workspace。环境解析Python 解释器、typeshed 与额外搜索路径选项说明--python path、--venvPython 环境或解释器路径。可指向三种对象解释器如.venv/bin/python3、虚拟环境目录如.venv、系统 Python 的sys.prefix目录如/usr。ty 用它来解析代码中的第三方导入。若你正使用 uv、conda 或已激活的虚拟环境通常无需指定本选项--typeshed path、--custom-typeshed-dir自定义的标准库 typeshed stub 目录--extra-search-path path额外的模块解析来源路径可多次传入。属高级选项通常只用于以非常规方式安装、且不在当前 Python 环境中的一三方模块若只是环境位置特殊应改用--python其中--python在 args.rs 中被声明为--python的 alias两种写法等价。Python 版本与平台选项说明--python-version version、--target-version解析类型时假设的 Python 版本。会影响允许的语法、标准库类型定义以及依赖 Python 版本的一三方模块类型定义版本取值3.7、3.8、3.9、3.10、3.11、3.12、3.13、3.14、3.15定义见 crates/ty/src/python_version.rs两端取值可在ty check --help中复核。未显式指定时的推导顺序按优先级从高到低来自 args.rs 的 doc 注释读取pyproject.toml中project.requires-python设置取该范围的最低版本检查已激活或已配置的 Python 环境尝试推断其版本回退到 ty 支持的最新稳定版Python。选项说明--python-platform platform、--platform解析类型时假设的目标平台。用于特化sys.platform的类型并影响平台专属函数与属性的可见性设为all表示不对平台做任何假设不指定时使用当前系统平台规则启用与禁用--error / --warn / --ignore规则严重级别调整是ty check最具特色的能力三参数均支持多次出现并可用all表示作用于全部规则--error rule将给定规则视为error级。可重复可用all。--warn rule将给定规则视为warn级。可重复可用all。--ignore rule禁用该规则。可重复可用all。从源码角度这三个参数由 args.rs 中自定义的RulesArg类型解析其注释明确指出后出现的规则参数会覆盖先前的严重级别arguments last override previous severities。实现上RulesArg::from_arg_matches会记录每个参数出现的索引并按索引排序从而保证覆盖语义正确。例如# 全部规则按 error 级别检查但禁用 call-non-callable ty check --error all --ignore call-non-callable # 只把 conflicting-metaclass 提级为 error、ambiguous-protocol-member 降级为 warn ty check --error conflicting-metaclass --warn ambiguous-protocol-member可用的规则名以 crates/ty/docs/rules.md 列出的为准例如abstract-and-final-method、call-non-callable、conflicting-metaclass等。修复与自动抑制--fix 与 --add-ignore选项说明--fix应用修复以解决错误--add-ignore添加ty: ignore注释以抑制全部规则诊断二者在 args.rs 中声明了conflicts_with互斥不能同时使用。底层行为可追溯至 lib.rs 的主循环--fix调用ty_python_semantic::fix_all_diagnostics并以Applicability::Safe为界限只应用安全的自动修复--add-ignore调用ty_python_semantic::suppress_all_diagnostics将诊断替换为行内ty: ignore注释在人类可读输出下--add-ignore结束时还会打印 Added N ignore comment(s) 汇总。文件选择与排除选项说明--exclude exclude排除出类型检查的文件 glob 模式。使用 gitignore 风格语法支持如tests/、*.tmp、**/__pycache__/**等写法--force-exclude/--no-force-exclude即使路径被直接传给 ty 命令行也强制执行排除规则--no-force-exclude关闭--respect-ignore-files/--no-respect-ignore-files遵循.gitignore及其他标准 ignore 文件的排除规则--no-respect-ignore-files关闭--exclude-scripts/--include-scripts排除包含 PEP 723 行内脚本元数据的文件除非显式传入--include-scripts关闭注意这些布尔开关在 args.rs 中均为「配对」定义一个公开的正向开关配一个隐藏的反向开关最终通过resolve_bool_arg合并成Some(true)/Some(false)/None三态——只有当用户显式传参时才覆盖配置文件中的对应设置避免 CLI 默认值意外压过配置文件里已显式声明的值。诊断输出格式选项说明--output-format output-format诊断信息的打印格式也可通过环境变量TY_OUTPUT_FORMAT设置五种可选值枚举定义在 args.rs取值语义full冗长打印诊断附上下文与有用提示默认concise每条诊断精简为一行打印仅含最核心信息丢弃上下文gitlab以 GitLab Code Quality 报告期望的 JSON 格式输出github以 GitHub Actions 工作流错误注解格式输出junit输出为 JUnit 风格 XML 报告例如在 GitHub Actions 中可直接使用--output-format github让错误以工作流注解形式内联显示JUnit 与 GitLab 格式则面向对应的 CI 平台报表。退出码控制选项说明--error-on-warning只要存在 warning 级诊断就使用退出码 1。不可与--exit-zero、--exit-zero-on-warning同时使用--exit-zero即使存在 error 级诊断也始终使用退出码 0。不可与--error-on-warning同时使用--exit-zero-on-warning若不存在 error 级诊断就使用退出码 0。不可与--error-on-warning同时使用底层退出码判定见 lib.rs 的exit_status_from_diagnostics程序先扫描所有诊断的最高严重级别Info Warning Error Fatal再结合error_on_warning终端设置决定成败若诊断中同时含有 IO 错误则直接返回「命令错误」。ExitStatus的完整语义如下退出码含义来源0命令成功或存在诊断但按规则不视为失败ExitStatus::Success1检查完成但存在 error 级诊断或--error-on-warning下有 warning 诊断或可执行文件发现失败ExitStatus::Failure2调用错误如当前目录不存在、CLI 参数错误ExitStatus::Error101ty 内部错误panic 或非用户原因的错误ExitStatus::InternalError130被 CtrlC 中断ExitStatus::Interrupted这使 ty 可以直接嵌入 CI 判断默认命令ty check返回 1 即表示需要修复而--exit-zero可用于「只报告不阻断」的持续集成场景。其他控制选项选项说明--color when控制彩色输出时机auto输出到交互终端时着色默认、always总是着色、never永不着色--no-progress隐藏全部进度输出spinner、进度条等--quiet、-q安静输出-qq表示完全静默--verbose、-v详细输出-vv、-vvv更详细对应 tracing 级别的提升--watch、-W监听文件变化对与变更文件相关的文件增量重查--config-file path指定用于配置的ty.toml文件路径。虽然 ty 配置也可以放入pyproject.toml但在此场景下不被接受。也可通过环境变量TY_CONFIG_FILE设置--config key value、-c以 TOMLKEY VALUE键值对形式覆盖单个配置项写法与ty.toml中一致可多次传入配置优先级值得一提CLI 通过--config传入的单项覆盖其优先级始终高于所有配置文件。这在 args.rs 的ConfigsArg中实现——每个-c键值对被解析为一份OptionsOptions::from_toml_str随后在 lib.rs 中按「先应用配置文件、再应用 CLI 覆盖」的顺序合并CLI 覆盖天然胜出。完整配置项语义参见 crates/ty/docs/configuration.md。示例——将配置与命令结合使用# 在指定 Python 3.12 环境下做全量检查 ty check --python .venv/bin/python3 --python-version 3.12 # 检查单个目录并额外排除两个目录 ty check src/ --exclude tests/ --exclude **/generated/** # 一次性查看所有错误并自动应用安全修复 ty check --fix # CI 中按 warning 即失败并输出 GitHub 注解格式 ty check --error-on-warning --output-format github # 交互式持续开发监听变化、增量重查 ty check --watchwatch 模式与主循环的内部结构从源码看--watch并非简单循环重跑ty check的检查流程由基于 Salsa 增量数据库的MainLoop驱动lib.rs。主循环通过消息通道接收「检查请求、变更事件、uv 环境同步完成」三类消息并让检查任务在 rayon 线程池中异步执行文件系统变更会通过watch::directory_watcher上报变更时自动取消进行中的查询并按 revision 丢弃过期的检查结果。CtrlC 处理被注册为取消令牌触发后返回退出码 130。进度条由IndicatifReporter呈现Checking {pos}/{len} files因此--no-progress能关闭包括脚本同步进度在内的全部进度 UI。ty server启动语言服务器ty serverty server以无参数形式启动语言服务器除--help/-h外没有公开选项。在 args.rs 中还存在一个被隐藏的调试参数--find-executable它会打印当前目录对应项目应使用的 ty 可执行文件绝对路径若已通过environment.python配置则优先使用否则按常规顺序发现 Python 环境供编辑器集成定位后端退出码 0 表示找到、1 表示发现失败、2 表示意外错误。该命令的实际服务实现位于 crates/ty/src/server.rs完整的 LSP 功能栈由 crates/ty_server 提供。ty version查看版本ty version [OPTIONS]唯一选项为--output-format默认值text可选text或jsontext输出形如ty 0.5.124 (53b0f5d92 2026-01-01)的单行信息json输出结构化 JSON。版本数据的组装在 crates/ty/src/version.rsVersionInfo由版本号字符串与可选的CommitInfo组成其中提交信息短哈希、完整哈希、提交日期、最近 tag、距最近 tag 的提交数在构建期由build.rs注入环境变量读取text格式规则为version[N] (short_commit_hash date)N仅在距最近 tag 存在未发布提交时出现。发布版本号来自工作区的dist-workspace.toml本仓库内ty包本身处于开发期版本为0.0.0且不发布见 crates/ty/Cargo.toml。ty generate-shell-completion生成 shell 补全ty generate-shell-completion SHELL该命令在官方文档中有记录但在 args.rs 中被标注为隐藏#[clap(hide true)]。它接收一个 shell 名由clap_complete_command支持并输出对应 shell 的补全脚本到 stdout例如可在 bash/zsh/fish 配置中将其输出重定向到补全目录。ty explain规则速查与解释ty explain COMMANDty explain是面向文档与排查的子命令下辖ty explain rule与帮助入口ty explain help。ty explain rule查看单条或全部规则ty explain rule [OPTIONS] [RULE]位置参数RULE要解释的规则名省略时默认解释全部规则。--output-format输出格式默认text可选text或json。实现位于 crates/ty/src/rule.rs它会查询default_lint_registry()注册表将匹配的LintId渲染为包含以下字段的说明规则名如call-non-callable默认级别ignore / warn / error状态Preview (since X)、Stable (since X)、Deprecated (since X): reason、Removed (since X): reason规则的完整文档正文。# 查看某条规则 ty explain rule call-non-callable # 以 JSON 输出全部规则的说明可用于生成工具链 ty explain rule --output-format jsontext输出以 Markdown 风格呈现每条规则从# rule-name标题开始可直接作为阅读材料json输出为序列化数组方便被脚本消费。所有规则的完整人类可读文档集中在 crates/ty/docs/rules.md。常见组合本地开发与 CI 两套命令结合上述选项可沉淀两套典型用法本地开发自动修复 增量监听# 一键安全检查并自动修复可安全修复的问题 ty check --fix # 开发期间持续监听 ty check --watchCI 门槛报警即失败 平台格式# GitHub Actionswarning 也视为失败输出注解 ty check --error-on-warning --output-format github # GitLab输出 Code Quality 报告 JSON ty check --output-format gitlab # 只读报告、不阻断即使有 error 也返回 0 ty check --exit-zero相关参考本命令参考文档原文件crates/ty/docs/cli.mdCLI 定义与参数解析唯一事实源crates/ty/src/args.rs入口与主循环、退出码 crates/ty/src/lib.rs、crates/ty/src/main.rs规则文档与配置说明crates/ty/docs/rules.md、crates/ty/docs/configuration.md环境变量如TY_CONFIG_FILE、TY_OUTPUT_FORMAT完整清单crates/ty/docs/environment.md【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
