在 Python 类型提示中，Optional[T] 表示“可能是 None”，而非“可省略”；要表达参数可省略但不可为 None，必须通过额外的 @overload 声明来显式支持无该参数的调用形式。
在 python 类型提示中，`optional[t]` 表示“可能是 `none`”，而非“可省略”；要表达参数**可省略但不可为 `none`**，必须通过额外的 `@overload` 声明来显式支持无该参数的调用形式。
当使用 @overload 实现多态类型签名时，类型检查器（如 mypy）仅依据调用时传入的实参个数和类型匹配最精确的 overload，而不考虑运行时默认参数的存在。因此，即使你在实现函数中为 expected_output_type 设置了默认值 HDF5DataTypes.UNKNOWN，若没有对应「两参数」的 overload，mypy 仍会报错：No overloads match the provided arguments。
✅ 正确做法是：显式添加一个不带 expected_output_type 参数的 overload，其返回类型应与 UNKNOWN 分支一致（即联合类型 Union[npt.NDArray, np.float_]），并确保其实现逻辑兼容该签名：
from typing import Union, List, overload, cast
import numpy as np
import numpy.typing as npt
import h5py
from enum import Enum
class HDF5DataTypes(Enum):
SCALAR = "scalar"
ARRAY = "array"
UNKNOWN = "unknown"
# ✅ 新增：两参数 overload（参数真正可省略）
@overload
def index_hdf5_to_value(
file_or_group: Union[h5py.File, h5py.Group],
indexes: List[str]
) -> Union[npt.NDArray, np.float_]:
...
# ✅ 保持原有三参数 overload（含默认值的 Literal 重载更精准）
@overload
def index_hdf5_to_value(
file_or_group: Union[h5py.File, h5py.Group],
indexes: List[str],
expected_output_type: Literal[HDF5DataTypes.SCALAR]
) -> np.float_:
...
@overload
def index_hdf5_to_value(
file_or_group: Union[h5py.File, h5py.Group],
indexes: List[str],
expected_output_type: Literal[HDF5DataTypes.ARRAY]
) -> npt.NDArray:
...
@overload
def index_hdf5_to_value(
file_or_group: Union[h5py.File, h5py.Group],
indexes: List[str],
expected_output_type: Literal[HDF5DataTypes.UNKNOWN] = HDF5DataTypes.UNKNOWN
) -> Union[npt.NDArray, np.float_]:
...
# 实现体（无类型注解，仅含逻辑）
def index_hdf5_to_value(
file_or_group: Union[h5py.File, h5py.Group],
indexes: List[str],
expected_output_type: HDF5DataTypes = HDF5DataTypes.UNKNOWN
) -> Union[npt.NDArray, np.float_]:
dataset = index_hdf5(file_or_group, indexes, h5py.Dataset)
if len(dataset.shape) == 0:
if expected_output_type == HDF5DataTypes.ARRAY:
raise ValueError("Expected output to be an array, but it was a scalar")
return cast(np.float_, dataset[()])
else:
if expected_output_type == HDF5DataTypes.SCALAR:
raise ValueError("Expected output to be a scalar, but it was an array")
return cast(npt.NDArray, dataset[:])? 关键注意事项：
- 所有 @overload 声明必须严格位于实现函数之前，且实现函数本身不能有类型注解（否则 mypy 会报错）；
- 新增的两参数 overload 必须放在最上方（或至少在更具体的 overload 之前），以保证类型检查器优先匹配最宽泛但合法的调用形式；
- expected_output_type 的默认值 = HDF5DataTypes.UNKNOWN 应保留在实现函数和对应的 overload 中，确保运行时行为一致；
- ❌ 不要使用 expected_output_type: Optional[HDF5DataTypes] —— 这会错误地允许 None，违背设计意图，且无法解决“参数省略”问题。
这样，用户即可安全调用 index_hdf5_to_value(hdf5_file, ["key1", "key2"])，享受完整的静态类型检查，同时保持接口语义清晰：该参数是可选的（omittable），而非可为空的（nullable）。
