如何在Python函数中为时区感知datetime对象显式添加类型提示？

方案1：用NewType创建名义类型别名 #

通过typing.NewType定义专属类型别名，让类型提示明确区分两种datetime：

import datetime as dt
from typing import NewType

# 定义时区感知datetime的类型别名
TZAwareDatetime = NewType("TZAwareDatetime", dt.datetime)
# 定义非时区感知datetime的类型别名
NaiveDatetime = NewType("NaiveDatetime", dt.datetime)

# 使用示例
def func(num: int, ref_datetime: TZAwareDatetime) -> TZAwareDatetime:
    # 返回时用别名包装，确保类型检查器识别
    return TZAwareDatetime(ref_datetime + dt.timedelta(days=num))

NewType创建的是名义类型，运行时本质还是dt.datetime，但mypy、pyright这类静态类型检查器会严格区分两种别名对应的类型，强制传入符合要求的datetime对象。

方案2：用Protocol定义结构性类型 #

用typing.Protocol定义协议，通过tzinfo属性的存在性区分，无需手动包装，更贴合Python动态特性：

import datetime as dt
from typing import Protocol

class TZAwareDatetime(Protocol):
    # 协议声明：该类型必须有非None的tzinfo属性
    tzinfo: dt.tzinfo

class NaiveDatetime(Protocol):
    # 协议声明：该类型的tzinfo必须为None
    tzinfo: None

# 使用示例
def func(num: int, ref_datetime: TZAwareDatetime) -> TZAwareDatetime:
    return ref_datetime + dt.timedelta(days=num)

这种方式下，静态类型检查器会自动校验传入的ref_datetime是否符合协议要求——时区感知的datetime必须有有效的tzinfo，非时区感知的则tzinfo为None，完全不需要额外代码，纯靠类型提示实现区分。

关键说明 #

• 两种方案都依赖静态类型检查器，Python解释器运行时不会做类型验证，完全符合你“仅通过类型提示或接近方式明确要求”的需求。
• 标准库datetime本身没有内置子类型区分这两种datetime，必须通过自定义类型实现。

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