Python TypedDict 类型

说明

《Python 教程》持续更新中，提供建议、纠错、催更等加作者微信: gairuo123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

TypedDict 是 Python 的 typing 模块中用于定义具有严格键和值类型约束的字典类型的工具。它最初在 PEP 589 中引入，从 Python 3.8 开始可用，并在 3.9 及更高版本中有了进一步增强。

与普通的 dict 不同，TypedDict 提供了一种方法来明确指定字典的结构，包括键和值的类型，从而增强类型检查和代码的可读性。

`TypedDict` 的特点

键和值的类型约束：
- 使用 TypedDict 定义的字典，其键是预定义的，并且每个键的值类型需要明确声明。
- 在使用时，如果键或值的类型不符合定义，静态类型检查工具（如 mypy）会提示错误。
运行时仍是普通字典：
- 在运行时，TypedDict 本质上还是普通的 Python 字典，因此可以像普通字典一样操作。
支持必选和可选字段：
- 可以区分字段是必须存在的还是可以省略的。

`TypedDict` 的使用

1. 定义一个基本的 `TypedDict`

使用 TypedDict 创建一个字典类型。

from typing import TypedDict

# 定义一个 TypedDict
class Person(TypedDict):
    name: str
    age: int
    is_employed: bool

# 使用 TypedDict 定义的字典
person: Person = {
    "name": "Alice",
    "age": 30,
    "is_employed": True,
}

# 访问字段
print(person["name"])  # 输出: Alice

# 如果键或值类型不匹配，mypy 等工具会报错

2. 可选字段

通过设置 total=False，可以定义一些可选字段。

from typing import TypedDict

class PartialPerson(TypedDict, total=False):
    name: str  # 可选字段
    age: int   # 可选字段
    is_employed: bool  # 可选字段

# 合法的用法
partial_person: PartialPerson = {
    "name": "Bob",
}

print(partial_person)  # 输出: {'name': 'Bob'}

与普通字典的区别

TypedDict 和普通字典的主要区别如下：

特性	普通字典 `dict`	`TypedDict`
键的类型是否固定	否	是（只能是预定义键）
值的类型是否固定	否	是（与定义一致）
静态类型检查支持	否	是（通过工具如 `mypy` 检查）
动态行为	完全动态	与普通字典一致

`TypedDict` 的高级特性

1. 嵌套 `TypedDict`

TypedDict 可以嵌套使用，用于定义更复杂的数据结构。

class Address(TypedDict):
    street: str
    city: str
    zip_code: int

class PersonWithAddress(TypedDict):
    name: str
    age: int
    address: Address

# 嵌套结构
person_with_address: PersonWithAddress = {
    "name": "Alice",
    "age": 30,
    "address": {
        "street": "123 Main St",
        "city": "Wonderland",
        "zip_code": 12345,
    },
}

2. 字段继承

TypedDict 支持继承，可以创建一个基础类型并在其上扩展。

class BasicPerson(TypedDict):
    name: str
    age: int

class Employee(BasicPerson):
    employee_id: int
    department: str

employee: Employee = {
    "name": "Bob",
    "age": 25,
    "employee_id": 101,
    "department": "Engineering",
}

配合静态类型检查工具

TypedDict 的主要价值在于它与静态类型检查工具（如 mypy）的配合使用。它能够在开发阶段捕获类型错误。

示例：

如果定义的键或值类型不正确，mypy 会报错：

from typing import TypedDict

class Car(TypedDict):
    make: str
    year: int

car: Car = {
    "make": "Toyota",
    "year": "2020",  # 错误：year 应为 int
}

运行 mypy：

$ mypy example.py
example.py:9: error: Incompatible types (expression has type "str", expected "int")

应用场景

定义接口结构：
- 用于描述函数的输入和输出结构。
描述配置文件：
- 对配置字典进行类型限制，提高代码的健壮性。
JSON 数据处理：
- 明确 JSON 数据的键和值的类型，用于数据验证和静态检查。

总结

TypedDict 是 Python 提供的一种类型安全的工具，非常适合需要明确字典结构的场景，尤其是在大型项目中使用时，可以显著提高代码的可读性和可靠性。

参考

https://docs.python.org/3/library/typing.html#typing.TypedDict
https://peps.python.org/pep-0589/

Python 标准库 typing 类型注解标注

更新时间：2024-12-03 06:57:47 标签：python 数据类型字典