Python中如何实现具备语义信息的类型注解？

Python原生支持这类带业务语义的类型注解，不需要依赖非官方黑魔法，针对你的时间戳场景，有三种成熟实现方式可选：

方案1：用NewType创建轻量语义别名（最适配你的场景） #

typing.NewType是标准库专门为「给基础类型附加语义区分」设计的工具，零运行时开销，所有主流类型检查器（mypy、pyright、PyCharm内置检查）都能完美识别。
你不需要在docstring里重复解释参数是时间戳，看注解就能明确语义，完全替代你想实现的datetime.datetime.timestamp注解效果。
示例代码：

import time
from datetime import datetime
from typing import NewType

# 定义语义类型：本质是float，语义为Unix时间戳
UnixTimestamp = NewType("UnixTimestamp", float)

def myfunc(start_date: UnixTimestamp, end_date: UnixTimestamp) -> dict:
    # 函数内部可以直接当普通float使用，不需要额外转换
    return {
        "start": datetime.fromtimestamp(start_date),
        "end": datetime.fromtimestamp(end_date)
    }

# 调用示例
if __name__ == "__main__":
    start = UnixTimestamp(time.time() - 86400)
    end = UnixTimestamp(time.time())
    result = myfunc(start, end)

这个方案的特点：

• 完全不改变运行时逻辑：NewType本身是个返回入参的恒等函数，不会做任何包装、转换，性能和直接用float没有区别
• 类型检查生效：如果你误把表示金额、身高的普通float传给参数，类型检查器会提示语义不匹配，避免传参顺序错误这类低级bug
• 代码可读性拉满：不需要看docstring，扫一眼注解就知道两个参数要传时间戳，而不是随便什么浮点数

注：你之前尝试写的datetime.datetime.timestamp不能作为类型注解，它是datetime实例的方法，作用是把datetime对象转为浮点时间戳，本身不属于类型对象，类型检查器无法识别。

方案2：用Annotated附加更丰富的语义元数据 #

如果除了基础语义，你还需要给类型附加更多信息（比如时间戳是秒级还是毫秒级、取值范围、业务规则），可以用Python 3.9+标准库提供的Annotated（3.8版本可从typing_extensions导入）。
示例代码：

from datetime import datetime
from typing import Annotated

# 定义两种不同精度的时间戳语义类型
UnixTimestampSec = Annotated[float, "unix_timestamp", "unit: seconds", "range: 0~4102444800"]
UnixTimestampMs = Annotated[float, "unix_timestamp", "unit: milliseconds", "range: 0~4102444800000"]

def myfunc(start_date: UnixTimestampSec, end_date: UnixTimestampSec) -> dict:
    return {"start": datetime.fromtimestamp(start_date), "end": datetime.fromtimestamp(end_date)}

这个方案的特点：

• 支持附加任意数量、任意类型的语义元数据，运行时可以通过typing.get_type_hints()读取这些元数据，用来做自动参数校验、文档生成
• 同样零运行时开销，不改变底层float类型的行为
• 适合需要细分同语义下不同规则的场景

方案3：自定义语义子类实现运行时校验 #

如果你不仅要注解语义，还希望在传参时自动校验值是否符合语义规则（比如判断传入的浮点数是不是合法的时间戳），可以自定义float的子类实现：

import time
from datetime import datetime

class UnixTimestamp(float):
    def __new__(cls, value: float):
        # 加入合法性校验：时间戳范围在1970年到2100年之间
        if not 0 <= value <= 4102444800:
            raise ValueError(f"Invalid unix timestamp: {value}")
        return super().__new__(cls, value)

def myfunc(start_date: UnixTimestamp, end_date: UnixTimestamp) -> dict:
    # 子类实例完全兼容float的所有操作，可以直接参与计算、传参给接收float的函数
    return {"duration": end_date - start_date}

# 调用时如果传入非法值会直接抛出错误，从源头拦截非法参数
myfunc(UnixTimestamp(time.time()-86400), UnixTimestamp(time.time()))

选型建议 #

• 只是需要区分同基础类型的不同语义、不需要额外功能，优先选NewType，最轻量最简单
• 需要给类型附加单位、取值规则等元数据，选Annotated
• 需要运行时自动校验参数合法性，选自定义子类方案

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