跳转到主要内容

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 为什么这样设计

不是偷懒,是三个根本决定:

  1. 性能:每次调用逐参数检查类型,等于给全程序所有函数套一层看不见的包裹,热路径代价真实存在。CPython 选择「求值一次、存起来、不检查」。
  2. 渐进式采用:如果类型检查是强制的,加错一个注解程序就崩,任何老项目都无法逐步迁移。现在的设计允许一个函数一个函数地补注解,没注解的照常工作。
  3. 鸭子类型哲学: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. 四种描述数据的方式怎么选

「有结构的数据」至此有了四种写法,加上后两章的两种,一张表看清分工:

裸 dictTypedDictdataclass(15-面向对象进阶)pydantic(21-pydantic数据建模)
本质内置容器dict 的字段说明书轻量数据类第三方校验模型
取值方式book["title"]book["title"]book.titlebook.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() + "!"