如何在不依赖numpy的前提下为Python库添加可选numpy类型支持

要在不强制依赖numpy的前提下，给函数添加numpy类型的类型提示，同时满足Python3.8+、setuptools69+及IDE智能提示需求，可按以下步骤实现：

一、代码层面：用TYPE_CHECKING隔离numpy类型导入 #

利用typing.TYPE_CHECKING常量（仅类型检查/IDE分析时为True，运行时为False），实现numpy类型的条件导入和类型别名定义，避免未安装numpy时的运行时错误：

from typing import TYPE_CHECKING, Union, List

# 仅在类型检查阶段导入numpy相关类型
if TYPE_CHECKING:
    from numpy.typing import ArrayLike
    from numpy import floating, integer
    # 定义包含numpy类型的联合类型别名
    NumericLike = Union[float, int, List[Union[float, int]], ArrayLike, floating, integer]
else:
    # 运行时仅保留基础数值类型
    NumericLike = Union[float, int, List[Union[float, int]]]

def cool(value: NumericLike) -> None:
    # 函数逻辑：运行时兼容numpy类型（比如通过hasattr判断处理）
    if hasattr(value, "__array__"):
        # 处理numpy数组/数值的逻辑
        processed = value.tolist()
    # 其他核心逻辑
    ...

关键细节： #

• Python3.8兼容：使用typing.Union和typing.List替代3.9+的原生类型语法（|、list[...]）
• 类型检查隔离：numpy的导入仅在类型检查时执行，运行时完全不依赖numpy
• 运行时兼容性：函数内部通过hasattr等方式判断并处理numpy类型，保证实际运行时的兼容性

二、pyproject.toml配置：添加numpy可选依赖 #

在项目的pyproject.toml中，将numpy配置为可选依赖，让需要类型提示的用户自行安装：

[project]
name = "your-package-name"
version = "0.1.0"
python = ">=3.8"
# 其他基础配置（如作者、描述等）参考你的现有模板

[project.optional-dependencies]
# 命名可选依赖组，用户通过pip install your-package[numpy-support]安装
numpy-support = [
    "numpy>=1.21.0"  # 选择兼容Python3.8的最低numpy版本
]

[build-system]
requires = ["setuptools>=69.0", "wheel"]
build-backend = "setuptools.build_meta"

关键细节： #

• setuptools69+适配：无需额外配置，只要pyproject.toml符合PEP 621规范即可
• 可选依赖逻辑：用户默认安装时不会包含numpy，仅主动安装可选依赖组后才会获取numpy类型提示支持

三、IDE智能提示支持 #

• 当用户安装了your-package[numpy-support]后，VSCode等IDE会自动识别numpy类型并在输入cool(时提供完整的类型补全提示
• 未安装numpy时，IDE会忽略numpy相关的类型注解，仅显示基础数值类型的提示，不影响正常使用

补充说明 #

• 无需单独依赖numpy.typing：numpy.typing是numpy的内置子包，安装numpy时会自动包含，单独安装反而可能引发依赖不兼容问题
• 类型检查工具兼容：mypy、pyright等主流类型检查工具会正确识别条件导入的numpy类型，不会报未导入错误

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