ty CLI 完全指南从ty check到语言服务器与 CI 集成的命令参考【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/tydocs/reference/cli.md是 ty一个用 Rust 编写的极速 Python 类型检查器与语言服务器的命令行参考文档。本文以该文档为骨架结合仓库中 type-checking.md、exit-codes.md、environment.md、configuration.md 以及 Python 启动器源码系统讲解 ty 全部子命令、ty check的每个选项、退出码语义、环境变量与输出格式。读完本文你将能够熟练地在终端、CI 流水线与编辑器环境中配置和使用 ty。说明docs/reference/cli.md是一份自动生成的文档其文件头注明由cargo dev generate-all生成需修改crates/ty/src/args.rs中的 doc 注释来更新内容。因此本文所有命令与参数均与当前仓库的 CLI 实现一一对应可作为权威的离线参考。ty 命令行总览一个命令五个子命令ty 采用子命令式 CLI顶层用法为ty COMMAND子命令说明ty check检查项目中的类型错误核心命令ty server启动语言服务器供编辑器集成使用ty version显示 ty 的版本信息ty explain解释规则及 ty 的其他组成部分ty help打印帮助信息也可打印指定子命令的帮助此外还有ty generate-shell-completion SHELL用于生成 Shell 自动补全脚本详见下文。与大多数 Rust CLI 一致每个子命令都支持--help/-h查看帮助-h输出摘要--help输出完整帮助ty check --help中还会列出当前版本支持的 Python 版本等动态信息。Python 启动器ty包如何找到二进制仓库中的python/ty是一个薄封装层ty check等命令在 pip 安装场景下正是通过它被转发的。python/ty/main.py 调用find_ty_bin()定位真实的 ty 二进制随后在 Windows 上通过subprocess.run、在其他平台通过os.execvp将参数原样透传python/ty/main.py。_find_ty.py会依次在sysconfig的 scripts 目录、包根目录上层、~/.local/bin等位置查找可执行文件python/ty/_find_ty.py。这意味着无论你用pip install ty、uv tool install ty还是独立安装脚本装好二进制ty命令的调用方式完全一致。ty check核心检查命令全参数解析ty check用于检查项目中的类型错误用法为ty check [OPTIONS] [PATH]...位置参数PATHS要检查的文件或目录列表默认值为“项目根目录”。也就是说不带任何参数运行ty check会递归检查当前项目或工作目录下的所有 Python 文件type-checking.md。选项详解选项说明--add-ignore自动在所有产生规则诊断的位置添加ty: ignore注释用于批量抑制诊断--color when控制彩色输出时机auto输出到交互式终端时显示默认、always总是显示、never从不显示--config KEY VALUE/-c以 TOML 键值对形式覆盖单个配置项写法同ty.toml中的配置单个配置项的覆盖优先级始终高于所有配置文件--config-file path指定要使用的ty.toml配置文件的路径。注意虽然 ty 配置可以放在pyproject.toml中但此参数不允许指向pyproject.toml也可以用环境变量TY_CONFIG_FILE设置--error rule将指定规则视为error级别。可重复指定多次传all则应用于所有规则--error-on-warning只要存在 warning 级别及以上的诊断就返回退出码 1。不能与--exit-zero或--exit-zero-on-warning同时使用--exclude exclude从类型检查中排除文件的 glob 模式gitignore 风格支持如tests/、*.tmp、**/__pycache__/**等写法--exclude-scripts排除包含 PEP 723 内联脚本元数据的文件除非显式传入用--include-scripts关闭--exit-zero即使存在 error 级别诊断也始终返回退出码 0。不能与--error-on-warning同时使用--exit-zero-on-warning只要没有 error 级别诊断就返回退出码 0。不能与--error-on-warning同时使用--extra-search-path path额外的模块解析来源路径可多次传入。这是高级选项通常只用于未按常规方式安装到 Python 环境的第三方/第一方模块环境位置不常规时请优先用--python--fix应用修复来解决错误--force-exclude即使路径是在命令行上显式传给 ty 的也强制应用排除规则用--no-force-exclude关闭--ignore rule禁用指定规则。可重复指定多次传all则应用于所有规则--no-progress隐藏所有进度输出如 spinner、进度条--output-format format诊断消息的输出格式详见下文“输出格式”小节也可用环境变量TY_OUTPUT_FORMAT设置--project project在给定项目目录内运行命令。从该目录向上遍历发现所有pyproject.toml除非设置了venv-path选项也会发现项目的虚拟环境.venv。其他命令行参数如相对路径仍相对于当前工作目录解析--python path/--venv path项目 Python 环境或解释器的路径。ty 用它解析代码中的第三方导入。可以是Python 解释器如.venv/bin/python3、虚拟环境目录如.venv、或系统 Python 的sys.prefix目录如/usr。使用 uv 等项目管理工具或已激活 Conda/虚拟环境时通常无需指定--python-platform platform/--platform解析类型时假设的目标平台用于特化sys.platform的类型并影响平台相关函数与属性的可见性。设为all表示不做任何平台假设未指定时使用当前系统平台--python-version version/--target-version解析类型时假设的 Python 版本。影响允许的语法、标准库类型定义以及随 Python 版本条件化的一/三方模块类型定义。可取值3.7~3.15详见下文“版本推导”。未指定时 ty 按以下优先级推导①pyproject.toml的project.requires-python取范围中的最小版本② 已激活或已配置的 Python 环境的版本 ③ 回退到 ty 支持的最新稳定版见ty check --help输出--quiet/-q使用安静输出-qq为完全静默--respect-ignore-files通过.gitignore等标准忽略文件排除文件用--no-respect-ignore-files关闭--typeshed path/--custom-typeshed-dir用于标准库 typeshed stubs 的自定义目录--verbose/-v使用详细输出-vv、-vvv更详细--warn rule将指定规则视为warn级别。可重复指定多次传all则应用于所有规则--watch/-W监视文件变化并重新检查与变更文件相关的文件规则级别的三条控制命令--ignore、--warn、--error三者构成了命令行层面的“规则重定级”三件套与配置文件中的rules表见 configuration.md对应。例如# 把 possibly-unresolved-reference 从默认级别提升为 error ty check --error possibly-unresolved-reference # 忽略 division-by-zero 规则的所有诊断 ty check --ignore division-by-zero # 把两条规则都降到 warn ty check --warn possibly-unresolved-reference --warn division-by-zero # 对全部规则应用同一级别 ty check --error all常用实战组合# 只检查单个文件 ty check example.py # 检查多个路径 ty check src/ tests/ # 增量监视模式文件变更时自动重查受影响的文件 ty check --watch # 静默 指定输出格式适合脚本调用 ty check -q --output-format concise # 自定义配置与 Python 环境 ty check --config-file ty.toml --python .venv/bin/python3 # 覆盖单个配置项优先级高于所有配置文件 ty check -c src.exclude [**/generated/**]其中--watch模式依赖 fine-grained incrementality 实现增量重查——后续每次检查比反复运行ty check快得多type-checking.md。输出格式从终端友好到 CI 机器可读ty check --output-format支持五种格式也可通过环境变量TY_OUTPUT_FORMAT设置environment.md值说明full详细打印诊断带上下文和有用的提示默认concise简洁打印诊断每行一条gitlab以 GitLab Code Quality 报告期望的 JSON 格式输出github以 GitHub Actions 工作流错误注解格式输出junit以 JUnit 风格 XML 报告输出配置文件中对应项为terminal.output-format默认full见 configuration.md。在 CI 中接入不同平台时只需切换格式即可让诊断直接显示到合并请求/工作流注解上# GitHub Actions ty check --output-format github # GitLab Code Quality ty check --output-format gitlab # 任意支持 JUnit 的平台 ty check --output-format junit退出码语义如何用$?驱动流程ty 的退出码语义定义在 exit-codes.md退出码含义0未发现warning及以上级别的违规1发现了warning及以上级别的违规2无效的 CLI 选项、无效的配置或 IO 错误101内部错误默认情况下只要有任何 warning 或 error 诊断ty 就以退出码 1 结束。三个命令行参数可以改变这一行为exit-codes.md--exit-zero即使发现违规也以 0 退出--error-on-warning发现任何 warning 及以上级别违规就以 1 退出即默认行为显式化--exit-zero-on-warning仅当发现 error 及以上级别违规时才以 1 退出warning 不影响退出码。约束关系--error-on-warning不能与--exit-zero或--exit-zero-on-warning同时使用。配置层面还提供了terminal.error-on-warning默认true。设为false后若所有诊断都是 warning 级别ty 将以退出码 0 结束configuration.md。例如在 CI 中希望“warning 不阻断构建、error 必须阻断”# 等价于 ty.toml 中的 [terminal] error-on-warning false ty check --exit-zero-on-warning环境变量命令行之外的配置通道ty 定义并读取的环境变量分为“ty 专用”和“外部定义”两类environment.md。ty 定义的变量变量作用TY_CONFIG_FILE指向要使用的ty.toml配置文件。设置后 ty 使用该文件而不再自动发现配置文件等价于--config-fileTY_LOG设置--verbose输出的日志级别接受任意兼容tracing_subscribercrate 的过滤器。例如TY_LOGtydebug等价于-vvTY_LOGtrace开启全部 trace 级日志TY_LOG_PROFILE设为1或true时启用 flamegraph 性能剖析生成tracing.folded文件可用于生成火焰图TY_MAX_PARALLELISM限制 ty 并行运行的任务数上限如并行检查的文件数。注意它不是线程上限——ty 在必要时如监视文件系统变化、专用 UI 线程仍可能额外派发线程TY_OUTPUT_FORMAT诊断输出格式取值同--output-format外部定义、ty 也会读取的变量变量作用CONDA_DEFAULT_ENV确定当前激活的 Conda 环境名称CONDA_PREFIX检测激活的 Conda 环境路径若VIRTUAL_ENV与CONDA_PREFIX同时存在优先VIRTUAL_ENVPYTHONPATH向 ty 的搜索路径添加额外目录格式与 Shell 的PATH相同Unix 用冒号、Windows 用分号分隔RAYON_NUM_THREADS限制 ty 并行工作时的线程数等价于TY_MAX_PARALLELISMRayon 标准变量VIRTUAL_ENV检测已激活的虚拟环境XDG_CONFIG_HOMEUnix 系统上用户级配置目录的路径_CONDA_ROOT确定 Conda 的根安装路径值得强调的是环境发现链路ty 会优先使用VIRTUAL_ENV指向的虚拟环境其次查找项目根或工作目录下的.venv再次回退到PATH中的python3/python最后才需要你显式传入--pythontype-checking.md。因此在 uv 项目里uv run ty check通常无需任何额外参数即可正确解析第三方依赖。ty server启动语言服务器ty server启动 ty 的语言服务器用法为ty server仅支持--help/-h。它实现 LSP提供代码导航、补全、代码操作、自动导入、inlay hints、悬停帮助等能力。一般你不会在终端直接运行它——VS Code、PyCharm、Neovim 等编辑器的 ty 扩展会在后台启动该进程见 editors.md。语言服务器内部依赖细粒度的增量分析因此--watch模式与编辑器体验共享同一套增量基础设施。ty version查看版本信息ty version [OPTIONS]选项说明--output-format format版本信息的显示格式可选text默认或jsontext适合人读json适合脚本解析版本号例如在 CI 中校验 ty 版本ty version --output-format jsonty explain规则即文档ty explain COMMAND子命令ty explain rule [OPTIONS] [RULE]解释某条规则省略RULE时解释所有规则ty explain help打印帮助信息ty explain rule的选项选项说明RULE要解释的规则名省略时默认解释全部规则--output-format format输出格式text默认或jsonjson输出让工具链可以程序化消费规则元数据如自动生成规则文档或 IDE 提示而text适合在终端快速查阅某条规则的触发条件与示例# 查看某条规则的含义 ty explain rule possibly-unresolved-reference # 以 JSON 形式导出全部规则说明 ty explain rule --output-format jsonty generate-shell-completion一键启用 Shell 补全ty 内置 Shell 补全生成器用法为ty generate-shell-completion SHELL。为常用 Shell 启用补全的方式如下详细步骤见 installation.md# Bash echo eval $(ty generate-shell-completion bash) ~/.bashrc # Zsh echo eval $(ty generate-shell-completion zsh) ~/.zshrc # fish echo ty generate-shell-completion fish | source ~/.config/fish/completions/ty.fish # Elvish echo eval (ty generate-shell-completion elvish | slurp) ~/.elvish/rc.elvPowerShell / pwsh 需要写入$PROFILEif (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force } Add-Content -Path $PROFILE -Value ( ty generate-shell-completion powershell) | Out-String | Invoke-Expression配置后重启 Shell 或 source 配置文件即可生效。若不确定自己的 Shell可运行echo $SHELL确认。配置文件与命令行选项的优先级关系ty 的配置可以放在pyproject.toml的[tool.ty]表或独立的ty.toml中configuration.md涉及rules、analysis、environment、src、terminal、overrides等多个配置域。与 CLI 相关的优先级链条为--config KEY VALUE的单项覆盖始终优先于所有配置文件包括自动发现的与--config-file指定的--config-file path或TY_CONFIG_FILE显式指定配置文件且此时禁止指向pyproject.toml未显式指定时ty 自动发现项目中的pyproject.toml/ty.toml。例如把“命令行覆盖配置文件”和“规则重定级”结合使用ty check \ --config-file ty.toml \ -c rules.possibly-unresolved-reference error \ --exclude **/generated/**而--python-version、--python-platform、--typeshed等选项分别对应配置中的environment.python-version、environment.python-platform、environment.typeshed命令行参数与配置文件可以互相补充、以命令行优先。完整实战从快速检查到 CI 接入把以上命令与配置组合起来一个典型的接入流程如下第一步快速上手无需安装uvx ty checkty 默认检查工作目录或项目下所有 Python 文件index.md。第二步项目级固定配置# ty.toml [tool.ty.rules] # 若放在 pyproject.toml 则写成 [tool.ty.rules] possibly-unresolved-reference warn division-by-zero ignore [src] exclude [**/generated/**, **/migrations/**] [terminal] output-format concise注意pyproject.toml与ty.toml中表的层级不同——前者需要[tool.ty.xxx]前缀后者直接写[xxx]对比见 configuration.md。第三步开发期使用监视模式ty check --watch第四步CI 中按平台输出并控制退出码ty check --output-format github # GitHub Actions ty check --output-format gitlab # GitLab Code Quality ty check --output-format junit # JUnit 报告 ty check --exit-zero-on-warning # 仅 error 阻断第五步性能与排障TY_LOGtydebug ty check -v # 查看内部日志 TY_LOG_PROFILE1 ty check # 生成 tracing.folded 供火焰图分析 TY_MAX_PARALLELISM2 ty check # 限制并行度等价于 RAYON_NUM_THREADS至此从命令行参数、退出码、环境变量到输出格式你已经掌握了 ty 在终端、脚本、CI 与编辑器中的全部控制面。想进一步了解规则体系与抑制语法可继续阅读 rules.md 与 suppression.md想深入类型系统特性参见 type-system.md。【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ty CLI 完全指南：从 `ty check` 到语言服务器与 CI 集成的命令参考
ty CLI 完全指南从ty check到语言服务器与 CI 集成的命令参考【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/tydocs/reference/cli.md是 ty一个用 Rust 编写的极速 Python 类型检查器与语言服务器的命令行参考文档。本文以该文档为骨架结合仓库中 type-checking.md、exit-codes.md、environment.md、configuration.md 以及 Python 启动器源码系统讲解 ty 全部子命令、ty check的每个选项、退出码语义、环境变量与输出格式。读完本文你将能够熟练地在终端、CI 流水线与编辑器环境中配置和使用 ty。说明docs/reference/cli.md是一份自动生成的文档其文件头注明由cargo dev generate-all生成需修改crates/ty/src/args.rs中的 doc 注释来更新内容。因此本文所有命令与参数均与当前仓库的 CLI 实现一一对应可作为权威的离线参考。ty 命令行总览一个命令五个子命令ty 采用子命令式 CLI顶层用法为ty COMMAND子命令说明ty check检查项目中的类型错误核心命令ty server启动语言服务器供编辑器集成使用ty version显示 ty 的版本信息ty explain解释规则及 ty 的其他组成部分ty help打印帮助信息也可打印指定子命令的帮助此外还有ty generate-shell-completion SHELL用于生成 Shell 自动补全脚本详见下文。与大多数 Rust CLI 一致每个子命令都支持--help/-h查看帮助-h输出摘要--help输出完整帮助ty check --help中还会列出当前版本支持的 Python 版本等动态信息。Python 启动器ty包如何找到二进制仓库中的python/ty是一个薄封装层ty check等命令在 pip 安装场景下正是通过它被转发的。python/ty/main.py 调用find_ty_bin()定位真实的 ty 二进制随后在 Windows 上通过subprocess.run、在其他平台通过os.execvp将参数原样透传python/ty/main.py。_find_ty.py会依次在sysconfig的 scripts 目录、包根目录上层、~/.local/bin等位置查找可执行文件python/ty/_find_ty.py。这意味着无论你用pip install ty、uv tool install ty还是独立安装脚本装好二进制ty命令的调用方式完全一致。ty check核心检查命令全参数解析ty check用于检查项目中的类型错误用法为ty check [OPTIONS] [PATH]...位置参数PATHS要检查的文件或目录列表默认值为“项目根目录”。也就是说不带任何参数运行ty check会递归检查当前项目或工作目录下的所有 Python 文件type-checking.md。选项详解选项说明--add-ignore自动在所有产生规则诊断的位置添加ty: ignore注释用于批量抑制诊断--color when控制彩色输出时机auto输出到交互式终端时显示默认、always总是显示、never从不显示--config KEY VALUE/-c以 TOML 键值对形式覆盖单个配置项写法同ty.toml中的配置单个配置项的覆盖优先级始终高于所有配置文件--config-file path指定要使用的ty.toml配置文件的路径。注意虽然 ty 配置可以放在pyproject.toml中但此参数不允许指向pyproject.toml也可以用环境变量TY_CONFIG_FILE设置--error rule将指定规则视为error级别。可重复指定多次传all则应用于所有规则--error-on-warning只要存在 warning 级别及以上的诊断就返回退出码 1。不能与--exit-zero或--exit-zero-on-warning同时使用--exclude exclude从类型检查中排除文件的 glob 模式gitignore 风格支持如tests/、*.tmp、**/__pycache__/**等写法--exclude-scripts排除包含 PEP 723 内联脚本元数据的文件除非显式传入用--include-scripts关闭--exit-zero即使存在 error 级别诊断也始终返回退出码 0。不能与--error-on-warning同时使用--exit-zero-on-warning只要没有 error 级别诊断就返回退出码 0。不能与--error-on-warning同时使用--extra-search-path path额外的模块解析来源路径可多次传入。这是高级选项通常只用于未按常规方式安装到 Python 环境的第三方/第一方模块环境位置不常规时请优先用--python--fix应用修复来解决错误--force-exclude即使路径是在命令行上显式传给 ty 的也强制应用排除规则用--no-force-exclude关闭--ignore rule禁用指定规则。可重复指定多次传all则应用于所有规则--no-progress隐藏所有进度输出如 spinner、进度条--output-format format诊断消息的输出格式详见下文“输出格式”小节也可用环境变量TY_OUTPUT_FORMAT设置--project project在给定项目目录内运行命令。从该目录向上遍历发现所有pyproject.toml除非设置了venv-path选项也会发现项目的虚拟环境.venv。其他命令行参数如相对路径仍相对于当前工作目录解析--python path/--venv path项目 Python 环境或解释器的路径。ty 用它解析代码中的第三方导入。可以是Python 解释器如.venv/bin/python3、虚拟环境目录如.venv、或系统 Python 的sys.prefix目录如/usr。使用 uv 等项目管理工具或已激活 Conda/虚拟环境时通常无需指定--python-platform platform/--platform解析类型时假设的目标平台用于特化sys.platform的类型并影响平台相关函数与属性的可见性。设为all表示不做任何平台假设未指定时使用当前系统平台--python-version version/--target-version解析类型时假设的 Python 版本。影响允许的语法、标准库类型定义以及随 Python 版本条件化的一/三方模块类型定义。可取值3.7~3.15详见下文“版本推导”。未指定时 ty 按以下优先级推导①pyproject.toml的project.requires-python取范围中的最小版本② 已激活或已配置的 Python 环境的版本 ③ 回退到 ty 支持的最新稳定版见ty check --help输出--quiet/-q使用安静输出-qq为完全静默--respect-ignore-files通过.gitignore等标准忽略文件排除文件用--no-respect-ignore-files关闭--typeshed path/--custom-typeshed-dir用于标准库 typeshed stubs 的自定义目录--verbose/-v使用详细输出-vv、-vvv更详细--warn rule将指定规则视为warn级别。可重复指定多次传all则应用于所有规则--watch/-W监视文件变化并重新检查与变更文件相关的文件规则级别的三条控制命令--ignore、--warn、--error三者构成了命令行层面的“规则重定级”三件套与配置文件中的rules表见 configuration.md对应。例如# 把 possibly-unresolved-reference 从默认级别提升为 error ty check --error possibly-unresolved-reference # 忽略 division-by-zero 规则的所有诊断 ty check --ignore division-by-zero # 把两条规则都降到 warn ty check --warn possibly-unresolved-reference --warn division-by-zero # 对全部规则应用同一级别 ty check --error all常用实战组合# 只检查单个文件 ty check example.py # 检查多个路径 ty check src/ tests/ # 增量监视模式文件变更时自动重查受影响的文件 ty check --watch # 静默 指定输出格式适合脚本调用 ty check -q --output-format concise # 自定义配置与 Python 环境 ty check --config-file ty.toml --python .venv/bin/python3 # 覆盖单个配置项优先级高于所有配置文件 ty check -c src.exclude [**/generated/**]其中--watch模式依赖 fine-grained incrementality 实现增量重查——后续每次检查比反复运行ty check快得多type-checking.md。输出格式从终端友好到 CI 机器可读ty check --output-format支持五种格式也可通过环境变量TY_OUTPUT_FORMAT设置environment.md值说明full详细打印诊断带上下文和有用的提示默认concise简洁打印诊断每行一条gitlab以 GitLab Code Quality 报告期望的 JSON 格式输出github以 GitHub Actions 工作流错误注解格式输出junit以 JUnit 风格 XML 报告输出配置文件中对应项为terminal.output-format默认full见 configuration.md。在 CI 中接入不同平台时只需切换格式即可让诊断直接显示到合并请求/工作流注解上# GitHub Actions ty check --output-format github # GitLab Code Quality ty check --output-format gitlab # 任意支持 JUnit 的平台 ty check --output-format junit退出码语义如何用$?驱动流程ty 的退出码语义定义在 exit-codes.md退出码含义0未发现warning及以上级别的违规1发现了warning及以上级别的违规2无效的 CLI 选项、无效的配置或 IO 错误101内部错误默认情况下只要有任何 warning 或 error 诊断ty 就以退出码 1 结束。三个命令行参数可以改变这一行为exit-codes.md--exit-zero即使发现违规也以 0 退出--error-on-warning发现任何 warning 及以上级别违规就以 1 退出即默认行为显式化--exit-zero-on-warning仅当发现 error 及以上级别违规时才以 1 退出warning 不影响退出码。约束关系--error-on-warning不能与--exit-zero或--exit-zero-on-warning同时使用。配置层面还提供了terminal.error-on-warning默认true。设为false后若所有诊断都是 warning 级别ty 将以退出码 0 结束configuration.md。例如在 CI 中希望“warning 不阻断构建、error 必须阻断”# 等价于 ty.toml 中的 [terminal] error-on-warning false ty check --exit-zero-on-warning环境变量命令行之外的配置通道ty 定义并读取的环境变量分为“ty 专用”和“外部定义”两类environment.md。ty 定义的变量变量作用TY_CONFIG_FILE指向要使用的ty.toml配置文件。设置后 ty 使用该文件而不再自动发现配置文件等价于--config-fileTY_LOG设置--verbose输出的日志级别接受任意兼容tracing_subscribercrate 的过滤器。例如TY_LOGtydebug等价于-vvTY_LOGtrace开启全部 trace 级日志TY_LOG_PROFILE设为1或true时启用 flamegraph 性能剖析生成tracing.folded文件可用于生成火焰图TY_MAX_PARALLELISM限制 ty 并行运行的任务数上限如并行检查的文件数。注意它不是线程上限——ty 在必要时如监视文件系统变化、专用 UI 线程仍可能额外派发线程TY_OUTPUT_FORMAT诊断输出格式取值同--output-format外部定义、ty 也会读取的变量变量作用CONDA_DEFAULT_ENV确定当前激活的 Conda 环境名称CONDA_PREFIX检测激活的 Conda 环境路径若VIRTUAL_ENV与CONDA_PREFIX同时存在优先VIRTUAL_ENVPYTHONPATH向 ty 的搜索路径添加额外目录格式与 Shell 的PATH相同Unix 用冒号、Windows 用分号分隔RAYON_NUM_THREADS限制 ty 并行工作时的线程数等价于TY_MAX_PARALLELISMRayon 标准变量VIRTUAL_ENV检测已激活的虚拟环境XDG_CONFIG_HOMEUnix 系统上用户级配置目录的路径_CONDA_ROOT确定 Conda 的根安装路径值得强调的是环境发现链路ty 会优先使用VIRTUAL_ENV指向的虚拟环境其次查找项目根或工作目录下的.venv再次回退到PATH中的python3/python最后才需要你显式传入--pythontype-checking.md。因此在 uv 项目里uv run ty check通常无需任何额外参数即可正确解析第三方依赖。ty server启动语言服务器ty server启动 ty 的语言服务器用法为ty server仅支持--help/-h。它实现 LSP提供代码导航、补全、代码操作、自动导入、inlay hints、悬停帮助等能力。一般你不会在终端直接运行它——VS Code、PyCharm、Neovim 等编辑器的 ty 扩展会在后台启动该进程见 editors.md。语言服务器内部依赖细粒度的增量分析因此--watch模式与编辑器体验共享同一套增量基础设施。ty version查看版本信息ty version [OPTIONS]选项说明--output-format format版本信息的显示格式可选text默认或jsontext适合人读json适合脚本解析版本号例如在 CI 中校验 ty 版本ty version --output-format jsonty explain规则即文档ty explain COMMAND子命令ty explain rule [OPTIONS] [RULE]解释某条规则省略RULE时解释所有规则ty explain help打印帮助信息ty explain rule的选项选项说明RULE要解释的规则名省略时默认解释全部规则--output-format format输出格式text默认或jsonjson输出让工具链可以程序化消费规则元数据如自动生成规则文档或 IDE 提示而text适合在终端快速查阅某条规则的触发条件与示例# 查看某条规则的含义 ty explain rule possibly-unresolved-reference # 以 JSON 形式导出全部规则说明 ty explain rule --output-format jsonty generate-shell-completion一键启用 Shell 补全ty 内置 Shell 补全生成器用法为ty generate-shell-completion SHELL。为常用 Shell 启用补全的方式如下详细步骤见 installation.md# Bash echo eval $(ty generate-shell-completion bash) ~/.bashrc # Zsh echo eval $(ty generate-shell-completion zsh) ~/.zshrc # fish echo ty generate-shell-completion fish | source ~/.config/fish/completions/ty.fish # Elvish echo eval (ty generate-shell-completion elvish | slurp) ~/.elvish/rc.elvPowerShell / pwsh 需要写入$PROFILEif (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force } Add-Content -Path $PROFILE -Value ( ty generate-shell-completion powershell) | Out-String | Invoke-Expression配置后重启 Shell 或 source 配置文件即可生效。若不确定自己的 Shell可运行echo $SHELL确认。配置文件与命令行选项的优先级关系ty 的配置可以放在pyproject.toml的[tool.ty]表或独立的ty.toml中configuration.md涉及rules、analysis、environment、src、terminal、overrides等多个配置域。与 CLI 相关的优先级链条为--config KEY VALUE的单项覆盖始终优先于所有配置文件包括自动发现的与--config-file指定的--config-file path或TY_CONFIG_FILE显式指定配置文件且此时禁止指向pyproject.toml未显式指定时ty 自动发现项目中的pyproject.toml/ty.toml。例如把“命令行覆盖配置文件”和“规则重定级”结合使用ty check \ --config-file ty.toml \ -c rules.possibly-unresolved-reference error \ --exclude **/generated/**而--python-version、--python-platform、--typeshed等选项分别对应配置中的environment.python-version、environment.python-platform、environment.typeshed命令行参数与配置文件可以互相补充、以命令行优先。完整实战从快速检查到 CI 接入把以上命令与配置组合起来一个典型的接入流程如下第一步快速上手无需安装uvx ty checkty 默认检查工作目录或项目下所有 Python 文件index.md。第二步项目级固定配置# ty.toml [tool.ty.rules] # 若放在 pyproject.toml 则写成 [tool.ty.rules] possibly-unresolved-reference warn division-by-zero ignore [src] exclude [**/generated/**, **/migrations/**] [terminal] output-format concise注意pyproject.toml与ty.toml中表的层级不同——前者需要[tool.ty.xxx]前缀后者直接写[xxx]对比见 configuration.md。第三步开发期使用监视模式ty check --watch第四步CI 中按平台输出并控制退出码ty check --output-format github # GitHub Actions ty check --output-format gitlab # GitLab Code Quality ty check --output-format junit # JUnit 报告 ty check --exit-zero-on-warning # 仅 error 阻断第五步性能与排障TY_LOGtydebug ty check -v # 查看内部日志 TY_LOG_PROFILE1 ty check # 生成 tracing.folded 供火焰图分析 TY_MAX_PARALLELISM2 ty check # 限制并行度等价于 RAYON_NUM_THREADS至此从命令行参数、退出码、环境变量到输出格式你已经掌握了 ty 在终端、脚本、CI 与编辑器中的全部控制面。想进一步了解规则体系与抑制语法可继续阅读 rules.md 与 suppression.md想深入类型系统特性参见 type-system.md。【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
