Python
最新 Python 语法手册(覆盖 Python 3.10 – 3.14)
覆盖 Python 3.10–3.14 新语法的速查表,示例全部实测,各节附「配套深讲」指向课程章节
- Python
- 速查
面向已会编程、想快速掌握现代 Python 写法的开发者。与本仓库配套使用:系统课程见本目录 01–22 章(各节末尾有「配套深讲」指引),LangChain 侧见 docs/ 使用文档与两本 LangChain Python 书。每个新特性都标注引入版本;未标注的即为 longstanding 语法。当前稳定版为 Python 3.14(2025-10 发布)。
0. 版本速览
| 版本 | 发布 | 关键特性 |
|---|---|---|
| 3.10 | 2021-10 | 结构化模式匹配 match/case、X | Y 联合类型、更友好的报错 |
| 3.11 | 2022-10 | asyncio.TaskGroup、except* 异常组、Self 类型、tomllib、提速 10%~60% |
| 3.12 | 2023-10 | 泛型新语法 def f[T](x: T)、type 别名语句、f-string 可复用引号、@override |
| 3.13 | 2024-10 | free-threaded 无 GIL 构建(实验)、JIT(实验)、新交互式 REPL、TypeIs |
| 3.14 | 2025-10 | t-string 模板字符串、注解延迟求值、子解释器 concurrent.interpreters、free-threading 官方支持(PEP 779)、except A, B: 简写、compression.zstd |
安装与运行(2026 年推荐工具链):
# 用 uv 管理版本与依赖(也可用系统 python3 + venv)
uv python install 3.14
uv init myapp && cd myapp
uv add requests # ≈ pip install + 锁定
# 传统方式
python3 -m venv .venv && source .venv/bin/activate
pip install requests
# 脚本入口惯用法
from pathlib import Path
def main() -> None:
data_dir = Path(__file__).parent / "data" # 不要手拼字符串路径
print(data_dir.resolve())
if __name__ == "__main__":
main()
1. 类型注解:现代写法
老式 typing.Optional[str]、typing.List[int] 已过时,现代写法直接用内置语法:
# 联合类型:X | Y(3.10+,取代 Union[X, Y])
def find_user(uid: int) -> dict | None: ...
# 内置容器泛型(3.9+)
def top_k(items: list[str], k: int = 5) -> list[tuple[str, float]]: ...
# 可调用与泛型映射
from collections.abc import Callable, Sequence
handler: Callable[[str], bool]
scores: dict[str, float] = {}
# 类型别名:type 语句(3.12+,取代 TypeAlias)
type Vector = list[float]
type Callback = Callable[[str], None]
# 泛型函数:方括号声明类型参数(3.12+,PEP 695,取代 TypeVar("T"))
def first[T](items: list[T]) -> T:
return items[0]
# 泛型类(3.12+)
class Stack[T]:
def __init__(self) -> None:
self._items: list[T] = []
def push(self, item: T) -> None:
self._items.append(item)
def pop(self) -> T:
return self._items.pop()
# 带约束/上界的类型参数(3.12+)
def total[T: (int, float)](xs: list[T]) -> T: ... # 约束
def double[T: float](x: T) -> T: return x * 2 # 上界
常用进阶标注:
from typing import Literal, TypedDict, ClassVar, Final
# 字面量类型:配合 match 或分支收窄
Mode = Literal["fast", "safe"]
# 结构化字典类型(TypedDict)
class UserInfo(TypedDict, total=False): # total=False → 所有键可选
name: str
age: int
# 常量与类变量
MAX_SIZE: Final[int] = 100
class Config:
debug: ClassVar[bool] = False # 类属性,不属于实例
# 3.11+:Self —— 返回自身类型(链式调用、子类安全)
from typing import Self
class Builder:
def set_name(self, name: str) -> Self:
self.name = name
return self
# 3.12+:@override —— 显式标记覆写,父类改名时静态检查器报警
from typing import override
class Sub(Builder):
@override
def set_name(self, name: str) -> Self: ...
# 3.13+:TypeIs —— 自定义类型收窄函数
from typing import TypeIs
def is_str_list(xs: list[object]) -> TypeIs[list[str]]:
return all(isinstance(x, str) for x in xs)
注解运行时取舍:注解默认不参与运行时校验;需要校验用 pydantic(本仓库两本书的工具 schema 全用它)。
配套深讲:注解从语法到 mypy 实操见 13-类型注解实战(含泛型 TypeVar 与 PEP 695);「注解变合同」的运行时校验见 21-pydantic数据建模。
2. 字符串:f-string 与 t-string
name, score = "Tom", 92.5
# f-string(3.12 起可嵌套同类引号、可换行、可复用)
print(f"{name}: {score:.1f}")
print(f"{f"{name=}".strip()}") # 3.12+:内外都用双引号也合法
# 调试写法:= 自动带上「变量名=值」(3.8+)
print(f"{score=:.1f}") # 输出 score=92.5
# 多行模板
msg = f"""
你好 {name},
本次得分 {score:.1f}。
""".strip()
t-string 模板字符串(3.14+,PEP 750):t 前缀返回 Template 对象而非 str,把「静态部分」和「插值」分开,交给渲染函数决定如何安全拼接——用于 SQL、HTML、日志等需要转义/参数化的场景:
from string.templatelib import Interpolation
template = t"SELECT * FROM users WHERE name = {name}" # 不是 str!
def render_sql(template) -> str:
parts = []
for part in template: # 依次产出 str 与 Interpolation
if isinstance(part, Interpolation):
parts.append("?") # 插值走参数绑定,杜绝注入
else:
parts.append(part)
return "".join(parts)
# str(template) 不存在——必须显式渲染,这是它安全的根源
3. 数据结构与推导式
# 解包与合并
first, *rest = [1, 2, 3, 4]
merged = {**defaults, **overrides}
merged2 = defaults | overrides # 字典合并运算符(3.9+)
# 海象运算符 := :赋值的同时用作表达式(3.8+)
if (n := len(data)) > 100:
print(f"too large: {n}")
# 推导式(3.12 起内联优化,更快)
squares = [x * x for x in range(10) if x % 2 == 0]
lookup = {user["id"]: user for user in users}
unique = {word.lower() for word in words}
# zip(strict=):长度不一致时报错而不是静默截断(3.10+)
for name, score in zip(names, scores, strict=True): ...
# itertools.pairwise(3.10+):相邻对
from itertools import pairwise
for a, b in pairwise([1, 4, 9]):
assert b > a
# StrEnum(3.11+):成员就是 str
from enum import StrEnum, auto
class Color(StrEnum):
RED = auto() # "red"
enum 与 Literal 的分工:Literal 在类型注解里锁死取值集合(13 章/21 章大量使用),零运行时成本;enum 是真正的类——成员可迭代、可挂方法、可做字典键,配置项与状态机用它。
配套深讲:推导式的入门讲解在 08-函数 §6,「惰性兄弟」生成器表达式在 16-迭代器与生成器 §5。
4. 控制流与结构化模式匹配
match/case(3.10+)比 JS 的 switch 强得多——按结构解构匹配:
def handle(cmd: dict) -> str:
match cmd:
case {"action": "move", "dx": dx, "dy": dy}: # 字典模式
return f"move {dx},{dy}"
case {"action": "resize", "size": [w, h]}: # 嵌套序列模式
return f"resize {w}x{h}"
case {"action": "color", "value": str() as c}: # 类型 + 捕获
return f"color {c}"
case {"action": "quit" | "exit"}: # 或模式
return "bye"
case {"action": unknown}: # 通配捕获
return f"unknown action: {unknown}"
case _: # 兜底
raise ValueError(cmd)
# 类模式 + 位置/关键字属性
class Point:
def __init__(self, x, y): self.x, self.y = x, y
match p:
case Point(x=0, y=0): print("origin")
case Point(x=0): print("on y-axis")
case Point(): print("somewhere")
# 序列解包 + 守卫(if 后缀)
match event:
case [start, end] if end > start:
process(start, end)
5. 异常处理
# 精确捕获多个异常(3.14 起 as 可省时不需要括号)
try:
fetch(url)
except (TimeoutError, ConnectionRefusedError): # 传统写法
retry()
except TimeoutError, ConnectionRefusedError: # 3.14+ 简写(无 as)
retry()
# 异常添加备注(3.11+)——报错链路更有用
try:
process(order)
except ValueError as e:
e.add_note(f"order_id={order.id}") # 会附加在 traceback 后
raise
# 空上下文 re-raise vs 带原因
try:
json.loads(raw)
except json.JSONDecodeError as e:
raise DataError("payload damaged") from e # 显式因果链
# 3.14+:return/break/continue 跳出 finally 会触发 SyntaxWarning —— 别这么写
except*(3.11+)捕获异常组:TaskGroup 并发失败时抛出的不是单个异常而是一个 ExceptionGroup,except* 按类逐组拆包(概念与用法见 20-异步编程入门):
try:
async with asyncio.TaskGroup() as tg:
tg.create_task(fetch("a"))
tg.create_task(fetch("b"))
except* TimeoutError as eg: # eg 是 ExceptionGroup,装着该类全部异常
for exc in eg.exceptions:
print("超时:", exc)
except* ValueError as eg:
print("值错误", len(eg.exceptions), "个")
配套深讲:异常树、traceback 精读、try 五部件与 pytest 见 18-异常处理、调试与测试。
6. 函数
# 参数语法的完整形态:/ 之前仅位置,* 之后仅关键字
def create(name: str, /, *, timeout: float = 1.0, **kwargs): ...
create("job") # OK
create(name="job") # TypeError:name 仅位置
# *args / **kwargs 带类型(3.12+ 可用新泛型语法声明)
def log(*args: object, **kwargs: object) -> None: ...
# 默认值陷阱:可变默认值是共享的 → 用 None 哨兵
def append_to(item: str, target: list[str] | None = None) -> list[str]:
target = target if target is not None else []
target.append(item)
return target
# 装饰器:functools.wraps 保住元信息
from functools import wraps
def timed[F, **P](fn: Callable[P, F]) -> Callable[P, F]: # 3.12+ ParamSpec 新写法
@wraps(fn)
def inner(*args: P.args, **kwargs: P.kwargs) -> F:
t0 = time.perf_counter()
try:
return fn(*args, **kwargs)
finally:
print(f"{fn.__name__}: {time.perf_counter() - t0:.3f}s")
return inner
# lambda 只用于单表达式;复杂逻辑写 def
key_fn = lambda kv: (kv[1], kv[0])
配套深讲:装饰器的完整推导(@wraps、带参三层、lru_cache/partial)见 14-函数进阶:lambda、高阶函数与装饰器。
7. 类与数据建模
from dataclasses import dataclass, field
# dataclass:自动生成 __init__/__repr__/__eq__
@dataclass(slots=True, kw_only=True) # slots=True(3.10+)省内存;kw_only 全关键字
class Article:
title: str
tags: list[str] = field(default_factory=list)
score: float = 0.0
# 不可变数据 → frozen=True;排序支持 → order=True
@dataclass(frozen=True, order=True)
class Version:
major: int
minor: int
# property / slots / classmethod 常规形态
class Temp:
__slots__ = ("celsius",)
def __init__(self, celsius: float): self.celsius = celsius
@property
def fahrenheit(self) -> float:
return self.celsius * 9 / 5 + 32
@classmethod
def from_f(cls, f: float) -> "Temp":
return cls((f - 32) * 5 / 9)
# 结构化子类型:Protocol(鸭子类型的静态版)
from typing import Protocol
class Retrievable(Protocol):
def invoke(self, query: str) -> list[str]: ...
def search(r: Retrievable, q: str) -> str: ... # 任何有该方法的类都满足,无需继承
# 抽象基类(需要继承并强制实现时)
from abc import ABC, abstractmethod
class Storage(ABC):
@abstractmethod
def save(self, key: str, value: bytes) -> None: ...
配套深讲:魔术方法、@property/@classmethod、dataclass 机制见 15-面向对象进阶;dataclass 与 pydantic 的分工见 21-pydantic数据建模。
8. 异步编程(asyncio)
import asyncio
async def fetch_one(url: str) -> str:
await asyncio.sleep(0.1) # 模拟 IO
return f"data:{url}"
# TaskGroup(3.11+):结构化并发,子任务异常自动取消兄弟任务
async def fetch_all(urls: list[str]) -> list[str]:
async with asyncio.TaskGroup() as tg:
tasks = [tg.create_task(fetch_one(u)) for u in urls]
return [t.result() for t in tasks]
async def main() -> None:
results = await fetch_all(["a", "b", "c"])
print(results)
asyncio.run(main()) # 入口处调用一次
# 异步迭代与异步推导式
async for chunk in stream: ...
chunks = [c async for c in stream]
# 超时控制(3.11+)
async with asyncio.timeout(2.0):
await slow_call()
诊断工具(3.14+):python -m asyncio ps <PID> / pstree <PID> 可实时查看运行中进程的任务树。
配套深讲:async/await 的直觉模型、事件循环、async for / async with 见 20-异步编程入门。
9. 并行的三个新选项(概念速览)
| 机制 | 版本 | 适用 |
|---|---|---|
concurrent.futures.ProcessPoolExecutor | 老版本 | CPU 密集,进程级并行 |
子解释器 concurrent.interpreters | 3.14+ | 每 interpreter 独立 GIL,真多核;数据共享受限(主要 memoryview) |
| free-threaded 构建(无 GIL) | 3.13 实验 / 3.14 官方支持(PEP 779) | 需单独安装(python3.14t),单线程有 ~5–10% 开销 |
# 3.14+ 子解释器(用模块级工厂函数 create() 创建)
from concurrent.interpreters import create
interp = create()
interp.exec("import math; print(math.pi)")
# 3.14+ 线程池版
from concurrent.futures import InterpreterPoolExecutor
with InterpreterPoolExecutor(max_workers=4) as pool:
results = list(pool.map(heavy_fn, data))
10. 注解的延迟求值(3.14,PEP 649/749)
3.14 起函数/类/模块的注解默认惰性求值:定义时不再执行注解表达式,前向引用不再需要加引号。
# 旧写法(3.13 及以前)
class Node:
def next(self) -> "Node | None": ... # 必须引号
# 3.14+:直接写
class Node:
def next(self) -> Node | None: ... # 无引号也 OK
# 用 annotationlib 按需取注解
from annotationlib import get_annotations, Format
get_annotations(func, format=Format.VALUE) # 真实求值(可能抛 NameError)
get_annotations(func, format=Format.STRING) # 字符串形式
这对 pydantic / LangChain 这类运行时读注解的库是利好:前向引用噪音大幅减少。
11. 标准库新工具速查
# tomllib(3.11+):读 TOML(pyproject.toml)
import tomllib
with open("pyproject.toml", "rb") as f:
config = tomllib.load(f)
# zoneinfo(3.9+):时区就用标准库,别用 utcnow()
from datetime import datetime, timezone
now = datetime.now(timezone.utc) # ✅ 带时区
# datetime.utcnow() 已弃用(3.12+),勿用
# pathlib(3.14+ 新增 copy/move)
from pathlib import Path
Path("a.txt").copy("b.txt")
Path("tmp.log").move("archive/")
# compression.zstd(3.14+,PEP 784)与统一入口
from compression import zstd
blob = zstd.compress(data)
# sys.remote_exec(3.14+):免重启附加调试器
# python -m pdb -p <PID>
# match 的穷尽性检查辅助(3.11+)
from typing import assert_never
def color_len(c: Color) -> int:
match c:
case Color.RED: return 3
case _: assert_never(c) # 漏分支时静态检查器报警
12. 从 JavaScript 迁移:惯用法对照
| JavaScript | Python | 说明 |
|---|---|---|
const x = 1 / let x = 1 | x = 1 | 无声明关键字;变量随作用域自然存在 |
null / undefined | None | 只有一个空值 |
=== | ==(引用比较用 is) | Python 默认就是值语义比较;is 仅用于 None/单例 |
arr.map(fn) | [fn(x) for x in arr] | 推导式;map() 返回迭代器 |
arr.filter(fn) | [x for x in arr if fn(x)] | |
arr.forEach | for x in arr: | |
`${x}` | f"{x}" | |
obj?.a?.b | obj.get("a", {}).get("b") | 或 `dict |
try/catch + Promise.all | asyncio.TaskGroup | 结构化并发,错误自动传播 |
export / import | 模块即文件,import / from x import y | 无 default export;__all__ 控制星号导入 |
Array.isArray(x) | isinstance(x, list) | |
JSON.stringify/parse | json.dumps / json.loads | |
Promise<void> 返回 | -> None | Python 注解只描述类型,不构成异步 |
顶层 await | ❌ 没有 | 异步必须跑在事件循环里(asyncio.run) |
process.env.X | os.environ["X"] / os.getenv("X") |
13. 版本门槛与兼容写法
# 运行时判断版本
import sys
if sys.version_info >= (3, 12):
from typing import override # 3.12+
else:
def override(f): return f # 降级为 no-op
# pyproject.toml 声明下限
# requires-python = ">=3.12"
# 弃用趋势速记
# - typing.Optional/List/Union/TypeAlias → | / 内置泛型 / type 语句
# - datetime.utcnow() → datetime.now(timezone.utc)
# - distutils(3.12 移除)→ setuptools / packaging
# - asyncio 隐式事件循环 API(get_event_loop 等)→ asyncio.run / 显式 loop
一页速记(最低版本)
X | Y、match/case、zip(strict=)、dataclassslots/kw_only—— 3.10TaskGroup、except*、Self、tomllib、StrEnum、assert_never—— 3.11- 泛型语法
def f[T]、type别名、f-string 嵌套引号、@override—— 3.12 TypeIs、ReadOnly、free-threaded/JIT 实验构建、新 REPL —— 3.13- t-string、注解延迟求值(免引号前向引用)、
concurrent.interpreters、except A, B:、compression.zstd、pathlib.copy/move—— 3.14