PYTHON

💻 Python Typing 类型注解

基础

python内置库。

typing库是Python 3.5及以上版本引入的，用于支持类型提示（Type Hints），旨在提高代码的可读性和可维护性，尤其在大型项目中非常有用。
⚠️ 注意：它不会影响Python的运行时行为，而是为开发者、IDE和静态类型检查工具提供支持。

类型

从typing模块的代码实现__all__属性中可知，typing库主要分为以下几个部分：

  • Super-special typing primitives: 特殊类型注解
  • ABCs(from collections.abc): ABC抽象基类
  • Structural checks, a.k.a. protocols: 结构检查，又称协议
  • Concete collection types: 具体集合类型
  • Other concrete types: 其他具体类型
  • One-off things: 其他

下面是每个部分的详细介绍：↓↓↓↓↓

Super-special typing primitives: 特殊类型注解

是 typing 模块中用于类型提示的核心工具

Annotated 为类型添加元数据，例如 Annotated[int, “user ID”]
Any 表示任意类型，适用于无法确定具体类型的情况。
Callable 注解可调用对象（如函数），例如 Callable[[int, str], bool] 表示接受一个 int 和一个 str 参数并返回 bool 的函数。
ClassVar 表示类变量，防止被误认为是实例属性。
Concatenate 用于连接参数列表，常与 ParamSpec 一起使用。
Final 表示变量或属性不可被子类重写或重新赋值。
ForwardRef 用于前向引用尚未定义的类型。
Generic 用于定义泛型类，支持类型参数化。
Literal 表示字面量类型，例如 Literal[“train”, “test”] 限制值为 “train” 或 “test”。
Optional 表示可选类型，即可以是指定类型或 None，例如 Optional[str]。
ParamSpec 捕获函数的参数规范，用于泛型函数。
Protocol 定义协议（结构性子类型），用于 duck typing。
Tuple 注解元组类型，例如 Tuple[int, str]。
Type 注解类型本身，例如 Type[MyClass]。
TypeVar 定义类型变量，用于泛型编程。
Union 表示联合类型，例如 Union[int, str] 表示可以是 int 或 str。

ABCs(from collections.abc): ABC抽象基类

来自 collections.abc 模块，用于表示集合和容器的类型

AbstractSet 抽象集合
ByteString 字节串类型
Container 容器类型，支持 in 操作
ContextManager 上下文管理器
Hashable 可哈希对象
ItemsView 字典的 items() 视图
Iterable 可迭代对象
Iterator 迭代器
KeysView 字典的 keys() 视图
Mapping 映射类型，如字典
MappingView 映射视图
MutableMapping 可变映射
MutableSequence 可变序列
MutableSet 可变集合
Sequence 序列类型
Sized 支持 len() 的对象
ValuesView 字典的 values() 视图
Awaitable 可等待对象
AsyncIterator 异步迭代器
AsyncIterable 异步可迭代对象
Coroutine 协程
Collection 集合类型
AsyncGenerator 异步生成器
AsyncContextManager 异步上下文管理器

Structural checks, a.k.a. protocols: 结构检查，又称协议

定义 duck typing 的结构。

Reversible 支持反向迭代
SupportsAbs 支持 abs() 函数
SupportsBytes 支持 bytes() 函数
SupportsComplex 支持 complex() 函数
SupportsFloat 支持 float() 函数
SupportsIndex 支持 index() 方法
SupportsInt 支持 int() 函数
SupportsRound 支持 round() 函数

Concete collection types: 具体集合类型

ChainMap 链式映射
Counter 计数器
Deque 双端队列
Dict 字典
DefaultDict 默认字典
List 列表
OrderedDict 有序字典
Set 集合
FrozenSet 冻结集合
NamedTuple 具名元组
TypedDict 类型字典
Generator 生成器

Other concrete types: 其他具体类型

BinaryIO 二进制I/O
IO 通用I/O
Match 正则匹配对象
Pattern 正则模式对象
TextIO 文本I/O

One-off things: 其他

与类型提示相关的辅助工具和类型

AnyStr 表示str或bytes \

cast 用于类型转换（仅在类型检查时有效）
final 装饰器，标记方法不可被重写
get_args 获取类型提示的参数
get_origin 获取类型提示的原始类型
get_type_hints 获取函数或类的类型提示
is_typeddict 检查是否为 TypedDict
NewType 创建新类型（仅在类型检查时有效）
no_type_check 跳过类型检查
no_type_check_decorator：装饰器，跳过函数的类型检查
NoReturn：表示函数永不返回
overload：定义函数重载
ParamSpecArgs 和 ParamSpecKwargs：与 ParamSpec 相关的工具
runtime_checkable：使协议在运行时可检查
Text：别名str
TYPE_CHECKING：在类型检查时为 True，运行时为 False
TypeAlias：标记类型别名
TypeGuard：用于类型守卫， narrowing 类型