Python 类型提示 TypedDict 告别字典类型错误，提升代码编辑器体验！

# 函数：打印坐标

def print_coords(coord):

   # 这里根本不知道coord需要哪些字段、字段类型是什么

   print(f"X坐标：{coord['x']}，Y坐标：{coord['y']}")

   # 如果后续要计算，类型错了就会崩

   print(f"坐标和：{coord['x'] + coord['y']}")

# 坑1：少传字段，运行时才报错

print_coords({"x": 10})  # 运行后报错：KeyError: 'y'

# 坑2：字段类型错，计算时才报错

print_coords({"x": 10, "y": "20"})  # 打印X/Y时没事，计算时报错：TypeError: unsupported operand type(s) for +: 'int' and 'str'

# 坑3：编辑器没提示，写代码全靠记

# 输入coord.的时候，编辑器根本不知道有x/y字段，没法自动补全

pip install typing-extensions

# Python 3.8+：基础用法

from typing import TypedDict

# 1. 定义TypedDict类：告诉编辑器，Coord类型的字典必须有x（int）和y（int）

class Coord(TypedDict):

   x: int  # 字段名：x，类型：整数（必需）

   y: int  # 字段名：y，类型：整数（必需）

# 2. 用TypedDict给函数参数加提示

def print_coords(coord: Coord):

   print(f"X坐标：{coord['x']}，Y坐标：{coord['y']}")

   print(f"坐标和：{coord['x'] + coord['y']}")

# 3. 正确使用：字段和类型都对

correct_coord: Coord = {"x": 10, "y": 20}  # 编辑器不报错

print_coords(correct_coord)  # 输出：X坐标：10，Y坐标：20；坐标和：30

# 4. 错误场景：编辑器实时报错（不用等运行）

# 错1：少传y字段（必需字段）

missing_field_coord: Coord = {"x": 10}  # 编辑器提示：缺少必需字段'y'

# 错2：y字段类型错（该传int，传了str）

wrong_type_coord: Coord = {"x": 10, "y": "20"}  # 编辑器提示：类型不匹配（str≠int）

# 情况1：Python 3.11+（直接用typing的NotRequired）

from typing import TypedDict, NotRequired

class User(TypedDict):

   id: int               # 必需字段：用户ID（整数）

   name: str             # 必需字段：用户名（字符串）

   email: NotRequired[str]  # 可选字段：邮箱（字符串，可不存在）

   age: NotRequired[int]    # 可选字段：年龄（整数，可不存在）

# 情况2：Python <3.11（用typing-extensions的NotRequired）

# from typing_extensions import TypedDict, NotRequired

# class User(TypedDict):

#     id: int

#     name: str

#     email: NotRequired[str]

# 正确用法：

user1: User = {"id": 1, "name": "Alice"}  # 只有必需字段，OK

user2: User = {"id": 2, "name": "Bob", "email": "bob@example.com"}  # 有必需+可选，OK

user3: User = {"id": 3, "name": "Charlie", "age": 25}  # 有必需+另一个可选，OK

# 错误用法（编辑器提示）：

user4: User = {"id": 4}  # 缺name（必需字段），报错

user5: User = {"id": 5, "name": "Dave", "email": 12345}  # email类型错（该是str，传了int），报错

from typing import TypedDict, Required  # Required也是3.11+

# total=False：所有字段默认可选，用Required标记必需字段

class Product(TypedDict, total=False):

   id: Required[int]  # 必需字段：产品ID

   name: str          # 可选字段：产品名

   price: float       # 可选字段：价格

   stock: int         # 可选字段：库存

# 正确用法：

product1: Product = {"id": 1001}  # 只有必需字段，OK

product2: Product = {"id": 1002, "name": "手机", "price": 2999.9}  # 必需+部分可选，OK

# 错误用法：

product3: Product = {"name": "电脑", "price": 5999.9}  # 缺id（Required字段），报错

# Python 3.9+：简洁用法

from typing import TypedDict

