如何从typing.TypeAlias迁移至type语句并解决isinstance报错？

问题背景 #

之前我用TypeAlias注解创建类型别名，既能给dataclass成员变量做标注，运行时也能直接用在isinstance检查：

>>> from typing import TypeAlias
>>> Number: TypeAlias = int | float
>>> n, x = 1, 2.5
>>> isinstance(n, Number)
True
>>> isinstance(x, Number)
True

但Python 3.12起官方弃用了这种写法，推荐使用type语句：

Deprecated since version 3.12: TypeAlias is deprecated in favor of the type statement, which creates instances of TypeAliasType and which natively supports forward references. Note that while TypeAlias and TypeAliasType serve similar purposes and have similar names, they are distinct and the latter is not the type of the former. Removal of TypeAlias is not currently planned, but users are encouraged to migrate to type statements.

我切换到新语法后，用isinstance检查时报错：

>>> type Number = int | float
>>> isinstance(n, Number)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() arg 2 must be a type, a tuple of types, or a union

原因分析 #

type语句创建的Number是TypeAliasType的实例，它是类型注解层面的别名，并非运行时的类型对象（比如int、float或者它们的联合类型），所以无法直接作为isinstance的第二个参数。

解决办法 #

根据使用场景选择对应方案：

1. 仅用于类型注解（无需运行时检查） #

如果只是给dataclass成员做类型标注，不需要在运行时用isinstance验证，直接保留type语句写法即可：

type Number = int | float

from dataclasses import dataclass

@dataclass
class Data:
    value: Number

类型检查工具（如mypy、pyright）能正常识别这个别名，不会影响静态类型检查。

2. 需要运行时类型检查 #

如果必须在运行时用isinstance验证，有两种可行方案：

方案A：直接绑定类型对象（舍弃TypeAliasType特性）

跳过type语句，直接把别名绑定到实际的联合类型，这样Number就是标准的类型对象，能直接用于isinstance：

Number = int | float
n, x = 1, 2.5
print(isinstance(n, Number))  # 输出True
print(isinstance(x, Number))  # 输出True

缺点是类型检查工具无法区分这是类型别名还是普通变量，若需要工具明确识别别名身份，不推荐此写法。

方案B：解析TypeAliasType获取实际类型

利用typing模块的工具函数解析TypeAliasType实例，拿到背后的实际类型：

from typing import get_type_hints

type Number = int | float
n, x = 1, 2.5

# 解析TypeAliasType获取实际类型
actual_type = get_type_hints(lambda: Number)['return']
print(isinstance(n, actual_type))  # 输出True
print(isinstance(x, actual_type))  # 输出True

也可以直接访问TypeAliasType的私有属性__value__（注意：私有属性可能在后续Python版本中变动，谨慎使用）：

type Number = int | float
actual_type = Number.__value__
print(isinstance(n, actual_type))  # 输出True

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