Python stubmaker 完整使用手册

一、stubmaker 概述与核心功能

1. 什么是 stubmaker

stubmaker 是 Python 官方配套的存根文件(.pyi)自动生成工具，底层封装 inspect、typing、ast 模块，用于为已有 Python 源码、第三方编译扩展库（C/C++/Rust 编写的 .so/.pyd）、动态模块生成类型提示存根文件（Stub File）。

区分同类工具：

• stubgen
  ：内置工具，仅支持纯 Python 源码；无法解析二进制扩展库；
• stubmaker
  ：增强版，兼容纯 Python + 编译扩展模块，自动推导函数签名、类属性、泛型、异常抛出，生成规范 .pyi 类型提示文件，适配 VSCode/PyCharm/mypy 静态类型检查。

2. 核心功能

1. 纯Python源码批量生成存根
   ：扫描文件夹/单文件，自动解析函数参数、返回值、类字段、装饰器；
2. 二进制扩展库存根生成
   ：解析 .pyd/.so 动态库、Cython 模块，弥补 stubgen 无法处理编译模块的短板；
3. 类型自动推导
   ：识别基础类型、Union、Optional、List/Dict、泛型、TypeVar；
4. 导出完整模块结构
   ：导出 __all__、常量、枚举、内置异常、类继承关系；
5. 自定义过滤规则
   ：忽略私有函数、过滤指定模块、保留/删除注释；
6. 增量生成
   ：对比旧 .pyi 文件，仅更新变更部分，不覆盖手写类型注释；
7. mypy 兼容
   ：生成符合 PEP484/PEP561 标准存根，支持静态类型校验。

二、安装方式

方式1：pip 标准安装

pip install stubmaker# 带类型检查依赖（推荐）pip install stubmaker mypy typing-extensions

方式2：源码安装（最新开发版）

git clone https://github.com/osandov/stubmaker.gitcd stubmakerpip install .

依赖要求

• Python ≥3.7；
• 可选依赖：mypy（类型校验）、cython（解析Cython模块）、setuptools（解析扩展库元数据）。

三、命令行语法、全局参数、子命令参数

基础命令语法

stubmaker [全局参数] 子命令 [子命令参数] 目标路径

支持两大核心子命令：generate（生成存根）、check（校验已有存根合法性）

1. 全局通用参数

2. generate 子命令（核心生成命令）完整参数

stubmaker generate [OPTIONS] TARGET

3. check 子命令（存根校验）参数

stubmaker check [OPTIONS] STUB_FILE

4. Python 代码内调用API语法（可编程生成）

stubmaker 提供编程式接口，可嵌入脚本批量自动化生成：

from stubmaker import StubGenerator, GeneratorConfig# 配置类config = GeneratorConfig(    recursive=True,    ignore_private=True,    output_dir="./stubs",    incremental=True)# 初始化生成器gen = StubGenerator(config=config)# 生成单文件gen.generate_file("mylib/main.py")# 生成整个包gen.generate_package("mylib/")# 校验存根gen.check_stub("stubs/main.pyi")

四、8个完整可运行实战应用案例

案例1：为单个纯Python文件生成基础存根

场景：给项目单文件 utils.py 生成 utils.pyi，输出到同目录，忽略私有方法。 命令行：

stubmaker generate --ignore-private utils.py

生成效果：自动提取所有公有函数、类，推导参数/返回值类型，生成标准 .pyi。

案例2：递归批量为整个项目包生成存根（输出至独立stubs文件夹）

场景：项目包名 myproject/，递归扫描所有子模块，存根统一输出到 ./stubs，增量更新。

stubmaker generate -r -o ./stubs --incremental --export-all myproject/

代码API版本：

from stubmaker import StubGenerator, GeneratorConfigcfg = GeneratorConfig(recursive=True, output_dir="./stubs", incremental=True, export_all=True)gen = StubGenerator(cfg)gen.generate_package("./myproject")

案例3：解析Cython编译扩展.pyd二进制模块生成存根

场景：第三方Cython库 fastcalc.pyd，stubgen无法解析，使用stubmaker运行时解析二进制导出符号。

stubmaker generate --python-exec python3 fastcalc.pyd -o ./stubs

关键：不加 --no-types-eval，必须运行加载模块读取运行时签名。

案例4：过滤指定模块、排除测试文件

场景：项目过滤 core.* 模块，排除所有 test_*.py 文件，不生成测试存根。

stubmaker generate -r --module-filter "^core\." --exclude "test_.*" src/

案例5：生成带文档注释、完整类型导入的标准化存根

场景：生成可发布给第三方的规范存根，保留docstring、自动补全typing导入。

stubmaker generate --include-docstrings --add-type-imports --force src/api.py -o dist/stubs

案例6：安全静态解析（禁止执行源码，防恶意代码）

场景：解析外部不可信第三方源码，关闭运行时类型求值，仅用AST静态分析。

stubmaker generate --no-types-eval untrusted_lib.py

