PyO3编写的Rust扩展类TestClass在Python IDE中无法被识别的原因

根本原因 #

1. PyO3编译出来的是二进制扩展文件（比如Linux/macOS下的.so、Windows下的.pyd），不是可读的纯Python源码。PyCharm的代码提示依赖静态扫描Python文本文件，无法直接解析二进制文件中的类、方法结构，因此会报找不到引用的错误。
2. 你误以为PyO3会生成Python文件，其实是混淆了「运行时可用的二进制模块」和「IDE需要的类型存根文件」——PyO3默认不会自动生成.pyi格式的类型存根，而这类文件才是给IDE做静态分析用的核心文件。

解决办法 #

用Maturin自动生成存根 #

如果你用Maturin（PyO3官方推荐的构建工具），直接运行以下命令：

maturin develop --generate-stub

它会自动为你的扩展模块生成对应的.pyi存根文件，生成后PyCharm就能立刻识别TestClass，还能提供正常的代码提示。

手动编写存根文件（适合小型模块） #

不想用工具的话，可自行在模块目录下创建__init__.pyi文件，手动补全类的结构，示例如下：

class TestClass:
    def __init__(self, init_param: int) -> None:
        pass

    def your_custom_method(self, arg: str) -> bool:
        pass

IDE会读取这个存根文件来识别类和方法的定义。

临时忽略错误（不推荐） #

如果只是想隐藏红标提示，在PyCharm里按Alt+Enter，选择「Add ignore comment」或者将模块目录标记为「Library Root」，但这种方法无法解决代码提示问题，仅作为临时方案。

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