# 直接标注：这个字典是TypedDict类型，有name（str）和score（int）字段

student: TypedDict("Student", {"name": str, "score": int}) = {

   "name": "小明",

   "score": 95

}

# 函数参数也能这么用（但不如类继承清晰，复杂场景不推荐）

def print_student(student: TypedDict("Student", {"name": str, "score": int})):

   print(f"姓名：{student['name']}，分数：{student['score']}")

print_student(student)  # 输出：姓名：小明，分数：95

from typing import TypedDict

# 字段名是"for"（关键字），用引号括起来

class QueryParams(TypedDict):

   "for": str  # 正确：用引号避免关键字冲突

   limit: int

   offset: int

# 创建实例：

params: QueryParams = {"for": "user", "limit": 10, "offset": 0}

# 访问时：不能用params.for（会报错），必须用下标params["for"]

print(params["for"])  # 输出：user

print(params["limit"])  # 输出：10

from typing import TypedDict, Optional

class OldUser(TypedDict):

   id: int

   name: str

   email: Optional[str]  # 旧写法：想表示“邮箱可选”，但实际是“必须有email，值可None”

# 旧写法的问题：

user: OldUser = {"id": 1, "name": "Alice"}  # 编辑器报错：缺少email字段（因为Optional要求字段必须存在）

user: OldUser = {"id": 1, "name": "Alice", "email": None}  # 这才是旧写法的正确用法（字段存在，值为None）

from typing import TypedDict, NotRequired

class NewUser(TypedDict):

   id: int

   name: str

   email: NotRequired[str]  # 正确：邮箱字段可不存在

user: NewUser = {"id": 1, "name": "Alice"}  # OK，字段可不存在

user: NewUser = {"id": 1, "name": "Alice", "email": "alice@example.com"}  # OK，字段存在

from typing import TypedDict

class Coord(TypedDict):

   x: int

   y: int

# 强行传错类型，运行时不报错（但编辑器提示错误）

wrong_coord: Coord = {"x": "10", "y": 20}  # 运行时不报错

print(wrong_coord["x"] + wrong_coord["y"])  # 运行时才报错：TypeError（str+int）

[

   {

       "id": 1,

       "name": "Alice",

       "email": "alice@example.com",

       "address": {"city": "Beijing", "street": "Main St"}

   },

   {

       "id": 2,

       "name": "Bob",

       "address": {"city": "Shanghai"}

   }

]

from typing import TypedDict, List, NotRequired

# 1. 先定义嵌套的Address TypedDict（因为address是字典）

class Address(TypedDict):

   city: str  # 必需：城市

   street: NotRequired[str]  # 可选：街道

# 2. 定义User TypedDict，包含嵌套的Address

class User(TypedDict):

   id: int  # 必需：用户ID

   name: str  # 必需：用户名

   email: NotRequired[str]  # 可选：邮箱

   address: Address  # 必需：地址（嵌套的TypedDict）

# 3. 定义API返回的类型（列表，每个元素是User）

UserList = List[User]

# 4. 模拟API返回数据

def get_user_list() -> UserList:

   return [

       {

           "id": 1,

           "name": "Alice",

           "email": "alice@example.com",

           "address": {"city": "Beijing", "street": "Main St"}

       },

       {

           "id": 2,

           "name": "Bob",

           "address": {"city": "Shanghai"}  # street可选，OK

       }

   ]

# 5. 处理用户数据

user_list = get_user_list()

for user in user_list:

   # 编辑器会自动提示user的字段：id、name、email、address

   print(f"用户{user['id']}：{user['name']}")

   # 访问嵌套的address字段，编辑器也有提示

   print(f"  城市：{user['address']['city']}")

   # 可选字段需要先判断是否存在

   if "street" in user['address']:

       print(f"  街道：{user['address']['street']}")

   if "email" in user:

       print(f"  邮箱：{user['email']}")

用户1：Alice

 城市：Beijing

 街道：Main St

 邮箱：alice@example.com

用户2：Bob

 城市：Shanghai