限制：无法解析动态赋值类型、二进制扩展库，仅纯静态语法树解析。

案例7：自动化脚本打包时生成存根（setup.py集成）

场景：打包发布Python库时，自动构建stubs并打包进分发包。build_stubs.py 脚本：

from stubmaker import StubGenerator, GeneratorConfigimport osdef build_package_stubs():    cfg = GeneratorConfig(        recursive=True,        output_dir="./build/stubs",        ignore_private=True,        export_all=True    )    gen = StubGenerator(cfg)    gen.generate_package("./mypackage")    print("存根生成完成，路径：", os.path.abspath("./build/stubs"))if __name__ == "__main__":    build_package_stubs()

执行：python build_stubs.py，配合 setup.py 的 cmdclass 自动构建。

案例8：校验已手写存根与源码类型一致性

场景：手动修改过 .pyi，校验是否和源码函数签名、类型匹配，严格模式报错阻断发布。

stubmaker check --strict stubs/core.pyi --mypy-config mypy.ini

脚本API校验：

from stubmaker import StubGenerator, GeneratorConfiggen = StubGenerator(GeneratorConfig())result = gen.check_stub("./stubs/core.pyi", strict=True)if not result.success:    raise SystemExit("存根与源码类型不匹配")

五、常见错误、报错原因与解决方案

错误1：ModuleNotFoundError: No module named ‘stubmaker’

• 原因：未安装包、pip环境与运行Python解释器不匹配；
• 解决：

# 确认当前pip绑定当前pythonpython -m pip install stubmaker

错误2：Failed to load module xxx.pyd / segmentation fault when parsing extension

• 原因1：Python版本与编译扩展库版本不兼容（32/64位、3.8 vs 3.10）；
• 原因2：扩展库依赖系统动态库缺失（Windows缺少VC++运行库、Linux缺少glibc）；
• 解决：使用对应版本解释器 --python-exec，安装系统依赖，或切换静态解析 --no-types-eval（仅纯py文件）。

错误3：Type evaluation disabled, cannot process binary module

• 原因：使用 --no-types-eval 参数同时解析 .pyd/.so 扩展；静态AST无法读取二进制导出符号；
• 解决：移除 --no-types-eval，允许运行时加载模块解析。

错误4：Stub file not updated with --incremental but source changed

• 原因：增量模式会跳过手动修改过的 .pyi 文件，不会覆盖手写代码；
• 解决：需要全量更新时加 --force 参数强制覆盖。

错误5：SyntaxError in generated .pyi, invalid type annotation

• 原因1：源码存在动态复杂类型（动态生成类、元编程），自动推导出错；
• 原因2：旧Python版本不支持PEP604 | 联合类型；
• 解决：手动修正对应存根，或添加 --skip-constants 过滤动态常量，升级Python到3.10+。

错误6：Recursive scan not working, subfolder stubs missing

• 原因：忘记加 -r/--recursive 参数，仅处理顶层文件；
• 解决：命令行追加 -r，API配置 recursive=True。

错误7：ImportError: cannot import name ‘StubGenerator’ from ‘stubmaker’

• 原因：stubmaker版本过低，早期版本无编程API；
• 解决：升级到最新版 pip install --upgrade stubmaker。

错误8：Mypy check reports “Missing type annotation” in generated stubs

• 原因：源码无类型注解，stubmaker自动推导为 Any；
• 解决：源码补充基础类型注解，或生成时手动修改存根，添加显式类型。

六、使用注意事项

1. 安全风险

• 默认模式会导入目标模块执行代码以获取运行时类型，不要用默认参数解析未知/恶意第三方代码；处理不信任源码必须加 --no-types-eval。
• 解析二进制扩展库会加载本地动态库，存在崩溃风险，建议隔离虚拟环境操作。

2. 类型推导局限性

• 高度元编程、动态创建函数/类、工厂模式无法100%精准推导，生成后需人工校对；
• 运行时动态修改的属性、 monkey patch 不会出现在存根中；
• 复杂泛型、自定义TypeVar可能推导为Any，需手动修正。

3. 项目工程规范

• 生产项目建议将 .pyi 存根统一放入独立 stubs/ 目录，不要和源码混杂；
• 发布开源库时，将生成的 .pyi 打包分发，搭配 py.typed 文件（PEP561）告知类型检查器存在存根；
• 版本迭代时使用 --incremental 保护手写的精细类型注释。

4. 性能优化

• 开启 --cache-dir 缓存模块解析信息，多次生成大幅提速；
• 大型项目配合 --exclude 过滤测试、第三方依赖、文档目录，减少扫描耗时。

5. 编辑器兼容

• VSCode/PyCharm识别 .pyi 需确保输出目录加入 sys.path；
• 若IDE不读取生成存根，在项目根目录创建 py.typed 空文件。

6. 版本兼容提醒

• Python3.7及以下不支持 | 联合类型，生成存根会使用 Union[] 兼容写法；
• 低于0.10版本的stubmaker不支持递归批量生成，建议升级至0.12+稳定版。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。