Python中仅用于类型检查的依赖声明规范探讨

你遇到的是仅用于类型检查、运行时无实际调用的外部依赖配置问题，直接给你明确的处理方式：

核心结论 #

这类依赖既不能放进常规dependencies，也不能完全不声明，应该归类为可选额外依赖，同时配合工具规则避免误报。

具体配置步骤 #

1. 在pyproject.toml中添加可选依赖分组
   专门创建一个用于类型检查的可选依赖组（比如命名为type-checking），把包b加进去：

   [project.optional-dependencies]
   type-checking = [
       "b>=1.0.0"  # 替换成你实际兼容的b包版本号
   ]
   

   这样需要做类型检查的用户可以通过pip install your-package[type-checking]安装必要的类型依赖，普通用户无需额外负担。

2. 避免工具误报
   像FawltyDeps这类工具会扫描代码中的导入语句（哪怕是TYPE_CHECKING条件下的），如果不声明依赖会触发误报。把b放到可选依赖组后，工具就能识别到这是一个合法的、按需安装的依赖，不会再报错。

为什么不能这么做？ #

• 不要放进常规dependencies：强制所有用户安装b完全没必要，大部分用户可能根本不会用到接受b.B类型的do_a函数，或者不需要做类型检查，这会增加不必要的安装体积和依赖链复杂度。
• 不要完全不声明：除了工具误报，用户如果想做类型检查但没安装b，会遇到类型提示缺失的问题，体验很差。

额外建议 #

如果你的库文档里提到了do_a函数支持b.B类型，记得在文档里说明需要安装your-package[type-checking]才能获得完整的类型提示，让用户一目了然。

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