Python
13 类型注解实战
读懂 `def f(x: str) -> list[str]`,理解注解「运行时不校验」
- Python
- 进阶
目标:把「类型注解是一份写给人和工具看的说明书,运行时默认不校验」这条主线打通——学完能给变量、函数、类属性写注解,用
list[str]、int | None、Literal描述真实数据形状,并用 mypy 把注解变成真正拦得住 bug 的检查。 与 LangChain 的关系:LangChain 全家桶建立在 pydantic 之上,而 pydantic 的能力全部从类型注解出发——你在Field(description=...)、with_structured_output(Schema)里写的每个str、int | None、list[Person],既是运行时校验规则,又是发给模型的 JSON Schema。
1. 为什么需要:一段没有说明书的代码
看一个入门风格的函数(对照 08-函数):
def analyze(result):
return {
"count": len(result),
"first": result[0] if result else None,
}
调用它前你要回答三个问题:result 是列表、字符串还是字典(len 对字典算 key 数)?result[0] 拿到什么?返回的 dict 有哪些 key?答案全在函数体里,唯一的办法是读实现。三行的函数还行;三千行、几十人协作的项目里,每个函数都要「考古」一次才能调用,维护成本灾难性地增长。三个月后的你自己,也是这群考古者之一。
类型注解(type hints)就是解法:把「数据长什么样」直接写在代码上——写给人和工具看的说明书,不是写给解释器执行的指令:
def analyze(result: list[str]) -> dict[str, int | str | None]:
return {
"count": len(result),
"first": result[0] if result else None,
}
一行签名回答了上面全部问题。注意函数体一行没改——注解不改变执行逻辑,这是本章要讲透的关键机制。
2. 注解长在哪:变量、函数、类属性
age: int = 18 # 变量:名字: 类型 = 值
name: str = "小明"
def make_greeting(name: str, times: int = 1) -> str: # 参数与返回值
return f"hello {name} " * times
class Student: # 类属性(对照 09-类和对象.md)
name: str
scores: list[float]
def __init__(self, name: str, scores: list[float]) -> None:
self.name = name
self.scores = scores
要点:
- 返回值写在
->后面;「什么都不返回」的函数(如__init__)注解-> None。 - 变量注解可以不赋值:
age: int是合法语句,只登记类型不创建变量——随后print(age)报NameError: name 'age' is not defined。它是纯粹的声明。 - 基础类型就是四个老朋友
int、float、str、bool。冷知识:bool是int的子类(isinstance(True, int)为True),所以注解int的地方传True工具不报错——历史包袱,知道即可。
机制:注解被存了起来。 def 执行时,Python 把所有注解求值一次,存进函数的 __annotations__ 字典:
def make_greeting(name: str, times: int = 1) -> str:
return f"hello {name} " * times
print(make_greeting.__annotations__)
# {'name': <class 'str'>, 'times': <class 'int'>, 'return': <class 'str'>}
注解是运行时真实存在的数据(就是类型对象本身),不是被丢掉的注释。这是伏笔:pydantic 之所以能按你的注解自动校验数据(21-pydantic数据建模),靠的正是能读到它们。平时没人读,它就安静躺着当说明书。
3. 容器与组合:描述有结构的数据
真实数据几乎都是容器。3.9+ 直接给内置类型加下标:
names: list[str] = ["小明", "小红"] # 元素全是 str
scores: dict[str, int] = {"小明": 90, "小红": 85} # key 是 str,value 是 int
point: tuple[int, str] = (1, "号位") # 定长两项,各是各的类型
tags: set[str] = {"python", "入门"}
读法统一:「外层类型[里面元素的类型]」。两个关键区分:
list[str]:一种元素类型,不管几个元素;dict[str, int]:所有 key 同型、所有 value 同型。tuple[int, str]是特例:定长、每个位置各自有类型,和列表正好相反。表达「不定长、元素都是 int 的元组」要写tuple[int, ...](三个点 = 任意长度)。
注解可以任意嵌套,精确描述真实形状——「每个学生一行、每行是姓名到分数的映射」:
grade_table: list[dict[str, float]] = [
{"小明": 90.5, "小红": 85.0},
{"小刚": 78.5},
]
def class_average(table: list[dict[str, float]]) -> float:
total, count = 0.0, 0
for row in table: # row 的类型:dict[str, float]
total += sum(row.values())
count += len(row)
return total / count
print(class_average(grade_table)) # → 84.66666666666667
编辑器里悬停 row 会显示 dict[str, float],输入 row. 自动补出字典方法——注解越精确,智能提示越强,这是「写给工具看」的直接收益。老代码里的 from typing import List, Dict 写作 List[int] 是 3.9 之前的唯一方式,读得懂即可,新代码用内置类型加下标。
4. 可选与联合:int | None 与 str | int
4.1 None 是一个真实的值
先纠正直觉:None 不是「没有值」的抽象概念,它是 NoneType 类的唯一实例,一个真实存在的对象(0 == None 是 False)。「可能没有」也是数据的合法状态,用 |(读作「或」)把多个类型并列:
def find_user(user_id: int) -> str | None:
users = {1: "小明"}
return users.get(user_id) # 找不到时 get 返回 None
str | None 读作「str 或 None」。工具的规矩:拿到它之后必须先用 if 收窄(narrowing)才能当 str 用:
name = find_user(2)
print(name.upper()) # 工具报错:None 没有 upper
if name is not None: # 收窄:这个分支里 name 一定是 str
print(name.upper()) # OK
「先 is not None 判空再使用」从此有了理论依据:不是风格洁癖,是把类型从 str | None 收窄成 str 的标准动作。同理有 int | str 等任意组合(联合类型,union)。
4.2 惯用法:默认值 None + 判空分支
真实代码里 | None 最高频的出场是「可选参数默认值为 None」:
def greet(name: str, title: str | None = None) -> str:
if title is None: # 调用方没传 → 给一个合理行为
return f"你好,{name}"
return f"你好,{title} {name}"
print(greet("小明")) # → 你好,小明
print(greet("小明", "博士")) # → 你好,博士 小明
为什么默认值是 None 不是 ""?「调用方没传」和「明确传了空字符串」是两种语义,None 是不与任何真实值冲突的哨兵。第 8 章见过的 def f(x=None) 加上注解后语义就完整了:x: str | None = None 同时说清「默认没有」和「有值时是什么」。
运行时冷知识:int | str 本身也是真实对象(types.UnionType 实例),甚至 isinstance(3, int | str) 返回 True——| 在运行时真的算了。
5. 关键真相:注解默认不校验,检查交给静态工具
5.1 反例:标了 int,传 str,照样跑
def double(x: int) -> int:
return x * 2
print(double("ab")) # 标注是 int,传 str —— 输出 "abab",没有任何报错
"ab" * 2 是合法操作(字符串重复),一路畅通。更阴险的是错误在离案发现场很远的地方才炸:
def greet(name: str) -> str:
return "hi " + name
greet(123)
# TypeError: can only concatenate str (not "int") to str
# 但报错指向函数体里的 +,而不是传错类型的调用处 greet(123)
greet(123) 这行本身不报错,炸的是 "hi " + 123。真实项目里调用处和崩溃处可能隔着几层函数、几个文件——你看到下游的 TypeError,得逆流而上找最初传错的源头。注解对此不做任何事:存进 __annotations__ 后,解释器看都不看一眼。
5.2 为什么这样设计
不是偷懒,是三个根本决定:
- 性能:每次调用逐参数检查类型,等于给全程序所有函数套一层看不见的包裹,热路径代价真实存在。CPython 选择「求值一次、存起来、不检查」。
- 渐进式采用:如果类型检查是强制的,加错一个注解程序就崩,任何老项目都无法逐步迁移。现在的设计允许一个函数一个函数地补注解,没注解的照常工作。
- 鸭子类型哲学:Python 的世界是「走起来像鸭子就是鸭子」。
double("ab")恰好合法就是证据——很多正确代码本来就依赖灵活的隐式行为,强制类型反而挡住合法写法。
所以注解的完整契约是:人用眼睛读,工具用分析查,解释器不执行。要让注解真正拦住 bug,需要「静态类型检查器」——只读代码文本、不运行程序、专门推断每个位置是什么类型有没有矛盾的工具。主流是 mypy 和 pyright(VS Code 的 Pylance 底层就是 pyright)。
5.3 跑一次 mypy
pip install mypy
把 5.1 的反例存成 checkme.py:
def double(x: int) -> int:
return x * 2
def greet(name: str) -> str:
return "hi " + name
print(double("ab")) # 传 str 给 int 参数
print(greet(123)) # 传 int 给 str 参数
运行 mypy checkme.py,真实输出:
checkme.py:7: error: Argument 1 to "double" has incompatible type "str"; expected "int" [arg-type]
checkme.py:8: error: Argument 1 to "greet" has incompatible type "int"; expected "str" [arg-type]
Found 2 errors in 1 file (checked 1 source file)
两处错误被精确报到行号——bug 在运行前、在造成破坏之前被拦下。工作流:平时靠编辑器里的 pyright 实时标红,提交前或 CI 里跑一次 mypy 兜底。
6. 进阶武器:Literal、Final、type 别名、Callable、TypedDict
6.1 Literal:值级别的类型
有时「类型」不足以表达约束——参数只允许三个字符串之一:
from typing import Literal
Mode = Literal["fast", "safe"] # 不是 str,是"这三个值之一"
def run(mode: Mode) -> None:
print(f"以 {mode} 模式运行")
run("fast") # OK
run("quick") # 是 str,但工具报错:不在 Literal 允许的值内
Literal 把约束下沉到具体的值(也能限定数字如 Literal[0, 1, 2]),mypy 对最后一行会报 Argument 1 to "run" has incompatible type "Literal['quick']"; expected "Literal['fast', 'safe']"。
6.2 Final:这个变量不再改
from typing import Final
MAX_RETRIES: Final[int] = 3 # 告诉人和工具:它是常量
MAX_RETRIES = 5 # 运行时赋值照常成功,但工具报错:
# mypy: Cannot assign to final name "MAX_RETRIES"
Final 是单方面的承诺(类比 tuple 之于 list),运行时不强制,工具负责抓违反承诺的代码。全大写命名是它的社交礼仪。
6.3 类型别名:给复杂类型起名字
list[dict[str, float]] 写三遍就该起名字。Python 3.12+ 用 type 语句:
type GradeTable = list[dict[str, float]] # 3.12+
def class_average(table: GradeTable) -> float:
...
type 语句创建 TypeAliasType 对象,右边的类型延迟到被使用时才求值(允许引用还没定义完的名字)。3.12 之前的旧写法是直接赋值 GradeTable = list[dict[str, float]],老代码里普遍是这种——它和普通变量无法区分,读代码时得靠猜;type 语句正是为消除这个歧义而生。
6.4 Callable:函数的类型
函数能当参数传(14-函数进阶:lambda、高阶函数与装饰器),被传的函数也有类型,用 Callable 描述——「参数类型列表 + 返回类型」:
from collections.abc import Callable
def is_long(s: str) -> bool:
return len(s) > 10
def count_match(words: list[str], check: Callable[[str], bool]) -> int:
return sum(1 for w in words if check(w)) # check(w) 返回 bool,可被检查
print(count_match(["short", "a-very-long-word"], is_long)) # → 1
Callable[[str], bool] 读法:方括号里的列表是参数类型(无参写 []),后面是返回类型。它也会出现在类的字段注解里(回调、策略),是读懂框架代码的必备词汇。
6.5 TypedDict:给 dict 画一张字段说明书
dict[str, int] 说「所有 value 都是 int」。但 JSON 风格的数据每个 key 类型不同:{"title": "三体", "year": 2008}——dict 注解表达不了这种形状,硬写只能退化成 dict[str, str | int],丢掉「哪个 key 是什么」的信息。TypedDict 补上这个洞:
from typing import TypedDict
class Book(TypedDict): # 语法像类,但描述的是 dict 的形状
title: str
year: int
book: Book = {"title": "三体", "year": 2008} # 构造出来的就是普通 dict
print(book["title"]) # → 三体,照常按 key 取值
dict[str, int] | Book(TypedDict) | |
|---|---|---|
| 描述能力 | 所有 value 同一种类型 | 每个 key 各自有类型,key 集合固定 |
| 运行时 | dict | 还是 dict,不创建新类 |
| 静态检查 | 只查 value 类型 | 查字段名、字段类型、缺字段 |
| 适用 | 同质集合、动态 key(计数表、映射表) | 固定字段的 JSON 形状(配置、API 载荷) |
注意「运行时还是 dict」这行:{"title": 123, "year": "x"} 构造和传参照样跑(mypy 会拦,运行时不拦)。TypedDict 是纯粹「写给工具看的 dict 说明书」。需要运行时真校验,用下一节的右两列。
6.6 泛型:TypeVar 与 PEP 695
读框架源码常见的最后一块拼图:Runnable[PromptValue, str] 这种「带参数的类型」——类型本身也可以有参数。老写法用 TypeVar(存量代码里大量存在,要认得):
from typing import TypeVar
T = TypeVar("T") # 声明一个类型变量:类型的占位符
def first(items: list[T]) -> T: # 进来什么类型,出去就是什么类型
return items[0]
n = first([1, 2, 3]) # T 被替换成 int,mypy 知道 n 是 int
3.12 起有了正式语法(PEP 695):方括号直接声明,不用再导入 TypeVar——
def first[T](items: list[T]) -> T: # 与上面等价的新写法
return items[0]
class Stack[T]: # 泛型类同理
def __init__(self) -> None:
self._items: list[T] = []
LangChain 里你主要扮演「读者」:Runnable[PromptValue, str] 读作「一个输入 PromptValue、输出 str 的可运行单元」,BaseChatMessageHistory 的泛型形态同理。新语法的约束/上界([T: (int, float)]、[T: float])见 最新Python语法手册 的类型注解节。
7. 四种描述数据的方式怎么选
「有结构的数据」至此有了四种写法,加上后两章的两种,一张表看清分工:
裸 dict | TypedDict | dataclass(15-面向对象进阶) | pydantic(21-pydantic数据建模) | |
|---|---|---|---|---|
| 本质 | 内置容器 | dict 的字段说明书 | 轻量数据类 | 第三方校验模型 |
| 取值方式 | book["title"] | book["title"] | book.title | book.title |
| 运行时校验 | 无 | 无(就是 dict) | 无(信任注解) | 有(构造即校验+转换) |
| 适用 | 临时、动态、同质数据 | 固定形状 JSON,给工具看 | 程序内部数据打包 | 边界处校验外部输入(LLM 输出、API) |
| 依赖 | 无 | 标准库 | 标准库 | pip install pydantic |
经验法则:数据从哪来,决定用哪张牌。程序内部产生、自己消费的数据,前三种够用(信任自己);从外部来的数据(用户输入、网络、LLM 输出)在边界那一刻不可信,用 pydantic 校验后再放行——LangChain 大量使用 pydantic 正因为模型输出是全程序最不可信的外部输入。
8. 常见坑
坑 1:以为写了注解就安全了
def shout(text: str) -> str:
return text.upper()
print(shout(123)) # 注解写着 str,这里传 int —— 运行直接炸:
# AttributeError: 'int' object has no attribute 'upper'
注解运行时不校验(第 5 节),bug 在 .upper() 那行以 AttributeError 的面目爆出。把注解当「写了就生效的保险」是最常见的误解——说明书要配上检查器才是合同。修法:装 mypy 或编辑器里的 pyright 插件,让传错类型在写代码时就被标红。
坑 2:可变默认值,注解救不了它
def add_item(item: str, items: list[str] = []) -> list[str]: # ❌ 经典陷阱
items.append(item)
return items
print(add_item("a")) # → ['a']
print(add_item("b")) # → ['a', 'b'] ← b 调用凭空拿到 a 留下的列表!
原因(第 8 章讲过):默认值在 def 执行时只创建一次,所有不传 items 的调用共享同一个列表。注意注解在这里毫无帮助——它只描述类型,不改变默认值的创建机制。修法是 4.2 节的 None 哨兵惯用法:
def add_item(item: str, items: list[str] | None = None) -> list[str]:
if items is None: # 每次调用都创建新列表
items = []
items.append(item)
return items
规矩:默认值永远用不可变对象(None、数字、字符串、元组),可变容器一律走 None 哨兵。Ruff 等代码检查工具(17-模块、包与项目工程化)会把可变默认值直接标为坏味道。
坑 3:把 | 写成 or
def parse(value: int or str) -> int: # ❌ 看起来像"int 或 str"
return int(value)
这行语法完全合法、运行不报任何错,所以格外危险。or 是布尔运算:int 类本身为真值,int or str 在运行时求值为 int(终端里打印 int or str 得到 <class 'int'>)——注解实际等于 value: int,str 被静默丢弃,工具检查结果整个是错的。修法:联合类型必须用管道符 |(3.10+),写 def parse(value: int | str) -> int:。记法:注解里「或」是 |;or 属于布尔表达式,两者毫无关系。
9. 在 LangChain 里的样子
本章的语法在 LangChain 里以 pydantic 的形态密集出现。摘编自 ../langchain-book-python/03-输出解析器.md:
from pydantic import BaseModel, Field
class AnswerWithConfidence(BaseModel):
answer: str = Field(description="用户问题的答案")
confidence: int = Field(description="问题答案的可信度评分,满分 100", ge=0, le=100)
逐行拆解注解在这里干了什么:
answer: str——普通注解,但 pydantic 会读它(正是 2 节__annotations__机制):构造实例时校验/转换 answer(数字字符串会自动转成对应类型,传对象则抛ValidationError);生成 JSON Schema 时变成"type": "string"。= Field(description=...)——这里的=不是默认值,Field(...)返回「字段配置对象」,description 原样写进发给模型的格式指令,约束模型「这个字段填什么」。说明书第一次有了第二读者:LLM。confidence: int = Field(..., ge=0, le=100)——注解int变成 Schema 的"type": "integer",ge=0, le=100变成"minimum": 0, "maximum": 100。模型返回95时下游直接拿到数字,无需转换;越界值在解析时抛错。
再摘编自 ../langchain-book-python/11-FunctionCalling.md,看第 3、4 节的惯用法如何在真实代码里组合:
from pydantic import BaseModel, Field
class Person(BaseModel):
"""提取关于一个人的信息"""
name: str = Field(description="人的名字")
age: int | None = Field(default=None, description="人的年龄")
class Relation(BaseModel):
people: list[Person] = Field(description="提取所有人")
relation: str = Field(description="人之间的关系, 尽量简洁")
age: int | None = Field(default=None, ...)——4.2 节「默认值 None」惯用法的实战形态,一举两得:运行时,文本没提年龄则字段是 None 而不是模型编造的数字(防幻觉);schema 生成时,带默认值的字段不进required,模型被允许干脆不输出它。people: list[Person]——3.1 节嵌套注解的进阶:容器里装的不是str而是另一个模型类,pydantic 递归校验列表里的每个Person。"""提取关于一个人的信息"""——docstring 也进 Schema 的 description,帮模型理解嵌套对象的整体语义。
本章主线的收束:注解在纯 Python 里是默认不生效的说明书,到了 pydantic 手里变成运行时真正执行的合同,同时还是发给模型的规格书——一份注解三处生效(人、校验器、LLM),这就是 LangChain 毫无保留地建立在类型注解之上的原因。第 21 章展开 pydantic,22-读懂LangChain:语法桥 做总串联。
小练习
练习 1:给下面的函数补全注解(参数、返回值都要)。
def word_lengths(words):
return {word: len(word) for word in words}
练习 2:写一个 top_student(scores),scores 形如 {"小明": [90, 85], "小红": [88, 92]},返回平均分最高的姓名;没有任何学生时返回 None。补全注解并处理好 | None 的收窄。
练习 3:一个 API 载荷长这样:{"query": "天气", "filters": ["fast"], "limit": 5},其中 filters 的元素只可能是 "fast"、"safe"。分别用 dict[...] 注解和 TypedDict + Literal 描述它,并说明哪种更好、为什么。
练习 4:找出下面代码里的三处问题(提示:两处让检查失真或产生运行时 bug,一处语义错误),并给出修正版。
def merge_tag(tag: str, tags: list[str] = []) -> list[str]:
tags.append(tag)
return tags
def to_int(value: int or str) -> int:
return int(value)
def shout(message: str) -> str:
return message + "!"
练习答案
练习 1:
def word_lengths(words: list[str]) -> dict[str, int]:
return {word: len(word) for word in words}
练习 2:
def top_student(scores: dict[str, list[int]]) -> str | None:
if not scores:
return None
best_name, best_avg = None, float("-inf")
for name, nums in scores.items():
avg = sum(nums) / len(nums)
if avg > best_avg:
best_name, best_avg = name, avg
return best_name
要点:返回类型 str | None;if not scores: return None 提前分支后,尾部 best_name 必有值,类型收窄为 str。
练习 3:
from typing import Literal, TypedDict
Filters = list[Literal["fast", "safe"]]
class SearchPayload(TypedDict):
query: str
filters: Filters
limit: int
dict[str, str | list[str] | int] 虽然合法,但丢掉了每个 key 的专属类型,filters 也收不住取值范围。TypedDict 固定了三个 key 及各自类型,Literal 把 filters 限定为两个值——连 {"filters": ["qucik"]} 这种拼写错误都能被工具拦下。固定形状 + 有限取值,TypedDict + Literal 完胜。
练习 4:① tags: list[str] = [] 可变默认值(坑 2),两次调用共享列表,改为 None 哨兵;② int or str 求值为 int,str 被静默丢弃(坑 3),应写 int | str;③ message + "!" 语义错误——函数叫 shout(喊出来)应该用 message.upper() + "!"。第 ③ 处提醒你:注解再齐全也只查形状不查语义。修正版:
def merge_tag(tag: str, tags: list[str] | None = None) -> list[str]:
if tags is None:
tags = []
tags.append(tag)
return tags
def to_int(value: int | str) -> int:
return int(value)
def shout(message: str) -> str:
return message.upper() + "!"