跳转到主要内容

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.102021-10结构化模式匹配 match/case、X | Y 联合类型、更友好的报错
3.112022-10asyncio.TaskGroup、except* 异常组、Self 类型、tomllib、提速 10%~60%
3.122023-10泛型新语法 def f[T](x: T)、type 别名语句、f-string 可复用引号、@override
3.132024-10free-threaded 无 GIL 构建(实验)、JIT(实验)、新交互式 REPL、TypeIs
3.142025-10t-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.interpreters3.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 迁移:惯用法对照

JavaScriptPython说明
const x = 1 / let x = 1x = 1无声明关键字;变量随作用域自然存在
null / undefinedNone只有一个空值
=====(引用比较用 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.forEachfor x in arr:
`${x}`f"{x}"
obj?.a?.bobj.get("a", {}).get("b")或 `dict
try/catch + Promise.allasyncio.TaskGroup结构化并发,错误自动传播
export / import模块即文件,import / from x import y无 default export;__all__ 控制星号导入
Array.isArray(x)isinstance(x, list)
JSON.stringify/parsejson.dumps / json.loads
Promise<void> 返回-> NonePython 注解只描述类型,不构成异步
顶层 await❌ 没有异步必须跑在事件循环里(asyncio.run)
process.env.Xos.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=)、dataclass slots/kw_only —— 3.10
  • TaskGroup、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