modern-python

name	modern-python
description	现代 Python 编程专家技能（Modern Python），覆盖 Python 3.10–3.14 的类型系统、数据类、模式匹配、函数式编程、测试、性能优化、科学计算与工程架构。当用户需要编写、审查、调试或优化 Python 代码，或问及 Python 特性（类型注解/PEP 695、dataclass、装饰器、生成器、上下文管理器、`match` 语句、面向对象设计、numpy/scipy/pandas/matplotlib、属性测试、性能调优、打包发布、项目架构）时使用。触发词包括：Python 代码、写/改/查 Python、类型提示、dataclass、装饰器、生成器、函数式 Python、Hypothesis、numpy 广播、性能优化、Python 项目结构等，即使没有明确说"Python"也一样触发。

Modern Python 编程技能

覆盖 Python 3.10–3.14 的现代工程化 Python 编程。本技能的内容沉淀自《科学计算 Python：苏黎世大学暑期学校中译版》（ch02–ch15），涵盖：面向对象设计、测试/调试/性能分析、数据结构与 NumPy/Pandas、SciPy 科学分析、硬件加速、标准库生态与打包、可视化、高级语言机制、函数式编程（类型代数/幺半群/属性测试）、解释器实现、项目架构。

Skill Architecture

渐进披露：按需读取 reference 文件。

领域	Reference 文件	主题
面向对象编程	reference/ch02_面向对象编程.md	类与实例、继承/组合、魔术方法、@property、dataclass、MRO、鸭子类型、ABC
测试调试性能	reference/ch03_测试调试与性能分析.md	pytest、断言、fixture、覆盖率、pdb、cProfile、大 O 分析、先测量再优化
数据管理	reference/ch04_Pandas与Jupyter生态.md	Jupyter、Series/DataFrame、I/O、groupby、merge、时间序列、索引对齐
数据结构	reference/ch05_数据结构.md	NumPy ndarray 底层结构、strides、广播规则、视图/拷贝、序列化(pickle/JSON/protobuf)、SQL
科学分析	reference/ch06_科学分析.md	求根(二分/牛顿/Brent)、优化(Nelder-Mead/BFGS)、MLE、线性代数、数值积分/微分、FFT
硬件加速	reference/ch07_硬件加速技术.md	存储层次、缓存、向量化(SIMD)、numexpr、numba、BLAS、Horner、测量方法学
标准库与打包	reference/ch08_不重造轮子.md	itertools/functools/collections/pathlib/typing/argparse、pyproject、PyPI 发布
可视化	reference/ch09_数据可视化.md	Matplotlib Figure/Axes、子图、图型选型、colormap、误差条、直方图 bin 规则
高级机制	reference/ch10_高级Python概念.md	装饰器、生成器、上下文管理器、闭包/LEGB、元类、描述符、__slots__、map/filter/reduce、async、match
函数式·类型代数	reference/ch11_函数式PythonI_类型与代数.md	渐进类型、积类型/和类型(ADT)、递归类型、结构化模式匹配、foldr
函数式·幺半群	reference/ch12_函数式PythonII_幺半群.md	ABC 模拟类型类、幺半群/半群、CPS、thunk、蹦床、栈安全 foldr、协变递归协议
函数式·属性测试	reference/ch13_函数式PythonIII_属性测试.md	属性测试、Hypothesis 策略、收缩、幺半群性质、契约设计(前置/后置/不变量)、CrossHair
解释器	reference/ch14_实现一个解释器.md	词法/语法分析、环境模型、eval/apply、词法作用域、闭包、尾调用、宏
架构	reference/ch15_项目架构与工程化.md	分层、依赖倒置、端口与适配器、依赖注入、纯核心命令外壳、架构测试、CI 门禁

Core Philosophy

面对任何 Python 任务，记住这几条原则：

用类型替你把关正确性

