TypedDict

TypedDict是 Python 3.8+ 引入的类型提示工具（位于typing模块，Python 3.9+ 可直接在dict上使用泛型语法），用于为字典（dict）指定固定键名和对应值类型，解决了普通字典“键名不固定、值类型模糊”的类型提示问题，让代码更易读、更易维护，且能被类型检查工具（如mypy、PyCharm 内置检查）验证。

一、核心作用：给字典“定规矩”

普通字典的类型提示（如dict[str, int]）只能说明“键是字符串、值是整数”，但无法限制必须有哪些键、不能有哪些额外键。而TypedDict可以明确：

1. 字典必须包含哪些键；
2. 每个键对应的值必须是什么类型；
3. 可选键（非必需）和必填键的区分。

示例对比：

# 普通字典：只能知道键是 str、值是 int，但不知道具体有哪些键defprocess_user(user:dict[str,int])->None:print(user["id"])# 不确定 user 是否有 "id" 键，可能运行时出错print(user["age"])# 同样存在键缺失风险# TypedDict：明确指定键名和类型，类型检查工具会提前报错fromtypingimportTypedDictclassUser(TypedDict):id:int# 必填键age:int# 必填键name:str# 必填键email:str|None# 可选类型（值可以是 str 或 None）defprocess_user(user:User)->None:print(user["id"])# 安全：User 一定有 "id" 键，且类型是 intprint(user["email"])# 安全：类型是 str | None，不会误判类型

二、基本用法

1. 定义TypedDict（两种方式）

方式1：类继承TypedDict（推荐，可读性强）

fromtypingimportTypedDict# 定义一个表示“书籍”的 TypedDictclassBook(TypedDict):title:str# 书名（字符串，必填）author:str# 作者（字符串，必填）pages:int# 页数（整数，必填）price:float# 价格（浮点数，必填）is_published:bool# 是否出版（布尔值，必填）

方式2：函数式定义（适用于简单场景）

fromtypingimportTypedDict# 格式：TypedDict("名称", {键名: 类型, ...})Book=TypedDict("Book",{"title":str,"author":str,"pages":int,"price":float,"is_published":bool})

2. 可选键（非必需键）

用Optional（或| None，Python 3.10+）表示“值可以是该类型或 None”，但如果要表示“键本身可选”，需用total=False或Required/NotRequired（Python 3.11+ 推荐）。

方法1：全局total=False（所有键默认可选）

classBook(TypedDict,total=False):# total=False：所有键都是可选的title:strauthor:strpages:int# 合法：可以只传部分键book1:Book={"title":"Python 编程"}book2:Book={"author":"张三","pages":300}

方法2：Required/NotRequired（Python 3.11+，精准控制单个键）

更灵活，可混合必填和可选键：

fromtypingimportTypedDict,Required,NotRequiredclassBook(TypedDict):title:Required[str]# 明确必填author:Required[str]# 明确必填pages:NotRequired[int]# 明确可选（可省略该键）price:NotRequired[float]# 合法：必填键齐全，可选键可省book:Book={"title":"Python 编程","author":"张三"}# 合法：包含可选键book2:Book={"title":"Java 编程","author":"李四","pages":400,"price":59.9}# 不合法（类型检查报错）：缺少必填键 "author"book3:Book={"title":"C++ 编程"}

3. 使用TypedDict实例

TypedDict仅用于类型提示，运行时不会强制检查（Python 是动态类型语言），但类型检查工具（如mypy）会提前拦截错误：

# 正确实例：符合 Book 的键名和类型valid_book:Book={"title":"IPython 教程","author":"开发者","pages":200,"price":49.9,"is_published":True}# 错误实例1：键类型不匹配（price 应为 float，传了 int）invalid_book1:Book={"title":"IPython 教程","author":"开发者","pages":200,"price":49,# 类型检查报错：expected float, got int"is_published":True}# 错误实例2：缺少必填键（author）invalid_book2:Book={"title":"IPython 教程","pages":200,"price":49.9,"is_published":True}# 类型检查报错：missing required key "author"# 错误实例3：额外键（不允许未定义的键，除非用 total=False 且不限制）invalid_book3:Book={"title":"IPython 教程","author":"开发者","pages":200,"price":49.9,"is_published":True,"publisher":"出版社"# 类型检查报错：unexpected key "publisher"}

