Lifeguard：用于 Python 惰性导入兼容性的静态分析器

Lobsters Hottest 2026/10/09 21:44 工具

python static-analysis lazy-imports meta open-source developer-tools

摘要

Meta/Facebook 开源了 Lifeguard，这是一个快速的静态分析器（目前处于 beta 阶段），能够检测与 PEP 810 Lazy Imports 不兼容的 Python 代码模式，帮助大型代码库安全地采用延迟模块加载，以降低启动时间和内存开销。

查看原文

查看缓存全文

缓存时间: 2026/10/09 22:29

Facebook/lifeguard

来源：https://github.com/Facebook/lifeguard

Lifeguard — 惰性导入助手

PyPI - 版本 (https://pypi.org/pypi/lifeguard-lazy-imports/)

License: MIT (https://opensource.org/licenses/MIT)

一个快速的静态分析工具，帮助 Python 采用惰性导入。

什么是惰性导入？

在 Python 中，每条 import 语句在模块加载时都会立即执行，无论该导入是否真正被使用，都会产生此开销。

PEP 810 为 Python 引入了显式惰性导入，将模块的实际加载延迟到首次访问被导入的名称时。惰性导入可以显著降低内存使用、启动时间和导入开销，尤其对于依赖树较深的大型代码库而言。

然而，部分 Python 模式依赖于导入的立即执行。例如：

模块级副作用 —— 在导入时注册处理器或修改全局状态的模块，如果延迟导入，其行为将会不同。
注册表模式 —— 导入时将自身注册到全局字典中的模块，在惰性导入下会静默注册失败。
sys.modules 操作 —— 读取或写入 sys.modules 的代码假设之前的导入已经执行完毕。
元类与 __init_subclass__ —— 类创建时的副作用可能依赖于导入的即时解析。

将现有代码库改造为使用惰性导入可能是一项艰巨的任务，尤其是在大规模项目中。Lifeguard 能够识别这些不兼容的模式，让你可以放心地采用惰性导入。

Lifeguard 的工作原理？

Lifeguard 并行分析给定项目的 Python 源文件。它遍历每个模块的 AST 来检测副作用，并将与惰性导入不兼容的副作用映射为错误。

分析器对其分析采取保守策略：任何无法通过程序判定为可安全惰性导入的模块，默认标记为不安全。这意味着 Lifeguard 会倾向于将可能兼容的模块标记为不兼容，牺牲潜在的性能优化以确保生产环境的安全性。

如需深入了解分析流程和架构，请参阅 docs/architecture.md。

项目阶段：Beta

Lifeguard 正在积极开发中。我们计划在 Python 3.15 正式发布时使其达到通用可用状态。

路线图事项

我们已经测试并支持 Python 3.12 和 3.14，其他版本也可能可以工作。要分析 PEP 810 中的显式 lazy import 语法，请传入 --python-version 3.15。
我们正在积极开发独立的 linter 输出模式，帮助用户识别代码库中哪些具体行与惰性导入不兼容。
我们计划为高级用户提供便捷的 Lifeguard 输出导入机制，以驱动惰性导入的启用（参见使用输出）。

从 PyPI 安装

Lifeguard 已发布在 PyPI 上，提供适用于 Linux、macOS 和 Windows（x86-64 和 ARM64）的预构建 wheel。需要 Python 3.12 或更高版本，无需 Rust 工具链：

pip install lifeguard-lazy-imports
lifeguard run-tree /path/to/project output.json --verbose-output verbose.txt

python -m lifeguard_lazy_imports 与 lifeguard 命令等效。

下面的 cargo run -- 示例是从源码构建并运行工具；使用已安装的包时，将 cargo run -- 替换为 lifeguard 即可。

PyPI 版本为手动发布，可能滞后于主分支。运行 lifeguard --help 查看已安装版本支持的功能。

从源码构建的前置条件

Rust（nightly） —— 通过 rustup 安装。Cargo 使用 rust-toolchain.toml 中固定的 nightly 版本，无需更改全局默认工具链。
Git —— 使用子模块克隆：git clone --recurse-submodules https://github.com/facebook/Lifeguard.git

如果之前未使用 --recurse-submodules 克隆，请执行 git submodule update --init --recursive。

快速开始

尝试 Lifeguard 最快的方式是使用 run-tree 子命令，它会在指定目录下发现 .py 文件并跟踪可解析的顶层导入。输入根目录下的文件和目录名必须是 ASCII Python 标识符；其他路径将被跳过。

cargo run -- run-tree

例如，使用自带的示例项目：

cargo run -- run-tree testdata/sample_project output.json

包含输出解读的完整教程请参阅 GETTING_STARTED.md。

运行 Lifeguard

对于需要更多控制的大型项目，你可以生成一个源数据库 —— 一个 JSON 文件，告诉 Lifeguard 项目中完整的 Python 文件集及其模块路径（详见输入格式）。按照以下步骤操作：

生成源数据库。我们提供了一个子命令来帮你初始化该文件，但你可能需要手动调整。（随着项目成熟，我们希望让这个过程更加顺畅。）

cargo run -- gen-source-db

如果你的项目有库依赖，可以通过在 pyproject.toml 中添加 lifeguard 配置节，让 Lifeguard 指向你的 site-packages：

[lifeguard]
site_packages = "/path/to/site-packages"

你可以通过 python -m site 查看你的 site-packages 路径。gen-source-db 和 run-tree 都会从 /pyproject.toml 中读取此配置节。相对的 site_packages 路径基于 INPUT_DIR 解析。你也可以用 --site-packages /path/to/site-packages 覆盖该设置。

注意： 发现机制跟踪顶层导入语句，可能无法发现所有依赖，例如嵌套在函数中或输入树之外的条件块中的导入。如果 Lifeguard 报告缺失模块，你可能需要手动向生成的源数据库中添加条目。

对于显式惰性导入语法，在源发现和分析两个阶段都需传入 --python-version 3.15。

选择以下两种模式之一运行 Lifeguard：
- 默认模式：打印代码库的高层分析结果（兼容文件百分比、主要错误等），并将 JSON 输出写入 OUTPUT_PATH。
```
cargo run --
```
- 详细模式：额外输出一份人类可读的报告，展示每个模块中导致不兼容的具体行。
```
cargo run -- --verbose-output
```

详细输出示例：

## example.module.foo

### Errors
ImportedModuleAssignment (1)
  Line 17 - sys

UnsafeFunctionCall (1)
  Line 38 - example.demo.unsafe_method

输入格式

在某些模式下，Lifeguard 需要一个源数据库 —— 一个将 Python 模块路径映射到其磁盘位置的 JSON 文件。格式如下：

{
  "build_map": {
    "foo/bar.py": "/local/usr/disk/foo/bar.py",
    "example/__init__.py": "/local/usr/disk/third-party/example/__init__.py"
  }
}

你可以使用 cargo run -- gen-source-db 自动生成（参见运行 Lifeguard），也可以手动创建。

输出格式

Lifeguard 输出一个包含两个字段的 JSON 文件：

{
  "LAZY_ELIGIBLE": {
    "module1": [],
    "module2": ["module3", "module4"],
    "module5": []
  },
  "LOAD_IMPORTS_EAGERLY": ["module5", "module99", "module100"]
}

使用 --verbose-output 时，JSON 还会包含 IMPLICIT_IMPORTS（模块到依赖的映射）和 IMPORT_CYCLES（每个循环中的模块列表）。使用 --sorted-output 可以获得确定性的字段排序。

`LAZY_ELIGIBLE`

一个字典，将可安全使用惰性导入的模块映射到必须提前急切导入的依赖列表。例如：

"module1": [] —— module1 完全安全，无需限制即可使用惰性导入。
"module2": ["module3", "module4"] —— module2 可安全使用惰性导入，但前提是 module3 和 module4 已经被导入。

重要： 不作为键出现在此字典中的模块已被分析判定为不适合使用惰性导入。

`LOAD_IMPORTS_EAGERLY`

一个模块集合，这些模块内所有导入都必须急切加载。惰性导入在这些模块中被临时禁用。

注意区别： 其他模块仍然可以惰性导入 LOAD_IMPORTS_EAGERLY 集合中的模块，但当该模块实际加载时，其自身的 import 语句必须立即执行而非延迟。此集合仅用于特定的边缘情况：

自定义终结器（__del__）—— 不可预测的执行时机意味着导入必须在终结时可用。
exec() 调用 —— 动态代码执行会消除静态分析的保障。
sys.modules 访问 —— 读取或写入 sys.modules 可能依赖于之前的导入已执行完毕。

更多详情请参阅 docs/load_imports_eagerly.md。

使用输出

作为独立 linter

Lifeguard 可以作为独立 linter 使用，帮助你识别代码库中哪些具体行与惰性导入不兼容。使用 --verbose-output 运行分析器可获得人类可读的报告，展示每个模块的错误及行号（参见运行 Lifeguard）。

这样，你可以像使用 linter 一样使用 Lifeguard：在 CI 或本地运行，审查被标记的行并进行修复。以此方式，Lifeguard 充当安全启用惰性导入的指南。

驱动惰性导入加载器

JSON 输出旨在驱动惰性导入加载器的过滤函数。在 Python 3.15 中，sys.set_lazy_imports_filter() 安装一个回调，控制哪些导入被延迟、哪些被急切加载。Lifeguard 的输出提供了构建此过滤器所需的数据 —— 使用 LAZY_ELIGIBLE 识别安全模块及其约束，使用 LOAD_IMPORTS_EAGERLY 识别需要提前解析所有导入的模块。

我们计划在 Python 3.15 发布之前提供便捷导入 Lifeguard 输出的工具。此功能正在开发中。

实现

Lifeguard 使用 Rust 实现。我们借助 ruff 进行 AST 遍历，并复用了 pyrefly 中的多个 crate。我们还扩展了 .pyi 存根文件，用于标注第三方库中的已知副作用 —— 例如，标记依赖项中某个特定的模块级函数调用具有可观察的行为。这些存根存储在 resources/ 文件夹中。详见 resources/stubs/stubs.md，了解副作用标注与标准类型存根的配合方式。

许可证

向 Lifeguard 贡献代码即表示你同意其贡献将根据本源码树根目录下的 LICENSE 文件进行许可。