Python 是动态类型，但渐进类型（PEP 484 + mypy/Pyright/Pyre/pytype）让你能零散地、无全有或全无负担地加注解。类型注解是"标准化文档"，也是静态检查器抓 bug 的依据。尽可能为公共 API 标注类型，用 PEP 695 类型参数写泛型。

优先用可验证的正确性手段

测试（pytest、单元测试、基于属性的 Hypothesis）与静态检查是正确性的第一道防线。先测量再优化——不要凭直觉优化热点，用 cProfile/timeit 找出真正的瓶颈。

组合优于继承，抽象优于重复

面向对象不是语法糖：DRY（不重复自己）与 KIS（保持简单）。能用标准库就不要重造轮子（itertools、functools、collections、dataclasses）。能用函数组合解决的问题，不要硬造类层级。

理解数据在机器里怎么流动

性能瓶颈往往是内存带宽而非计算。理解 ndarray 的 strides/内存布局、缓存局部性、广播、视图与拷贝，才能写出"快 100 倍"的向量化代码。

Working with Python Code

写 Python 代码时

1. 确定目标版本：新项目默认用项目环境允许的最新 Python（本环境有 3.12 与 3.14）。3.10+ 才能用 match 与 | 联合类型；3.12+ 才用 PEP 695 类型参数；from __future__ import annotations 在 3.12 上做自引用前向注解仍必要（3.14 起 PEP 649 延迟求值成为默认）。

2. 优先现代写法：

   • 类型注解：def f(x: float) -> float；泛型用 PEP 695（class Box[T]:、def first[S, T](...)）
   • 数据容器：dataclass(frozen=True, slots=True) 优先于手写类与 namedtuple；需要结构共享时用 frozen=True
   • 联合类型用 |（int | None）而非 Optional；内建泛型（list[int]）而非 typing.List
   • 模式匹配 match/case（PEP 634）替代冗长的 if/elif 解构
   • 遍历用 enumerate/zip；列表理解优于 map/filter + lambda；需要惰性时用生成器表达式
   • 文件读写用 pathlib.Path；资源管理用 with + 上下文管理器

3. 面向对象纪律：

   • 用 dataclass 表示值对象；用 ABC（abc.ABC + @abstractmethod）声明接口
   • 继承表达 is-a，组合表达 has-a；能互换就继承，否则组合
   • 依赖倒置：依赖抽象（ABC/Protocol）而非具体类；用 Protocol 描述结构化接口
   • 熟悉魔术方法与 @property、@classmethod/@staticmethod 的语义差异

4. 错误处理：用异常而非返回码；raise ... from 保留异常链；try/except/else/finally 各司其职；尽早失败（fail fast）。

5. 性能意识：科学计算优先 NumPy 向量化（广播、切片、聚合），避免 Python 层循环；需要极致性能用 numba @njit 或 numexpr；理解 BLAS 在 np.linalg/scipy.linalg 背后的作用。

审查 Python 代码时

检查：

