Ruff ty 类型检查器环境变量完全指南配置、日志、并行度与 Python 环境发现【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff导读本文围绕 Ruff 仓库中 Python 类型检查器tycrates/ty定义与读取的全部环境变量展开系统讲解TY_CONFIG_FILE、TY_LOG、TY_LOG_PROFILE、TY_MAX_PARALLELISM、TY_OUTPUT_FORMAT五个 ty 自有变量以及VIRTUAL_ENV、CONDA_PREFIX、PYTHONPATH、XDG_CONFIG_HOME等外部定义变量的实际用途并对照crates/ty/src、crates/ruff_db/src、crates/ty_site_packages/src等处的源码实现说明每个变量的读取时机、优先级与底层机制。读完本文你将能够通过环境变量精确控制 ty 的配置文件加载、日志过滤、火焰图性能分析、并行任务上限与诊断输出格式并理解 ty 如何借助外部环境变量发现 Python 虚拟环境、Conda 环境与搜索路径。ty 是什么这些环境变量服务的对象在深入变量清单之前需要明确这些环境变量所属的项目上下文。ty 是 Ruff 仓库中正在开发的Python 静态类型检查器位于 crates/ty其 CLI 以ty check等子命令为核心与 Ruff 的 lint/format 能力并列但职责不同。ty 复用了仓库内大量基础 crate例如文件系统抽象 crates/ruff_db、Python 语义分析 crates/ty_python_semantic、环境与 site-packages 发现 crates/ty_site_packages、项目元数据与 uv 集成 crates/ty_project 等。ty 对环境变量的整体声明集中在一个统一常量表中crates/ty_static/src/env_vars.rs通过pub struct EnvVars集中声明了 ty 及其所有 crate 使用到的环境变量名再由 crates/ty_static/src/lib.rs 向外导出。本文中所有变量名均可在该文件中找到权威定义后续源码分析均以此为起点。ty 自定义的环境变量五件套ty 定义并遵守以下五个环境变量它们与对应的命令行参数互为镜像构成 CLI 之外的第二套配置通道。TY_CONFIG_FILE指定配置文件路径用途指向一个ty.toml配置文件。行为语义当该变量被设置时ty 将直接使用该文件作为配置来源不再自动发现配置文件。这与命令行参数--config-file完全等价。源码佐证在 crates/ty/src/args.rs#L151-L155 中config_file参数通过 clap 的env属性与TY_CONFIG_FILE绑定/// The path to a ty.toml file to use for configuration. /// /// While ty configuration can be included in a pyproject.toml file, it is not allowed in this context. #[arg(long, env EnvVars::TY_CONFIG_FILE, value_name PATH)] pub(crate) config_file: OptionSystemPathBuf,值得注意的参数注释透露了两个细节该参数要求ty.toml文件虽然 ty 的配置可以写在pyproject.toml中但在--config-file/TY_CONFIG_FILE这一上下文中不允许指向pyproject.toml参数类型为OptionSystemPathBuf即路径需要是系统合法路径UTF-8且不设置时表现为None走自动发现逻辑。典型用法export TY_CONFIG_FILE/path/to/your/ty.toml ty check .设置后ty 将跳过对当前目录及父目录的配置文件自动发现完全以该文件为准。TY_LOG精细控制日志级别用途为 ty 的--verbose输出指定日志级别。行为语义若设置了该变量ty 使用其值作为日志过滤器该值接受任何与tracing_subscribercrate 兼容的过滤器语法即EnvFilter指令语法。官方文档给出的两个关键示例TY_LOGtydebug等价于命令行-vvTY_LOGtrace开启全部 trace 级别日志。源码佐证日志初始化集中在 crates/ty/src/logging.rs#L109-L145 的setup_tracing函数中其核心逻辑是// The TY_LOG environment variable overrides the default log level. let filter if let Ok(log_env_variable) std::env::var(EnvVars::TY_LOG) { EnvFilter::builder() .parse(log_env_variable) .context(Failed to parse directives specified in TY_LOG environment variable.)? } else { // 未设置 TY_LOG 时按 -v / -vv / -vvv 的详细程度构建默认过滤器 match level { VerbosityLevel::Default { EnvFilter::default() .add_directive(tywarn.parse().unwrap()) .add_directive(ruffwarn.parse().unwrap()) } level { /* 依据 level_filter 为 ty 与 ruff 两个 target 添加指令 */ } } };这段代码揭示了几层事实TY_LOG的优先级高于命令行-v/-vv/-vvv只要设置了TY_LOG无论命令行 verbose 级别如何都以TY_LOG的过滤器为准默认未设置情况下ty 与 ruff 两个 tracing target 默认只显示warn级别其他 crate 的事件被屏蔽过滤器语法丰富由于底层是EnvFilter支持按 crate 名、span 字段甚至模块路径进行过滤。进阶用法来自 crates/ty/docs/tracing.md# 显示所有 crate 的 debug 消息 TY_LOGdebug # 除 ty 消息外还显示 salsa 查询执行消息 TY_LOGrufftrace,tytrace,salsainfo # 只显示 ty_python_semantic::types 模块的 trace TY_LOGty_python_semantic::types # 只显示某个特定文件的 span 内消息需配合 -vvv 查看 span TY_LOGty[{file/path/to/x.py}]tracetracing.md同时提醒使用 span 字段过滤时tracing 无法在进入 span 时就预知子 span 是否属于目标文件因此仍会输出全部 span另外 salsa 会记录完整的记忆化值源码文本与解析后的 AST容易产生极长输出。注意release 构建中trace!事件会被移除因此 trace 级日志在 release 版本中不可见。TY_LOG_PROFILE开启火焰图性能分析用途当值被设置为1或true时ty 开启 flamegraph火焰图性能分析。行为语义开启后ty 会在当前目录生成一个tracing.folded文件该文件可进一步用于生成火焰图进行性能分析。源码佐证在 crates/ty/src/logging.rs#L192-L206 的setup_profile中fn setup_profileS() - (...) { if let Ok(1 | true) std::env::var(EnvVars::TY_LOG_PROFILE).as_deref() { let (layer, guard) tracing_flame::FlameLayer::with_file(tracing.folded) .expect(Flame layer to be created); (Some(layer), Some(guard)) } else { (None, None) } }实现细节底层使用tracing_flame::FlameLayer输出文件固定命名为当前目录下的tracing.folded返回的FlushGuard被保存在TracingGuard中见setup_tracing返回类型确保程序退出时将分析数据冲刷到磁盘。该 ProfilingLayer 在 crates/ty/src/logging.rs#L147-L151 被注册进tracing_subscriber的 registry与过滤器、格式化层并存。典型用法与火焰图生成crates/ty/docs/tracing.md#L115-L136TY_LOG_PROFILE1 ty -- --current-directory../test -vvv将文本化的折叠堆栈转换为可视化火焰图需安装infernocargo install --locked inferno # flamegraph火焰图 cat tracing.folded | inferno-flamegraph tracing-flamegraph.svg # flamechart火焰图/时间线 cat tracing.folded | inferno-flamegraph --flamechart tracing-flamechart.svgTY_MAX_PARALLELISM限制并行任务上限用途指定 ty 允许并行运行的任务数量上限例如同时检查多少个文件。行为语义文档明确强调——这不是线程数上限。ty 在必要时仍会派生额外线程例如监听文件系统变化、运行专用 UI 线程等。换言之它限制的是并行处理任务这一层面而非进程内线程总数。源码佐证该变量的核心读取逻辑位于 crates/ruff_db/src/lib.rs#L82-L107 的max_parallelism()函数pub fn max_parallelism() - NonZeroUsize { std::env::var(EnvVars::TY_MAX_PARALLELISM) .or_else(|_| std::env::var(EnvVars::RAYON_NUM_THREADS)) .ok() .and_then(|s| s.parse().ok()) .unwrap_or_else(|| { std::thread::available_parallelism().unwrap_or_else(|_| NonZeroUsize::new(1).unwrap()) }) }解析出的语义顺序为若设置了TY_MAX_PARALLELISM且可解析为整数使用它否则回退到RAYON_NUM_THREADS即TY_MAX_PARALLELISM优先于RAYON_NUM_THREADS否则使用std::thread::available_parallelism()系统可用并行度若系统查询也失败最终回退为1。该值的消费方主要有两处全局 Rayon 线程池crates/ty/src/lib.rs#L920-L927 的setup_rayon()用它作为 Rayon 全局线程池的线程数并叠加 16 MB 的STACK_SIZE见 crates/ruff_db/src/lib.rs#L109-L114文件系统遍历crates/ruff_db/src/system/os.rs#L306 在构建目录遍历线程池时使用max_parallelism().min(NonZeroUsize::new(12).unwrap())即目录扫描线程数不会超过 12。典型用法# 限制文件检查并行度更易读日志性能分析时也更可控 TY_MAX_PARALLELISM2 ty check .TY_OUTPUT_FORMAT控制诊断输出格式用途指定诊断消息的打印格式。行为语义设置后ty 使用该格式进行输出而非默认格式接受的取值与--output-format命令行参数完全一致。源码佐证在 crates/ty/src/args.rs#L157-L159 中output_format参数同样通过 clap 的env属性绑定/// The format to use for printing diagnostic messages. #[arg(long, env EnvVars::TY_OUTPUT_FORMAT)] output_format: OptionOutputFormat,从 crates/ty/docs/cli.md 的--output-format帮助文本可知full是默认值其语义为详细打印诊断信息包含上下文与有用的提示其余可选值与--output-format支持的值保持一致。典型用法export TY_OUTPUT_FORMATfull ty check .外部定义的环境变量Python 环境发现除上述 ty 自有变量外ty 还读取以下由 Python 生态venv / conda / pip外部定义的环境变量用于定位解释器、虚拟环境与搜索路径。CONDA_DEFAULT_ENV、CONDA_PREFIX、_CONDA_ROOTConda 环境三件套三个变量分别承担不同职责CONDA_DEFAULT_ENV用于确定当前激活的 Conda 环境名称CONDA_PREFIX用于检测当前激活的 Conda 环境路径_CONDA_ROOT用于确定Conda 的根安装路径。关键优先级规则当VIRTUAL_ENV与CONDA_PREFIX同时存在时VIRTUAL_ENV会被优先采用即 venv 优先于 conda。源码佐证这三个变量被 ty 用于区分 Conda 环境的类型进而决定标准库与 site-packages 的解析方式。核心逻辑在 crates/ty_site_packages/src/lib.rs#L960-L1009 的CondaEnvironmentKind中fn from_prefix_path(system: dyn System, path: SystemPath) - Self { // 如果 _CONDA_ROOT 已设置且与 CONDA_PREFIX 路径一致说明是 base 环境 if let Ok(conda_root) system.env_var(EnvVars::CONDA_ROOT) path.as_str() conda_root { return Self::Base; } // 其次使用 CONDA_DEFAULT_ENV 做启发式判断 let Ok(current_env) system.env_var(EnvVars::CONDA_DEFAULT_ENV) else { return Self::Child; }; // 环境名为 base 或 root 视为 base 环境向后兼容的特殊处理 if current_env base || current_env root { return Self::Base; } // 其余情况按路径名与活跃环境名是否一致判断 let Some(name) path.file_name() else { return Self::Child; }; if name current_env { Self::Child } else { Self::Base } }该逻辑将 Conda 环境区分为两种类型Basebase 环境按系统 Python 环境对待CondaEnvironmentKind::BaseChild非 base 的 Conda 环境按虚拟环境对待CondaEnvironmentKind::Child。判定路径依次为_CONDA_ROOT与CONDA_PREFIX是否一致 →CONDA_DEFAULT_ENV是否为base/root→ 路径目录名是否与活跃环境名一致。代码注释还指出一个易混淆点CONDA_DEFAULT_ENV名字具有误导性——它实际保存的是当前活跃环境名如base而非固定的默认环境名。crates/ty_project/src/uv/environments.rs的测试代码第 1303-1310 行附近在构造测试环境时也会显式设置VIRTUAL_ENV、CONDA_PREFIX、CONDA_DEFAULT_ENV、PYTHONPATH等变量印证了 ty 正是通过这些变量感知测试/运行环境。PYTHONPATH扩展搜索路径用途向 ty 的搜索路径中追加额外目录。行为语义格式与 shell 的PATH相同——由操作系统对应的路径分隔符Unix 上为冒号:Windows 上为分号;分隔的一个或多个目录路径名。源码佐证在 crates/ty_project/src/uv/environments.rs#L1305-L1309 的测试初始化中PYTHONPATH与其他环境发现变量被一同写入测试系统表明 ty 在环境解析阶段会读取它来补充模块搜索目录。RAYON_NUM_THREADS标准 Rayon 线程上限用途指定 ty 在执行并行工作时使用的线程数上限。行为语义与TY_MAX_PARALLELISM等价是 Rayon 的标准环境变量。由前文 crates/ruff_db/src/lib.rs#L99-L107 可知当TY_MAX_PARALLELISM与RAYON_NUM_THREADS同时设置时TY_MAX_PARALLELISM优先若两者都未设置则回退到系统可用并行度。VIRTUAL_ENV虚拟环境检测用途用于检测当前是否激活了 Python 虚拟环境。行为语义当VIRTUAL_ENV与CONDA_PREFIX同时存在时VIRTUAL_ENV优先venv 优先于 conda。该变量由 venv/uv 等工具在激活虚拟环境时写入ty 读取它以定位活跃虚拟环境的根目录从而解析其下的标准库与第三方包。XDG_CONFIG_HOME用户级配置目录用途Unix 系统上指向用户级配置目录。行为语义ty 在确定用户配置目录时会遵循 XDG 规范。在 crates/ruff_db/src/system/os.rs#L141-L155 的user_config_directory()实现中ty 使用etceteracrate 的choose_base_strategy()选择平台基目录策略进而得到配置目录。相关文档注释crates/ruff_db/src/system/os.rs#L492-L497进一步说明测试中需要隔离用户配置目录时推荐通过设置APPDATAWindows或XDG_CONFIG_HOMEUnix 及其他平台环境变量来覆盖这也佐证了XDG_CONFIG_HOME是该目录解析链路中的关键输入。作为参考同文件的缓存目录逻辑crates/ruff_db/src/system/os.rs#L157 附近在 Linux/macOS 上使用$XDG_CACHE_HOME/ty或~/.cache/ty可见 ty 对 XDG 系列变量遵循同一套平台规范。变量读取的统一入口EnvVars 常量表与 System 抽象理解 ty 环境变量机制的关键在于两层设计第一层集中声明的常量表。crates/ty_static/src/env_vars.rs 用pub struct EnvVars静态常量形式声明了所有变量名TY_LOG、TY_LOG_PROFILE、TY_MAX_PARALLELISM、TY_CONFIG_FILE、TY_OUTPUT_FORMAT、VIRTUAL_ENV、PYTHONPATH、CONDA_DEFAULT_ENV、CONDA_PREFIX、CONDA_ROOT等并由attribute_env_vars_metadata宏crates/ruff_macros/src/env_vars.rs生成元数据。任何 crate 引用变量名时都使用EnvVars::XXX避免字符串散落各处、杜绝拼写不一致。第二层System 抽象的env_var方法。在运行时代码中ty 通过ruff_db的Systemtrait 读取环境变量例如 crates/ruff_db/src/system/os.rs#L222-L224fn env_var(self, name: str) - std::result::ResultString, std::env::VarError { std::env::var(name) }OsSystem的实现直接委托给std::env::var而测试系统TestSystem则可以覆盖环境变量实现测试隔离测试中不在进程内改环境变量避免多线程不安全。这也是 crates/ty_project/src/uv/environments.rs 测试中通过db.test_system().set_env_var(...)注入UV、VIRTUAL_ENV等变量的原因。值得注意的是CLI 层如TY_CONFIG_FILE、TY_OUTPUT_FORMAT走的是 clap 的env绑定crates/ty/src/args.rs而运行时的并行度、环境发现、日志与性能分析则走System::env_var或std::env::varcrates/ty/src/logging.rs、crates/ty/src/lib.rs、crates/ruff_db/src/lib.rs、crates/ty_site_packages/src/lib.rs。两条读取路径互为补充共同构成 ty 的环境变量体系。优先级与协作规则速查综合文档与源码ty 环境变量的优先级规则可总结如下变量与命令行的关系优先级/回退规则TY_CONFIG_FILE等价--config-file设置后禁用自动发现配置TY_OUTPUT_FORMAT等价--output-format设置后取代默认格式默认fullTY_LOG覆盖-v/-vv/-vvv设置后覆盖verbose 级别未设置时默认tywarn,ruffwarnTY_LOG_PROFILE无直接对应参数值恰为1/true时生成tracing.foldedTY_MAX_PARALLELISM无直接对应参数优先于RAYON_NUM_THREADS→ 回退available_parallelism→ 回退1RAYON_NUM_THREADS无直接对应参数仅当TY_MAX_PARALLELISM未设置时生效VIRTUAL_ENV—优先于CONDA_PREFIXCONDA_PREFIX—与_CONDA_ROOT一致 → base 环境CONDA_DEFAULT_ENV—base/root→ base 环境否则按路径名判断_CONDA_ROOT—用于判定 Conda base 环境根路径PYTHONPATH—按系统路径分隔符追加搜索目录XDG_CONFIG_HOME—Unix 用户级配置目录解析的关键输入组合实战一次可观测的受限并行运行将以上变量组合使用可以实现一次兼具配置固定、日志细分、性能采样与并行受控的 ty 检查运行export TY_CONFIG_FILE./ty.toml # 固定配置文件 export TY_OUTPUT_FORMATfull # 详细诊断输出 export TY_LOGtydebug,ty_site_packagesdebug # 聚焦 ty 与 site-packages 发现 export TY_MAX_PARALLELISM2 # 限制文件检查并行度便于阅读日志 export TY_LOG_PROFILE1 # 同时采集火焰图数据 ty check . # 运行结束后生成火焰图 cat tracing.folded | inferno-flamegraph tracing-flamegraph.svg若环境中同时存在 venv 与 condaty 会遵循VIRTUAL_ENV优先的规则选择活跃环境若希望调试并行与线程行为则用TY_MAX_PARALLELISM1或RAYON_NUM_THREADS1关闭并行、获得完全线性的日志顺序crates/ty/docs/tracing.md#L23-L34。延伸阅读crates/ty/docs/environment.md本文对应的原始环境变量文档crates/ty/docs/cli.mdty CLI 全量参数说明含--config-file、--output-format、-v/-vv/-vvvcrates/ty/docs/tracing.mdTY_LOG过滤器高级语法、salsa 查询跟踪、性能分析与火焰图生成完整教程crates/ty/src/logging.rs日志过滤、格式化与tracing.folded输出的实现crates/ty/src/args.rsCLI 参数与TY_CONFIG_FILE、TY_OUTPUT_FORMAT的 clapenv绑定crates/ruff_db/src/lib.rsmax_parallelism()并行度计算与STACK_SIZE定义crates/ty_site_packages/src/lib.rsConda 环境类型判定逻辑crates/ty_static/src/env_vars.rs全部环境变量的权威声明。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考