如何为编译入pyd文件的多嵌套子模块编写pyi文件及最佳实践

是否需要为每个子模块单独编写pyi文件？ #

不需要单独创建多个pyi文件，只需要编写顶层模块的单个pyi文件即可覆盖所有嵌套子模块的类型声明。因为编译后的单个pyd文件在Python中会被识别为包含子模块的顶层模块，对应的pyi文件只需一个就能完整描述整个模块的层级结构。

如何在pyi中体现子模块的嵌套层级？ #

可以通过在顶层pyi文件中定义类来模拟子模块结构，并将这些类作为顶层模块的属性暴露出来，让类型检查器识别嵌套关系。以下是具体示例：

假设编译后的pyd文件名为my_lib.pyd，内部包含core和utils两个子模块，每个子模块有对应的函数和类，对应的pyi写法如下：

# my_lib.pyi
from typing import Any, Module

# 定义core子模块的类型结构
class core(Module):
    def compute(self, x: int) -> int: ...
    class DataModel:
        def __init__(self, value: str) -> None: ...
        @property
        def value(self) -> str: ...

# 定义utils子模块的类型结构
class utils(Module):
    def format_output(self, data: dict[str, Any]) -> str: ...
    def validate_input(self, x: int) -> bool: ...

# 将子模块暴露为顶层模块的属性
core: core
utils: utils

如果存在多层嵌套（比如my_lib.core.tools），可以在父模块类中继续嵌套定义子模块类：

# my_lib.pyi
from typing import Module

class core(Module):
    # 定义core下的tools子模块
    class tools(Module):
        def helper_func(self) -> None: ...
    
    tools: tools
    def compute(self, x: int) -> int: ...

最佳实践 #

• 严格对齐pyd结构：子模块名称、类/函数的参数类型、返回值类型必须与pybind11绑定的代码完全一致，避免类型提示失效或报错。
• 仅保留类型声明：pyi文件只需描述类型信息，函数体统一用...替代具体实现，不要写任何业务逻辑。
• 简化复杂嵌套：对于多层嵌套的子模块，遵循“父模块类包含子模块类”的写法，保持结构的可读性。
• 利用类型别名：如果子模块中有大量重复的复杂类型，可在pyi顶部定义类型别名，减少重复代码。
• 验证类型有效性：写完pyi后，用mypy等类型检查工具测试导入和使用子模块的代码，确保类型提示正常工作。

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