• 类型注解是否覆盖公共 API；泛型是否用对了 PEP 695
• 是否有裸 except:、吞掉的异常、丢失的异常链
• 可变默认参数（def f(x=[])）、共享可变状态、意外的别名（b = a 然后修改 b）
• 广播/shape 错误、视图 vs 拷贝的意外（a.view() vs a.copy()）
• 循环里不必要的分配、Python 层逐元素运算（应向量化）
• 是否重复造轮子（已有标准库/成熟库实现）
• 测试覆盖是否只测"精选样例"而没测性质
• f-string 与格式化、{{/{% 在 Jinja 场景的转义
• 大 O 复杂度是否随输入规模失控

调试 Python 代码时

1. 复现 → 二分隔离 → 最小化（git bisect 是 O(log n) 定位回归的利器）
2. traceback 自下而上读：最底帧是异常发生处
3. print 用于快速试探，logging 用于长期，pdb/IDE 断点用于难缠 bug
4. 用 cProfile + pstats 找热点；用 %timeit（IPython）做微基准
5. 属性测试（Hypothesis）能自动找到手工想不到的反例

优化 Python 代码时

1. 先测量：profile 找热点，不要猜。
2. 算法层：改复杂度（O(n²)→O(n)）通常收益最大。
3. 向量化：Python 循环 → NumPy 向量运算（广播/聚合/ufunc），常得 ~100 倍。
4. 减少中间物：Horner 因式分解减少运算与中间数组；numexpr 按块求值免临时数组。
5. 编译：numba JIT、Cython；理解 JIT 首次编译开销。
6. 数据布局：C-order vs F-order；缓存局部性；合并连续访问。
7. 并行：多进程受限于 GIL 与内存带宽，先确认瓶颈是 CPU 还是带宽。

Python 版本速查

• 3.8：functools.cached_property、positional-only 参数 /、walrus :=
• 3.9：内建泛型（list[int]）、dict 合并 |
• 3.10：match/case（PEP 634）、| 联合类型、括号化上下文管理器
• 3.11：Self 类型、except*、tomllib、异常组
• 3.12：PEP 695 类型参数（class T/def f[T]）、type 语句、functools.partialmethod 增强
• 3.13：自由线程（no-GIL）试验、random 加速
• 3.14：PEP 649 注解延迟求值默认化（from __future__ import annotations 不再必要）、PEP 758 延迟 except 求值

常用模式速查

dataclass vs namedtuple vs 手写类

只是"具名字段的值"？             → @dataclass(frozen=True, slots=True)
需要类行为（方法/校验/继承体系）  → 普通类
追求元组解构与哈希且无方法        → namedtuple（但注意不能多重继承）

类型类/接口（Haskell typeclass 的 Python 等价）

多个无关类共享能力、需要单注解覆盖 → ABC（abc.ABC + @abstractmethod）
只关心结构、不关心继承             → typing.Protocol
一个类型是多个"能力"的组合         → 继承多个 ABC

联合类型 vs 积/和类型

"可能是 A 或 B"（一次一个）      → 和类型：Enum / 类层级 + @final / int | str
"同时是 A 和 B"（所有分量）      → 积类型：dataclass / tuple / dict

递归的栈安全

朴素递归可能爆栈（默认上限 1000） → 改写为循环 + 累加器（左折叠）
必须右折叠/尾递归                 → CPS + thunk + trampoline 实现 TCO

幺半群识别

看到"可结合 + 有单位元"的运算（加法、字符串拼接、列表拼接、OR/AND、min/max、矩阵乘法）→ 它就是幺半群，可抽象出 mempty/mappend/mconcat 接口，测试其结合律与单位元。

When to Read Reference Files

• 写类/继承体系/数据类 → reference/ch02_面向对象编程.md
• 写测试或调 bug / 分析性能 → reference/ch03_测试调试与性能分析.md
• 处理表格数据 / DataFrame → reference/ch04_Pandas与Jupyter生态.md
• 数组运算 / 广播 / 序列化 → reference/ch05_数据结构.md
• 数值算法（求根/优化/积分/FFT） → reference/ch06_科学分析.md
• 代码太慢 / 向量化 / numba → reference/ch07_硬件加速技术.md
• 用标准库 / 打包发布 → reference/ch08_不重造轮子.md
• 画图 / 可视化设计 → reference/ch09_数据可视化.md
• 装饰器 / 生成器 / 高级语法 → reference/ch10_高级Python概念.md
• 类型代数 / ADT / 模式匹配 → reference/ch11_函数式PythonI_类型与代数.md
• 幺半群 / 栈安全递归 → reference/ch12_函数式PythonII_幺半群.md
• 属性测试 / Hypothesis → reference/ch13_函数式PythonIII_属性测试.md
• 解析器 / 求值器 / 语言实现 → reference/ch14_实现一个解释器.md
• 项目分层 / 依赖注入 / CI → reference/ch15_项目架构与工程化.md