VS Code中Python函数签名IntelliSense的信息来源及自定义方法

• 核心来源是类型存根文件（.pyi 格式文件），这也是查看requests.get时能看到完整提示的根本原因。
  Python的IDE（VS Code+Pylance、PyCharm等）、静态类型检查工具（Mypy、Pyright）不会仅从运行时的.py源码提取类型信息，会按照优先级检索对应代码的类型声明：对于没有在源码中内置类型注解的第三方库，会优先读取单独维护的类型存根。这类存根文件只包含函数、类、方法的签名、类型注解、文档说明，不写实际运行逻辑，相当于专门给开发工具读取的接口定义文件。
  你Ctrl+Click跳转到的<python-dir>/site-packages/requests/api.py是实际运行的业务源码，requests本身没有在运行时代码中写类型注解，它的类型提示来自单独发布的types-requests第三方存根包（通常会被Python环境、Pylance自动安装），或是IDE内置的常用库存根缓存。如果在悬停弹窗中选择「跳转到声明」而非「跳转到实现」，就能打开对应的.pyi存根文件，看到和悬停提示完全一致的完整类型定义。
• 其他补充提示来源：
  • 代码源码中直接按照PEP 484规范编写的原生类型注解
  • 符合Google、NumPy、reStructuredText格式规范的docstring中记录的参数、返回值说明
  • IDE内置的Python标准库全量类型存根

• 方法1：直接在源码中添加标准类型注解（维护成本最低，最推荐）
  按照PEP 484规范，直接给函数参数、返回值、类属性、变量标记类型，同时配套写清楚docstring即可，IDE无需额外配置就能直接识别生成完整悬停提示，示例：

  def fetch_data(url: str, timeout: int | float = 10, retry: int = 3) -> dict:
      """拉取指定接口的返回数据
      Args:
          url: 目标接口地址
          timeout: 请求超时时间，单位为秒
          retry: 请求失败后的最大重试次数
      Returns:
          接口返回的JSON数据解析后的字典对象
      """
      # 此处写实际业务逻辑
      pass
  

• 方法2：编写独立的.pyi类型存根文件
  如果不想在运行时代码中添加类型注解（比如需要兼容极老版本Python、给无类型的第三方私有库补提示），可以编写和.py源码同名的.pyi存根文件，和源码放在同一目录下即可被IDE识别。存根文件不需要写实际运行逻辑，函数体用...占位即可，以上面的fetch_data函数为例，对应存根写法：

  # 对应http_utils.py的存根文件http_utils.pyi
  def fetch_data(url: str, timeout: int | float = 10, retry: int = 3) -> dict:
      """拉取指定接口的返回数据
      Args:
          url: 目标接口地址
          timeout: 请求超时时间，单位为秒
          retry: 请求失败后的最大重试次数
      Returns:
          接口返回的JSON数据解析后的字典对象
      """
      ...
  

• 方法3：规范编写docstring
  如果暂时不想添加类型注解，只要按照主流格式写全docstring中的参数类型、含义、返回值说明，IDE也能解析生成基础的悬停提示，缺点是类型检查精度不如原生注解和存根文件。
• 配置注意事项：VS Code用户需要安装Pylance插件并开启基础类型检查功能，PyCharm默认内置的代码分析引擎即可自动识别上述所有格式的提示信息。

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