如何为Python C API开发的C/C++模块生成Python函数存根？

我之前折腾Python C API模块的时候也碰到过这个头疼的问题——IDE完全没法识别模块里的函数，更别说自动补全了。其实核心原因就是这类编译后的.pyd模块没法被IDE静态解析，我们需要给它加个**类型存根文件（.pyi）**来提供函数、类的类型信息。下面给你几个实用的解决办法：

方法1：手动编写存根文件（最直接省心） #

如果你的模块对外暴露的函数、类不多，手动写存根是最快的方式。你只需要在模块的根目录下创建一个和模块同名的.pyi文件（比如你的模块叫zroya，就创建zroya.pyi），然后在里面写出所有对外接口的类型签名和文档字符串。

举个例子，假设你的模块有显示通知的函数和配置类，存根可以这么写：

"""Python C API实现的桌面通知模块"""

def show_notification(title: str, content: str, timeout: int = 5000) -> bool:
    """
    显示桌面通知
    
    Args:
        title: 通知标题文本
        content: 通知正文内容
        timeout: 通知自动关闭时长（毫秒），默认5000
    
    Returns:
        布尔值，代表通知是否成功显示
    """
    ...

class NotificationConfig:
    """通知样式配置类"""
    def __init__(self, icon_path: str | None = None) -> None:
        """初始化配置，可选指定图标路径"""
        ...
    
    def set_icon(self, icon_path: str) -> None:
        """设置通知显示的图标"""
        ...

写完之后，IDE会自动识别这个存根文件，自动补全和类型提示就正常工作了。

方法2：用工具自动生成存根（适合接口较多的模块） #

如果你的模块有大量函数和类，手动写存根太麻烦，可以用工具自动生成。这里推荐用mypy自带的stubgen工具，步骤很简单：

1. 先确保你的模块能被Python正常导入（可以把模块所在目录临时加到PYTHONPATH环境变量里）
2. 安装mypy：

   pip install mypy
   

3. 运行命令生成存根：

   stubgen zroya -o .
   

   这个命令会在当前目录生成一个zroya文件夹，里面包含自动生成的__init__.pyi存根文件。你可以把这个存根文件直接移到模块根目录下，或者调整路径让IDE能找到它。

注意：自动生成的存根可能会有类型推断不准确的情况，比如把返回值默认设为Any，你可以手动修改存根文件，补充更准确的类型提示。

方法3：修改setup.py，构建时自动生成并打包存根 #

如果你想让模块在安装时自动带上存根，不需要用户额外操作，可以修改setup.py，在构建流程中加入生成存根的步骤。这里可以通过自定义build_ext命令来实现：

from setuptools import setup, Extension
from setuptools.command.build_ext import build_ext
import subprocess
import os

class BuildExtWithStub(build_ext):
    def run(self):
        # 先执行默认的C扩展编译流程
        super().run()
        # 生成存根文件
        module_name = "zroya"
        # 确保存根输出目录存在
        stub_output_dir = os.path.join(self.build_lib, module_name)
        os.makedirs(stub_output_dir, exist_ok=True)
        # 调用stubgen生成存根
        subprocess.run(
            ["stubgen", module_name, "-o", self.build_lib],
            check=True,
            capture_output=True
        )

setup(
    name="zroya",
    ext_modules=[Extension("zroya", sources=["zroya.c"])],
    cmdclass={"build_ext": BuildExtWithStub},
    # 其他配置信息，比如版本、作者等...
)

这样当你运行python setup.py install或者pip install .时，脚本会自动生成存根并打包到安装目录里，用户安装后IDE就能直接识别到类型信息了。

补充一句：不管你用哪种方式，只要存根文件的名字和模块名一致，IDE都会自动关联存根和你的动态加载模块，完全不影响原来的__bootstrap__加载逻辑。

内容的提问来源于stack exchange，提问作者Lorin