三、高级用法

1. 继承TypedDict（扩展已有结构）

可以像普通类一样继承TypedDict，实现结构复用：

fromtypingimportTypedDictclassBaseUser(TypedDict):id:intname:str# 继承 BaseUser，新增字段classAdminUser(BaseUser):permissions:list[str]# 管理员额外的“权限列表”字段department:str# 部门字段# 合法：包含 BaseUser 的所有键 + AdminUser 的新增键admin:AdminUser={"id":1,"name":"管理员","permissions":["delete","edit"],"department":"技术部"}

2. 嵌套TypedDict（复杂结构）

当字典的值是另一个字典时，可嵌套TypedDict实现多层类型提示：

fromtypingimportTypedDictclassAddress(TypedDict):city:strstreet:strzipcode:strclassUser(TypedDict):id:intname:straddress:Address# 嵌套 Address 类型# 合法：address 字段符合 Address 的结构user:User={"id":2,"name":"用户","address":{"city":"北京","street":"中关村大街","zipcode":"100080"}}

3. 与Union结合（多类型可选）

允许某个键的值是多种类型（用Union或|，Python 3.10+）：

fromtypingimportTypedDict,UnionclassProduct(TypedDict):id:intname:strprice:Union[int,float]# 价格可以是 int 或 float（Python 3.10+ 可写 int | float）# 两种价格类型都合法product1:Product={"id":1,"name":"手机","price":2999}# int 价格product2:Product={"id":2,"name":"耳机","price":199.9}# float 价格

4. Python 3.9+ 泛型语法（dict直接指定结构）

Python 3.9 引入了dict的泛型语法，可直接用dict[TypedDict]简化写法（无需显式继承TypedDict）：

# Python 3.9+ 支持fromtypingimportTypedDictclassUser(TypedDict):id:intname:str# 等同于 User 类型user:dict[str,int|str]# 普通泛型（不限制键名）user2:User# TypedDict（限制键名和对应类型）

四、TypedDict的注意事项

1. 仅用于类型提示，运行时不校验：Python 解释器不会在运行时检查字典是否符合TypedDict定义（比如少传键、类型不匹配不会报错），需配合mypy等工具做静态类型检查。

   # 安装 mypy 后，检查文件：mypy your_script.py

2. 键名必须是字符串常量：TypedDict的键只能是字符串（不能是变量、表达式），且定义时必须明确键名。

3. 与NamedTuple的区别：

   • TypedDict：本质是字典（dict实例），支持动态修改键值（但不建议修改结构）；
   • NamedTuple：本质是元组（tuple实例），不可变，更适合“固定结构、不修改”的场景。

4. total参数的默认值：默认total=True，即所有键都是必填的；total=False时，所有键都是可选的（可省略）。

五、应用场景

1. 接口数据校验：前后端交互、API 响应数据的结构提示（比如明确接口返回的字典必须包含code、message、data键，且类型固定）。
2. 配置文件解析：配置字典的键名和类型固定（比如数据库配置db_config必须包含host、port、user、password）。
3. 函数参数/返回值提示：明确函数接收的字典参数结构，或函数返回的字典结构，减少文档注释，提升代码可读性。

示例（API 响应数据）：

fromtypingimportTypedDict,Optional,ListclassUserData(TypedDict):id:intname:strage:Optional[int]classApiResponse(TypedDict):code:intmessage:strdata:Optional[List[UserData]]# data 是 UserData 列表或 None# 函数返回值类型提示：明确 API 响应结构deffetch_users()->ApiResponse:return{"code":200,"message":"success","data":[{"id":1,"name":"张三","age":25},{"id":2,"name":"李四","age":None}]}

总结

TypedDict是 Python 中给字典“结构化”的核心工具，通过明确键名和对应值类型，解决了普通字典类型提示模糊的问题。它不影响运行时性能，仅用于静态类型检查，能显著提升代码的可读性、可维护性，尤其适合数据交互、配置解析等字典结构固定的场景。

如果你的项目使用 Python 3.8+，且需要处理大量结构化字典数据，TypedDict是比普通dict类型提示更优的选择。