如何为PyCharm创建car内置模块的Stub包以实现无修改自动补全？

要让import car无需修改代码就能获得自动补全，核心是给IDE提供类型存根（Stub）文件，让PyCharm识别内置模块的接口，同时不影响运行时真实模块的加载。以下是两种可行方案：

方案一：本地类型存根文件（无需打包安装） #

1. 在项目根目录新建一个typings文件夹（名字可自定义）。
2. 在该文件夹内创建car.pyi文件，写入接口的类型定义（无需实现逻辑，用...占位）：

   def getState(id: int, optional_id: int | None = None) -> None: ...
   def log(value: str) -> None: ...
   

3. 配置PyCharm识别该目录：
   • 打开File > Settings > Project: [你的项目名] > Project Structure
   • 选中typings文件夹，点击Mark Directory as > Sources Root
4. 重启PyCharm或重新加载项目，此时import car即可自动补全getState和log方法。

方案二：安装存根包（适合多项目复用） #

如果需要在多个项目中复用这个补全配置，可以创建一个模块名为car的存根包，而非car-stub，确保和真实模块名一致：

1. 创建一个新的文件夹，命名为car_package（打包用的父目录，名字随意），内部新建car子文件夹。
2. 在car文件夹内创建__init__.pyi文件，内容同方案一的car.pyi。
3. 在car_package目录下创建setup.py文件，用于打包：

   from setuptools import setup
   
   setup(
       name="car-stubs",
       version="0.1.0",
       packages=["car"],
       package_data={"car": ["*.pyi"]},
       provides=["car"],  # 声明提供car模块的类型提示
       python_requires=">=3.8",
   )
   

4. 激活项目的虚拟环境，在car_package目录下执行：

   pip install -e .
   

5. 回到PyCharm，import car即可正常获得自动补全，运行时Python会优先加载内置的真实car模块，不会出现冲突。

关键说明 #

• 不能用car-stub作为包名，因为这会导致导入路径和现有代码的import car不匹配，必须让存根的模块名与真实内置模块完全一致（即car）。
• 类型存根文件仅用于IDE的类型提示，运行时Python会忽略这些文件，优先加载真实的内置模块，因此不会影响代码功能。

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