使用 typing.overload 精确类型化可变参数函数的条件返回

from datetime import datetime
from typing import Union, Tuple

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

    :param date: 要转换的日期，可以是 datetime 对象、字符串或整数。
    :return: 如果只传入一个日期，返回一个整数时间戳；否则，返回一个包含整数时间戳的元组。
    """
    # 假设 timestamp_ 是一个辅助函数，将单个日期转换为时间戳
    def timestamp_(d_item: Union[datetime, str, int]) -> int:
        # 实际实现可能涉及日期解析和转换
        if isinstance(d_item, datetime):
            return int(d_item.timestamp())
        elif isinstance(d_item, str):
            # 示例：简单处理，实际应有更健壮的解析
            return int(datetime.strptime(d_item, "%Y-%m-%d").timestamp())
        elif isinstance(d_item, int):
            return d_item # 假设传入的整数已经是时间戳
        raise ValueError("Unsupported date type")

    if len(date) == 1:
        return timestamp_(date[0])
    return tuple([timestamp_(d) for d in date])

# 此时，类型检查器会认为 timestamp(date_obj) 的返回类型是 int | Tuple[int, ...]
# 而我们希望它明确是 int

import typing as t
from datetime import datetime

# 定义处理单个位置参数的重载签名
@t.overload
def timestamp(date: datetime | str | int, /) -> int:
    """
    处理只传入一个位置参数的情况，返回一个整数时间戳。

    注意：`# type: ignore[overload-overlap]` 可能因 Mypy 版本而异。
    这里是为了避免 Mypy 报告此重载与下面的可变参数重载存在重叠。
    我们希望在传入一个参数时，类型检查器优先选择此更具体的重载。
    """
    # type: ignore[overload-overlap]

# 定义处理零个、两个或更多位置参数的重载签名
@t.overload
def timestamp(*date: datetime | str | int) -> tuple[int, ...]:
    """
    处理传入零个、两个或更多位置参数的情况，返回一个整数时间戳元组。
    """
    ... # 重载签名中不需要实际的实现

# 实际的函数实现
def timestamp(*date: datetime | str | int) -> int | tuple[int, ...]:
    """
    将日期转换为时间戳的实际实现。
    """
    def _convert_single_date_to_timestamp(d_item: datetime | str | int) -> int:
        if isinstance(d_item, datetime):
            return int(d_item.timestamp())
        elif isinstance(d_item, str):
            try:
                # 尝试多种日期格式，这里仅为示例
                return int(datetime.strptime(d_item, "%Y-%m-%d").timestamp())
            except ValueError:
                raise ValueError(f"无法解析日期字符串: {d_item}")
        elif isinstance(d_item, int):
            return d_item # 假设传入的整数已经是时间戳
        raise TypeError(f"不支持的日期类型: {type(d_item)}")

    if len(date) == 1:
        return _convert_single_date_to_timestamp(date[0])
    return tuple([_convert_single_date_to_timestamp(d) for d in date])

# 假设我们有一个辅助函数 reveal_type 用于在 Mypy 中显示类型
# 在实际代码中，这只是一个注释，Mypy 会自行分析
# from mypy import reveal_type # 实际上不需要导入，Mypy 命令行工具会显示

# 示例调用
reveal_type(timestamp(datetime.now()))     # 预期 Mypy 显示: Revealed type is "builtins.int"
reveal_type(timestamp("2023-01-01"))       # 预期 Mypy 显示: Revealed type is "builtins.int"
reveal_type(timestamp(1672531200))         # 预期 Mypy 显示: Revealed type is "builtins.int"

reveal_type(timestamp(datetime.now(), "2023-01-01")) # 预期 Mypy 显示: Revealed type is "builtins.tuple[builtins.int, ...]"
reveal_type(timestamp())                   # 预期 Mypy 显示: Revealed type is "builtins.tuple[builtins.int, ...]" (空元组)