为何Pylance无法捕获所有废弃函数/类？求静态检测工具

为什么Pylance检测废弃对象存在差异？ #

核心原因是两类废弃标记的实现方式不同，静态分析工具的检测能力依赖于是否能在代码/类型存根中读取到静态可识别的废弃标识：

• datetime.datetime.utcnow这类标准库对象的废弃，会同步在Python的**类型存根（.pyi文件）**中通过@deprecated装饰器或__deprecated__属性标记。Pylance作为基于Pyright的静态分析工具，会直接解析这些静态元信息，无需运行代码就能识别废弃状态。
• flask.json.JSONEncoder这类第三方库的废弃，仅通过运行时调用warnings.warn触发警告。静态分析工具不会执行代码逻辑，自然无法捕获这种仅在运行时才会触发的废弃提示——除非库的开发者同步在类型存根中添加了静态可检测的废弃标记。

可静态捕获此类废弃的工具及方案 #

1. Pyright/Pylance 自定义类型存根 #

如果第三方库未在类型存根中标记废弃，你可以：

• 本地创建对应库的类型存根文件（比如flask/json.pyi），在其中给JSONEncoder添加@deprecated装饰器，Pylance会读取本地存根并识别废弃。
• 提交PR给第三方库的类型存根仓库，补充静态废弃标记，帮助后续用户也能静态检测。

2. Mypy #

Mypy同样支持解析类型存根中的废弃标记，配置方式如下：

• 确保启用warn_deprecated配置项（在mypy.ini中设置warn_deprecated = True）。
• 对于未标记的第三方库，同样可以通过自定义类型存根来补充废弃信息，Mypy会识别这些存根并给出静态警告。

3. 代码层面的静态标记规范 #

如果是自己的代码，建议使用静态可识别的废弃装饰器替代仅运行时的warnings.warn：

• 使用Python 3.12+内置的typing.Deprecated装饰器。
• 使用第三方deprecated库的@deprecated装饰器，这类装饰器会添加静态可检测的元信息，让Pylance、Mypy等工具能识别。

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