如何正确重载接受任意位置参数、返回int或元组的Python函数？

实现思路 #

直接用Union返回类型只能让类型检查器识别模糊的返回范围，要实现「传1个参数返回int，传多个返回对应长度元组」的精准类型推断，需要用typing.overload定义多组函数签名，分别匹配不同参数数量的场景，最后统一实现核心逻辑。

完整代码示例 #

首先导入必要模块：

from datetime import datetime
from typing import overload, Union, Tuple

定义重载签名（注意顺序，具体场景的签名要放在通用场景前面，让类型检查器优先匹配精准规则）：

# 单个参数：返回int
@overload
def timestamp(date: Union[datetime, str, int]) -> int: ...

# 两个参数：返回长度为2的int元组
@overload
def timestamp(date1: Union[datetime, str, int], date2: Union[datetime, str, int]) -> Tuple[int, int]: ...

# 三个参数：返回长度为3的int元组
@overload
def timestamp(date1: Union[datetime, str, int], date2: Union[datetime, str, int], date3: Union[datetime, str, int]) -> Tuple[int, int, int]: ...

# 任意数量（0个或≥4个）参数：返回任意长度的int元组
@overload
def timestamp(*date: Union[datetime, str, int]) -> Tuple[int, ...]: ...

然后是实际函数实现（保留你的核心逻辑，优化了推导式写法）：

def timestamp(*date: Union[datetime, str, int]) -> int | Tuple[int, ...]:
    """
    将日期转换为时间戳

    :param date: 要转换为时间戳的日期
    :return: 距离纪元时间的秒数；传入多个日期时返回对应长度的时间戳元组
    """
    if len(date) == 1:
        return timestamp_(date[0])
    return tuple(timestamp_(d) for d in date)

确保辅助函数timestamp_也有正确的类型提示（保证类型链完整）：

def timestamp_(date: Union[datetime, str, int]) -> int:
    # 这里写实际转换逻辑，示例如下：
    if isinstance(date, datetime):
        return int(date.timestamp())
    elif isinstance(date, str):
        return int(datetime.fromisoformat(date).timestamp())
    elif isinstance(date, int):
        return date
    raise TypeError("不支持的日期类型")

效果说明 #

• 传入1个参数时，类型检查器会精确推断返回类型为int，而非模糊的int | Tuple[int, ...]；
• 传入2/3个参数时，会推断返回对应长度的元组，获得更精准的代码提示和类型检查；
• 传入0个或≥4个参数时，匹配通用重载规则，返回Tuple[int, ...]；
• 所有重载最终指向同一个实现，不会增加额外逻辑负担。

内容的提问来源于stack exchange，提问作者demetere._