ty 类型检查器文件发现与排除完全指南include / exclude / gitignore 模式与虚拟环境处理【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty导读ty一个用 Rust 编写的极速 Python 类型检查器默认会自动发现项目中的全部 Python 文件但在真实工程中生成代码目录、构建产物、虚拟环境、测试夹具等通常都不应纳入类型检查。本文基于 ty 的官方文档与仓库源码系统讲解通过src.include、src.exclude、respect-ignore-files等配置项精准控制文件发现范围的方法并深入解析其 gitignore 风格的 glob 语法、默认排除清单、CLI 显式传参与虚拟环境处理策略。读完本文你将能在pyproject.toml或ty.toml中准确配置 ty 的检查范围并理解这些配置在底层是如何生效的。文件发现机制概述ty 会在项目中自动发现所有 Python 文件。这一发现过程受两类因素共同约束显式配置通过src.include与src.exclude设置见 src 配置参考指定搜索与排除范围隐式规则默认排除的常见目录清单以及.gitignore、.ignore等忽略文件的尊重策略。配置文件的组织方式遵循 ty 的通用规则见 配置指南可以在项目根目录或其最近的父目录放置pyproject.toml配置写在[tool.ty]表下或ty.toml省略[tool.ty]前缀。ty.toml优先于pyproject.toml项目级配置优先于用户级配置~/.config/ty/ty.toml命令行参数又优先于所有持久化配置。用 include 与 exclude 划定检查范围ty 通过src.include和src.exclude两个配置项控制检查哪些文件。以下配置会让 ty 检查src和tests目录下的全部 Python 文件但跳过src/generated目录 pyproject.tomltoml [tool.ty.src] include [src, tests] exclude [src/generated] ty.tomltoml [src] include [src, tests] exclude [src/generated] 需要注意两点优先级规则见 src.exclude 参考 与 src.include 参考exclude优先于include即使某个路径同时命中 include 与 exclude它也会被排除exclude为空时默认值并非“无”ty 会默认排除一系列常见目录详见下文“默认排除清单”除非你用取反模式显式撤销。从源码结构看include/exclude的匹配发生在 ty 的文件收集阶段ty 的配置定义集中在 Rust 工作区的ty_projectcrate 中例如crates/ty_project/src/metadata/options.rs中的Options结构体先由 include 确定候选集合再由 exclude 做减法最终进入类型检查流水线。默认排除清单与取反!模式ty 默认排除一批几乎在所有工程中都不应检查的目录完整清单见 src.exclude 参考**/.bzr/ **/.direnv/ **/.eggs/ **/.git/ **/.git-rewrite/ **/.hg/ **/.mypy_cache/ **/.nox/ **/.pants.d/ **/.pytype/ **/.ruff_cache/ **/.svn/ **/.tox/ **/.venv/ **/__pypackages__/ **/_build/ **/buck-out/ **/dist/ **/node_modules/ **/venv/这份清单覆盖了主流版本控制目录.git、.hg、.bzr、.svn、缓存目录.mypy_cache、.ruff_cache、.pytype、.pants.d、虚拟环境.venv、venv、__pypackages__以及常见构建产物dist、_build、buck-out、node_modules、.eggs等。如果确实需要让某个默认排除的目录参与检查可以用前导!的取反 exclude将其“重新纳入”。例如把默认排除清单中的build目录恢复为可检查 pyproject.tomltoml [tool.ty.src] # Remove build from the excluded directories. exclude [!**/build/] ty.tomltoml [src] # Remove build from the excluded directories. exclude [!**/build/] 同理要恢复dist可用exclude [!dist]。注意取反模式同样遵循下文介绍的 glob 语法且带斜杠的!**/build/只匹配目录含其内容不带斜杠的!dist同时匹配文件与目录。尊重.gitignore与.ignore文件默认情况下respect-ignore-files为truety 会忽略.ignore、.gitignore、.git/info/exclude以及全局 gitignore 文件中列出的文件见 respect-ignore-files 参考。这意味着你现有的 Git 忽略规则会直接作用于 ty 的文件发现无需在 ty 配置中重复维护一份排除清单。如果希望 ty 忽略这些文件例如想完全由include/exclude控制范围可以关闭该功能 pyproject.tomltoml [tool.ty.src] respect-ignore-files false ty.tomltoml [src] respect-ignore-files false 命令行中对应的是--respect-ignore-files与--no-respect-ignore-files开关见 ty check 命令行参考。显式传参命令行路径总是被包含你可以把要检查的路径直接作为ty check的位置参数传入例如ty check src scripts/benchmark.py即使这些路径本会被exclude过滤或忽略文件排除只要以位置参数显式传入ty check它们就一定会被包含在检查范围内。也就是说显式传参拥有最高优先级是“无论如何都要检查这些文件”的可靠手段。这一行为也带来一个配套选项如果你希望即使显式传入的路径也强制受排除规则约束可以使用--force-exclude见 ty check 命令行参考。此外与文件发现相关的 CLI 选项还包括--exclude exclude以 gitignore 风格模式在命令行追加排除规则支持如tests/、*.tmp、**/__pycache__/**等写法见 --exclude 参考--exclude-scripts/--include-scripts控制是否排除含 PEP 723 内联脚本元数据的文件详见下文--config-file path与TY_CONFIG_FILE环境变量指定配置文件。include / exclude 的 glob 语法详解include与exclude均采用 gitignore 风格的 glob 模式语法规则如下两条配置的详细说明分别见 include 参考 与 exclude 参考模式含义src/只匹配名为src的目录包括其内容src匹配名为src的文件或目录目录含其内容*匹配任意可为空字符序列但不跨/**匹配零个或多个路径组件必须独立构成一个路径组件./**a、./b**/均为非法写法会直接报错连续超过两个*同样非法?匹配任意单个字符/除外[abc]匹配方括号内的任一字符可用字符区间区间按 Unicode 序排列如[0-9]匹配0到9的任一字符未闭合的方括号非法模式是锚定的所有模式都相对于项目根目录锚定。例如src只匹配project_root/src不会匹配project_root/test/src。同理exclude 模式src只排除project_root/src不会排除project_root/test/src。要匹配任意层级下名为src的目录应使用前缀匹配**/src。⚠️ 性能警告前缀 include 模式如**/src会显著拖慢 Python 文件发现的速度因为 ty 必须遍历更多目录层级来做匹配。若非必要优先使用锚定的相对路径。语法来源所有接受模式的字段都采用 PEP 639 中定义的“精简可移植 glob 语法”reduced portable glob syntax并额外支持用反斜杠\转义字符。这意味着如果你需要匹配模式中的特殊字符如字面量的*或?可以通过转义来实现。排除含内联元数据的脚本exclude-scripts除路径匹配外ty 还支持按文件内容特征排除src.exclude-scripts用于排除包含 PEP 723 内联脚本元数据inline script metadata的文件除非它们在命令行中被显式传入见 exclude-scripts 参考。默认值为false即默认检查这类脚本 pyproject.tomltoml [tool.ty.src] exclude-scripts true ty.tomltoml [src] exclude-scripts true 命令行对应--exclude-scripts与反向的--include-scripts见 ty check 命令行参考。虚拟环境venv的排除问题问题背景从 Python 3.13 开始venv模块会在虚拟环境根目录自动写入一个.gitignore文件。由于 ty 默认尊重.gitignorerespect-ignore-files true虚拟环境内的文件会被自动排除ty 不会对其中的文件发出诊断。然而在使用更早版本的 Python 时虚拟环境根目录没有.gitignorety 可能会对虚拟环境内的文件产生诊断——尤其是当虚拟环境恰好在项目根目录下如.venv而它又不在 ty 的默认排除清单生效范围之外的情况下。解决方案方案一为虚拟环境补充一个.gitignore。例如名为.venv的虚拟环境echo * .venv/.gitignore这样 ty 会尊重该文件从而忽略.venv内的全部内容。方案二把虚拟环境目录加入项目根目录的.gitignore或.ignore文件效果相同。进阶针对特定文件的 overrides 排除除了全局的include/excludety 还提供了overrides机制可以在同一份配置中针对特定文件/目录应用不同的规则配置见 overrides 参考。每个 override 自带include与exclude列表语法与上文一致用于圈定其作用范围# 在 tests 与生成文件中放宽规则 [[tool.ty.overrides]] include [tests/**, **/test_*.py] [tool.ty.overrides.rules] possibly-unresolved-reference warn# 忽略生成目录中的规则但保留关键文件 [[tool.ty.overrides]] include [generated/**] exclude [generated/important.py] [tool.ty.overrides.rules] possibly-unresolved-reference ignoreoverride 内的exclude优先于同一 override 内的include多个 override 同时命中同一文件时后定义的生效override 规则优先于全局规则。配置优先级小结综合来看ty 的文件发现与排除遵循以下优先级从高到低命令行显式路径参数传入ty check的路径必定被包含除非使用--force-exclude命令行选项--exclude、--respect-ignore-files/--no-respect-ignore-files、--exclude-scripts等覆盖配置文件项目级配置文件ty.toml优先于pyproject.toml的[tool.ty]表src.include、src.exclude、respect-ignore-files、exclude-scripts用户级配置~/.config/ty/ty.toml等与项目级配置合并数组类设置会拼接内置默认规则默认排除清单与.gitignore/.ignore尊重策略。理解这条链路你就能在大型仓库、多分支生成代码、混合虚拟环境等复杂场景下精确地让 ty 只检查你真正关心的 Python 文件既避免噪音诊断拖慢反馈速度也防止生成代码中的问题被遗漏。【免费下载链接】tyAn extremely fast Python type checker and language server, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ty2/ty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考