Visual Studio Code为何不显示自定义PyPI包函数的文档字符串？

你的问题大概率出在自定义包的配置或结构上，而非VS Code的基础设置（毕竟其他PyPI包能正常识别）。结合你的尝试，给出以下具体解决步骤：

1. 修正包的导入方式与结构 #

• 不要使用from .utils import *这种通配符导入，Pylance无法解析通配符导入的具体成员，会导致类型提示失效。改为显式导入需要暴露的函数，并定义__all__列表明确对外接口：

  # jeffutils/__init__.py
  from .utils import calculate_sum, format_date, validate_email  # 替换为你的实际函数名
  __all__ = ["calculate_sum", "format_date", "validate_email"]
  

• 确保包的目录结构符合标准PyPI规范，示例结构：

  jeffutils/
    __init__.py
    utils.py  # 存放你的实用函数
  pyproject.toml  # 包配置文件（推荐）
  

2. 规范文档字符串格式 #

Pylance对文档字符串的格式有要求，确保你的函数文档字符串符合主流规范（Google、NumPy或reStructuredText均可），示例：

# jeffutils/utils.py
def calculate_sum(a: int, b: int) -> int:
    """计算两个整数的和

    Args:
        a: 第一个整数
        b: 第二个整数

    Returns:
        两个整数的和
    """
    return a + b

3. 确保包的安装与元数据正确 #

• 使用pyproject.toml管理包的元数据（替代旧的setup.py），示例配置：

  [project]
  name = "jeffutils"
  version = "0.1.0"
  authors = [{name = "Jeff Hansen", email = "your@email.com"}]
  description = "实用工具函数集合"
  requires-python = ">=3.8"
  packages = ["jeffutils"]
  

• 安装包时，优先使用开发模式（pip install -e .）确保VS Code能实时识别包的更新；如果是正式发布的包，确认VS Code当前选中的Python解释器已经安装了正确版本的包（通过左下角解释器选择器验证）。

4. 调整VS Code Pylance的辅助设置 #

如果上述包配置都没问题，再调整VS Code设置：

• 将包的源码路径或安装路径添加到python.analysis.extraPaths：

  "python.analysis.extraPaths": ["/path/to/your/jeffutils/source"]
  

• 重启Pylance语言服务：打开命令面板（Ctrl+Shift+P），执行Python: Restart Language Server
• 清除缓存：执行Python: Clear Cache and Reload Window

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