VSCode中Python自定义继承异常的文档字符串不显示问题

问题背景 #

自定义异常类代码如下：

class CustomNamedException(Exception):
    """Example docstring here."""

    def __init__(self, name) -> None:
        self._name = name

    def __str__(self):
        return("Error message.")

在VSCode中使用该类时，信息提示框显示的是基类Exception的文档字符串“Common base class for all exceptions”，而非自定义类的“Example docstring here.”，想确认是否遗漏了相关设置。

更新补充 #

若为__init__方法添加文档字符串，该方法的文档字符串会正常显示。

疑问 #

这是否是预期行为？继承BaseException类时，类级文档字符串会被忽略，仅__init__的文档字符串生效？

解答 #

这不是Python本身的行为，而是VSCode中Python语言服务（比如Pylance）的显示逻辑导致的。

Python本身并不会忽略自定义异常类的类级文档字符串，你可以在终端执行help(CustomNamedException)，能正常看到类的文档说明。

VSCode里的提示逻辑会优先展示__init__方法的文档，尤其是在你实例化异常（比如写CustomNamedException("test")）的时候，编辑器会聚焦到构造方法的提示内容。但如果只是把光标放在类名上查看类本身，正常应该能显示类级文档字符串。如果还是没显示，可以检查以下几点：

• 确保VSCode的Python插件（Pylance）是最新版本，旧版本可能存在这类显示bug
• 检查VSCode设置中的python.analysis.documentationMode，将其设置为full，确保完整展示文档内容
• 重启VSCode或者重新加载窗口，有时候缓存会导致显示异常

另外需要明确：继承BaseException或Exception类时，Python本身完全支持类级文档字符串，不存在“被忽略”的情况，只是编辑器的提示逻辑会在特定场景下优先展示构造方法的内容。

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