来源书籍

Python Cookbook(第3版)中文版

Skill 版本:v23 工程实践(高浓度 + 低稳定性) 476 张卡片

本书每个主题都按“问题、解决方案、讨论”组织,不只是罗列 API,还会解释方案为什么能工作,例如数据结构章节会比较 heapq 与全量排序的适用条件,迭代器章节围绕迭代协议、生成器和管道组织数据流,并发章节讨论线程通信、死锁、GIL 与 Actor 模式。这些内容信息浓度较高,能迁移到日常工程判断中。稳定性方面,它又强绑定 Python 3.3 时代的标准库、语法和第三方库用法,部分建议会随语言版本演进而变化,因此整体落在“工程实践”,不是纯经典原理。

David Beazley、Brian K. Jones · 陈舸 译 · 人民邮电出版社 · 2015-05-01 · 第3版中文版 · ISBN 978-7-115-37959-7

全书导读

本书面向已有Python基础的开发者,以具体问题串起数据处理、语言协议和系统边界。每条配方给出一个可理解的起点,再解释为何能这样做。阅读时要同时看“它解决什么问题”和“它依赖什么前提”:能运行的演示、适合生产的接口和跨版本仍成立的机制并不等同。

本版以Python3.3为主要背景。容器、迭代协议、封装和资源所有权等思想仍能帮助理解现代程序,但旧导入钩子、打包方式、Unicode接口以及网络加密示例已有版本变化。本笔记保留原版出处,在具体解释中区分稳定机制、示例遗漏和版本限制,不承诺旧代码可以原样执行。

按需查问题时,可先读对应条目的概念和边界;系统阅读时,先掌握前六章的数据表示与流式处理,再读函数、对象、元编程与模块,最后进入网络、并发、脚本、测试和C扩展。附录给出查证路径,封面自然史另列,不与软件机制强行建立类比。

全书主线

全书反复处理同一类边界:数据在不同表示之间转换,行为通过协议组合,资源在不同所有者之间流转。先选对对象和数据形状,再决定何时计算、谁保留状态、哪里验证与清理,具体API才能形成可靠方案。

容器和文本章节关注值的组织与含义;迭代章节把一次性结果改为按需推进的过程。文件和编码把这个过程接到外部字节,序列化则给字节与结构赋予约定。函数、描述符和元类分别在调用、属性访问和类创建阶段复用规则;模块决定这些规则如何命名和加载。网络与并发加入部分完成、等待和失败,测试提供观察这些边界的手段,C扩展则把类型、寿命和失败协议变成必须手工兑现的责任。

flowchart TD
A[值与数据形状] --> B[按需处理与表示转换]
B --> C[函数和对象协议]
C --> D[加载与外部接口]
D --> E[网络及并发的等待和失败]
E --> F[测试与诊断证据]
B --> G[C边界的布局与所有权]
F --> G

图表示理解上的依赖关系,不表示每个程序都按这条固定流水线执行。

前言

本书以Python 3.3为写作与验证背景,面向已掌握基础的开发者,用具体问题和方案带入更深入的语言与标准库机制。示例往往只是起步框架,使用前还要补齐环境、输入和错误处理;版本说明是历史范围,不能据此宣称所有代码在当前Python仍可直接运行。授权、联系方式和致谢属于出版背景,没有进一步技术机制。

第1章 数据结构和算法

本章从容器的组织方式出发,区分解包的形状契约、堆的局部顺序、字典集合运算与记录筛选。不同工具不互相替代:少量极值、全排序和按键分组有不同前提。理解这些前提,后续按需迭代和序列化才能保持数据含义。

1.1 将序列分解为单独的变量

解包用赋值左侧的变量结构声明预期数据形状。固定数量不匹配会失败,嵌套也需要对应;它适用于可迭代对象,而不只限于列表和元组。用于忽略值的下划线只是普通变量约定,仍会被赋值。

解包是结构契约

要把固定结构记录分成变量,可以用对应形状赋值,例如x, y = (4, 5);嵌套记录也能在左侧写出嵌套结构。数量或层级不匹配会暴露错误,因此解包同时声明了输入假设。对象只需可迭代,不必是列表;_是普通变量名,表示忽略的约定仍会赋值,需避免覆盖其他用途。

函数写return 1,2,3时返回的是一个三元组;调用方可接收整体,也可按预期结构解包。逗号构造元组,括号主要用于分组,空元组等语法仍另有规则。

解包是结构契约保存独立卡片。

原书依据 · 2 处

1.2 从任意长度的可迭代对象中分解元素

变长记录仍可有固定头尾,用星号目标收集其余项就能保持这些位置的含义。余项总是列表,也可能为空;嵌套或带标签记录可以进一步分派处理。它不是任意长度数据的惰性头尾接口,递归拆列表的示例也不适合作通用求和。

星解包收集变长余项

处理长度变化但头尾位置固定的记录时,可用first, *middle, last = grades分出边界与余项。星号目标得到列表,余项可为空,但仍需满足未带星号位置所需的最少元素数;计算平均值还要自行处理空列表。它可用于带标记记录与拆分后的字段,星号接收与函数调用处的*args展开用途不同。收集余项会得到实际列表,不能当成无限流的惰性拆分。

星解包收集变长余项保存独立卡片。

原书依据 · 1 处

1.3 保存最后N个元素

有界deque把最近记录的保留上限交给容器,追加新项时从另一端淘汰最旧项。搜索例在追加当前行之前yield,因此历史不包含当前匹配行;yield给出同一可变队列,保存结果时也要考虑后续变动。无上限deque则作为普通双端队列使用,两端操作不同于列表头部移动。

队列保存窗口

要在处理过程中保留最近N项,可用deque(maxlen=N)设定容量上限,再逐项append;队列满时会从另一端淘汰最旧项,并非创建时就有N个元素。搜索例先yield匹配行与历史,再追加当前行,所以历史不含当前行。它暴露的是同一个可变队列,若要长期保存某次历史,应复制所需快照;容器不会替调用者决定结果生命周期。

队列保存窗口保存独立卡片。

原书依据 · 1 处

双端队列支持两端进出

需要在序列两端进出数据时,可用无容量上限的deque(),例如appendleft(x)在左侧加入,popleft()取走左端。两端添加与弹出的常见复杂度为O(1),列表头部插入或删除则需要移动元素,通常为O(N)。这不表示deque所有位置访问都同样高效,也不保证某个实际程序必然更快。

双端队列支持两端进出保存独立卡片。

原书依据 · 1 处

1.4 找到最大或最小的N个元素

找少量极值与排序全部数据是不同任务。nlargest/nsmallest可按key比较复杂记录,选择时要看所需N与总量的关系;堆本身只维护能快速取最小项的局部顺序,不等于整个列表已排好。

小N优先用堆

要找少量最大或最小元素,可考虑heapq.nlargest(N, items)或nsmallest,并用key指定记录的比较字段。所需N远小于总量时通常更合适;只要一个极值可直接用min/max,接近全量则需比较排序。具体实现可能按输入优化,不能把示例heapify完整列表当成这些函数的唯一内部算法,也不能凭复杂度代替实际测量。

小N优先用堆保存独立卡片。

原书依据 · 1 处

堆序不等于整体排序

最小堆保证根部可取最小元素,但内部列表不一定整体有序。heapify建立堆后,反复heappop才按从小到大取出;每次弹出会破坏性地修改堆并维护剩余堆序,代价与堆大小M相关,常见为O(log M)。需要原数据时先作副本,不要把打印出来的堆数组当成已排序结果。

堆序不等于整体排序保存独立卡片。

原书依据 · 1 处

1.5 实现优先级队列

优先队列把业务优先级转换成堆可比较的键:负优先级让较高值先弹出,递增序号让同级按入队顺序,并避免比较没有次序定义的载荷。队列只提供这类顺序规则,线程通信还需同步协议。

优先队列显式编码比较规则

需要每次弹出最高优先级元素时,可用最小堆保存(-priority, index, item):priority取负让高优先级先出,递增index在同级时保持入队顺序,并阻止比较不可排序的item。PriorityQueue.push(item, priority)加入,pop()返回载荷;空队列与并发使用仍需额外约定,原例不含线程同步。

结构图:

classDiagram
    class PriorityQueue {
        +push(item, priority)
        +pop()
    }
    class Item {
        +__init__(name)
        +__repr__()
    }
    PriorityQueue o-- "*" Item : 通过堆元组保存引用

图保留原例名称和参数,聚合不表示独占生命周期;返回类型未在签名中声明,未补造。原文push/pop排版缩进有误,方法归属据调用与说明理解,不声称原样可运行。

优先队列显式编码比较规则保存独立卡片。

原书依据 · 1 处

序号避免比较不可排序载荷

用元组作排序键时,会从左到右比较,前面的字段决定结果后无需比较余项。若只放(priority, item),同优先级会落到不支持次序比较的载荷并失败;加入唯一递增序号,就能先打破平局。这个序号还定义同级稳定出队顺序,不能在仍有旧元素时重复使用而破坏假设。

序号避免比较不可排序载荷保存独立卡片。

原书依据 · 1 处

1.6 在字典中将键映射到多个值上

字典每个键仍只有一个值,一键多值是把列表或集合作为这个值。列表保留重复与添加次序,集合用于去重;defaultdict用工厂处理缺失键,下标访问可能因此改变字典。显式setdefault则把插入动作放在调用处。

多值字典用容器保存值

若一个键需要对应多项数据,可把列表或集合作为字典值;前者保留重复和追加顺序,后者用于去重且不依赖遍历顺序。defaultdict(list)让首次缺失键下标访问创建空列表,随后append即可。若不希望普通读取创建键,可使用普通字典,在需要插入时显式setdefault;它也会添加缺失键,且默认表达式每次调用都会先求值。

按字段收集所有记录时,可逐项追加到对应键的列表,不必先排序;这种方式便于以后按键随机访问,但会保存完整分组,需考虑输入规模。

多值字典用容器保存值保存独立卡片。

原书依据 · 2 处

1.7 让字典保持有序

本书在Python 3.3背景下使用OrderedDict保留键最初加入的次序,更新既有键不改变该位置。顺序跟踪也有实现与存储代价。现代普通dict的插入顺序保证已经改变选择前提,因此保留历史方法时同时注明官方版本边界,不能沿用普通字典必然无序的结论。

映射顺序需要版本前提

要按插入顺序迭代或序列化映射,本书的Python 3.3方案使用OrderedDict,更新既有键不改变其位置;历史实现以链表跟踪顺序,增加存储成本。现代普通dict自Python 3.7也保证插入顺序,不能再仅以有序为由断言必须用OrderedDict。Python官方文档已核验此版本变化(2026-10-27);原书“两倍多”不是所有版本固定内存比。

映射顺序需要版本前提保存独立卡片。

原书依据 · 1 处

1.8 与字典有关的计算问题

直接迭代字典得到键,按值计算则应明确选择返回值、键还是两者。把(value,key)成对比较能同时保留关联信息,也意味着值相同时继续比较键;zip生成的迭代器消费后还需重新创建。

按字典值计算要保留关联

要按字典中的值找极值或排序,先区分需要值、对应键还是两者。min(d)比较键,min(d.values())只给值;用min(zip(d.values(), d.keys()))可得到(value,key)对。元组先比较值,再用键打破平局,因此同值时键还需可排序;若只想按值选择对应键,可用key函数明确规则。不要把两种平局语义当成完全相同。

按字典值计算要保留关联保存独立卡片。

原书依据 · 1 处

迭代器耗尽后不能直接复用

zip等迭代器提供的是逐步消费的遍历状态,通常用完后不会自动重新开始。对同一个zip对象先求min再求max,第二次可能面对空输入。需要多遍时可重新创建迭代器,或在输入有限且内存允许时保存结果;把无限流整体转换为列表不是可行的通用补救。

迭代器耗尽后不能直接复用保存独立卡片。

原书依据 · 1 处

1.9 在两个字典中寻找相同点

字典视图可把键与键值对用于集合比较,表达交集和差集,而无需先复制全部键。比较对象不同,结果含义也不同;items视图做这类集合运算还依赖值可哈希,values则没有同样的集合接口。

字典视图按比较对象做集合运算

比较两个映射时,a.keys() & b.keys()找共同键,a.items() & b.items()找相同键值对,差集可进一步筛选新字典。键视图可直接参与集合操作,不必先复制成集合;items用于集合运算时,相关值也需可哈希。values视图不提供同样操作;转为集合还要求值可哈希,并会丢失重复次数与顺序,不能把这些信息损失忽略。

字典视图按比较对象做集合运算保存独立卡片。

原书依据 · 1 处

1.10 从序列中移除重复项且保持元素间顺序不变

稳定去重不是把结果直接变成集合,而是沿原顺序遍历,用集合只记录已经见过的判定键,首次出现时输出原项。复杂记录可提取稳定的可哈希键,键的选择也定义了什么算重复。

按首次出现顺序去重

要去重而保留首次出现顺序,可依次遍历输入,用seen集合记录已见判定键,首次遇到时输出原项。简单可哈希值可直接作键;字典等记录可提取稳定、可作为集合成员的字段元组。按(x,y)去重与只按x去重的含义不同,应先定义等价规则。生成器可逐项输出,但seen仍随不同键数量增长,不能据惰性输出断言内存恒定。

按首次出现顺序去重保存独立卡片。

原书依据 · 1 处

1.11 对切片命名

slice对象让固定字段范围拥有名称,并可复用在读取、替换或删除中。它还公开start/stop/step,indices(size)则按目标序列长度规范化边界,便于交给range。名称说明位置意图,不会自动验证外部记录格式。

切片名称显露固定字段含义

当固定字段解析到处重复裸索引时,可给slice对象命名,例如SHARES = slice(20,32),再使用record[SHARES]。同一对象也可用于适用序列的替换或删除,减少位置规则散落;start、stop、step让边界可检查。indices(size)按指定长度规范化索引供range使用,但不会替程序验证字段长度或内容格式。

本章脚注把平面文件用于描述没有关系结构的记录文件;命名切片适用于已知固定字段范围,不能由这一文件名就推定所有记录都等宽。

切片名称显露固定字段含义保存独立卡片。

原书依据 · 2 处

1.12 找出序列中出现次数最多的元素

Counter将可哈希元素映射到计数,most_common返回高频项,update把后续输入累加。运算还需要区别计数映射与正多重集:示例中的加减不是任意有符号差值的保真表示。

计数器汇总频次并保留语义

要统计可哈希元素的频次,可用Counter建立元素到计数的映射,再用most_common(N)选高频项;update是累加,而非普通字典的覆盖。计数器之间的加减采用正多重集输出语义,会丢弃非正结果,不能当完整有符号差值账本。官方Counter文档已核验该边界(2026-10-27);对象本身能保存负值与运算输出过滤是两回事。

计数器汇总频次并保留语义保存独立卡片。

原书依据 · 1 处

1.13 通过公共键对字典列表排序

排序的key把记录映射为可比较依据。itemgetter可提取一项或多项,多项形成按字段先后比较的元组;同样的提取器也能用于min/max。它分离了记录本身与当前排序目的,字段应存在且提取结果可比较。

排序键显露记录的比较字段

要按记录字段排序,可给sorted传key提取比较值;字典记录可用itemgetter("lname", "fname"),返回元组先按姓再按名比较。同一提取器也适用于min/max,载荷本身无需支持次序。选择器也可按下标或对象的取项协议取值;字段缺失或返回值不可比较仍会失败,不能把key当成数据清洗。lambda可表达同样逻辑,性能需按实际输入观察。

若记录是对象,可用attrgetter("user_id")读取属性,或以多个属性形成元组;这与itemgetter读取字典键/下标的方式不同。User示例只按user_id排序,不需要让User自己实现大小比较。

排序键显露记录的比较字段保存独立卡片。

原书依据 · 2 处

1.14 对不原生支持比较操作的对象排序

对象不必定义所有实例的自然次序,也可在当前操作中用属性提取器提供排序键。attrgetter对应属性访问,itemgetter对应取项;二者以相同key接口服务不同记录形式。

排序键显露记录的比较字段关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

1.15 根据字段将记录分组

groupby分的是相邻且键相同的一段段记录;若要同一键的全部记录归在一起,先让它们连续,常见办法是按相同key排序。若需要随时按键随机访问全部组,则容器聚合更合适,但需要保存相应数据。

多值字典用容器保存值关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

连续分组须先对齐键顺序

要让同一键的全部记录在一组迭代,先使它们连续,例如按目标key排序,再交给itertools.groupby。它每次返回键与该组的子迭代器,不会自动全局搜集后续同键记录;已经按键连续的数据无需重复排序。若目标是按键随机访问各组,可用多值字典聚合,换取保存全部组的空间。两种方案解决的访问需求不同。

连续分组须先对齐键顺序保存独立卡片。

原书依据 · 1 处

1.16 筛选序列中的元素

提取、过滤和替换决定不同的结果形状:过滤去掉不满足条件的项,条件表达式则保留位置但改变值。列表、生成器和filter控制何时产生结果,compress则把另一列的布尔选择结果按位置应用到数据上。

筛选与替换要区分结果形状

删去不满足条件的项,可用推导式的if过滤;若要保留位置而替换值,应把条件写在输出表达式中,例如n if n > 0 else 0。结果较大时可用生成器逐项产生,复杂条件或异常处理可封装为函数供filter使用。filter返回迭代器,且判断通过后输出原项,不能把条件函数内的转换误认为输出值也被转换。

筛选与替换要区分结果形状保存独立卡片。

原书依据 · 1 处

布尔掩码筛选需位置对齐

要把一列的判断用于另一列数据,可先生成布尔选择序列,再用compress按相同位置保留真值对应的项。前提是两列代表同一顺序的记录,任何漏项、重排或长度差异都应先核对;它不按业务键自动匹配。返回值是迭代器,若需长期持有结果且输入有限,可显式收集。

布尔掩码筛选需位置对齐保存独立卡片。

原书依据 · 1 处

1.17 从字典中提取子集

字典推导式把保留条件与键值输出放在一起,创建新的映射子集。可以按值或键成员关系筛选;不同写法的历史计时只说明需要测量,不能据示例倍数为当前输入下结论。

字典推导式显露子集条件

要从映射中提取子集,可用字典推导式同时说明保留条件和输出键值,例如{k:v for k,v in prices.items() if v > 200}。也能按目标键集合筛选。它建立新映射,不会自动深复制值对象;如果值仍引用可变对象,两个映射可能共享内容。按键交集再查值是另一种表达,应按清楚程度和真实负载比较,不照搬原书计时倍数。

字典推导式显露子集条件保存独立卡片。

原书依据 · 1 处

1.18 将名称映射到序列的元素中

命名元组由工厂产生带字段名的tuple子类,使读取代码不必记住每个下标。它仍有固定构造结构,不会自动适应数据库增加字段;字段赋值不可原地改变,但_replace能创建替代实例。原型实例则可为缺省字段提供已有值。

命名元组让字段含义可见

用namedtuple工厂指定类型名和字段,可得到tuple子类,用字段名替代神秘下标。原例Stock有name、shares、price,读取shares更能说明计算含义。它仍支持索引与解包,且构造数量、位置仍须与输入对应;Stock(*rec)不会自动适应数据库增列。字段不能原地重新赋值,_replace返回新实例;这也不是内部可变载荷的深度冻结。

结构图:

classDiagram
    tuple <|-- Stock
    class Stock {
        +name
        +shares
        +price
        +_replace(**kwargs)
    }

图采用原文第一个三字段Stock版本;namedtuple是返回类型的工厂函数,不是这个继承图里的类。_replace按关键字创建替代实例,原文未给具体返回类型注解。

命名元组让字段含义可见保存独立卡片。

原书依据 · 1 处

原型记录提供缺省字段

要从字段可能缺少的字典构造完整记录,可先创建包含默认值的命名元组原型,再用prototype._replace(**data)生成新实例。原例五字段Stock把date/time默认设为None,已有字段由输入替换。它解决的是已知结构中的缺省值,不会自动接受任意新字段;默认值是否共享可变对象仍需设计。

原型记录提供缺省字段保存独立卡片。

原书依据 · 1 处

1.19 同时对数据做转换和换算

转换后的数据若只供一次聚合,可将生成器表达式直接交给sum等函数,避免显式中间列表。但返回投影值与按key选择原记录是不同契约,不能为了写法短就混淆它们。

转换聚合可按需衔接

要先转换或过滤数据再聚合,可把生成器表达式直接传给消费者,例如sum(x*x for x in nums),减少显式的一次性中间列表。是否节省全部内存仍取决于消费者和输入,不能把任何函数都当作流式处理。min(r["shares"] for r in rows)返回数值,而min(rows, key=...)返回原记录,两者应按调用者需要选择。

转换聚合可按需衔接保存独立卡片。

原书依据 · 1 处

1.20 将多个映射合并为单个映射

ChainMap把多个原映射作为查找层次,优先采用较前层的值,修改却只作用于第一层。它保留引用,因此原映射的改动可见;这不同于update建立一份合并副本。new_child和parents还能用来进入或离开局部层次。章末脚注补充数据术语,其中可哈希性的解释需纠正。

切片名称显露固定字段含义关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

链式映射分离查找与写入层

要把多份映射逻辑上当成一个查找范围,可用ChainMap按顺序搜索,重复键取第一份命中值。写入与删除只作用第一层,即使后层有该键,删除也可能失败。它保存原映射引用,后续原对象变化会被看见;new_child增加局部层,parents返回后续层视图,不能把它当成隔离的合并快照。

结构图:

classDiagram
    class ChainMap {
        +new_child()
        +parents
    }
    class dict
    ChainMap o-- "*" dict : 原例映射引用

图中的dict对应原例a、b;new_child只列原文使用的无参数形式,parents是属性。聚合表示引用而非独占生命周期,查找顺序和仅写第一层由正文说明。

链式映射分离查找与写入层保存独立卡片。

原书依据 · 1 处

合并副本与引用视图不同

把多份字典用update汇入新字典,会复制当前的键值关联;原字典以后替换某个值,不会同步修改这份合并映射。ChainMap则保留原映射,读取能反映其后续变化。应先决定需要固定的合并结果还是动态视图;字典合并仍是浅层复制,嵌套可变对象可能共享,不能把副本理解成全面隔离。

合并副本与引用视图不同保存独立卡片。

原书依据 · 1 处

可哈希不等于对象不可变

可哈希要求对象在生命期内哈希值稳定,能按相等规则比较,且相等对象具有相同哈希值,才可安全作字典键或集合成员。它不等于所有内部状态绝不能变;元组若含不可哈希成员也不一定可哈希。原章脚注把两者等同过强,已据Python官方术语表核验修正(2026-10-27)。

可哈希不等于对象不可变保存独立卡片。

原书依据 · 1 处

第2章 字符串和文本

文本处理先区分字节与字符,再处理查找、替换、规范化、分词和语法结构。正则表达式适合一定范围的模式,递归语法需要更明确的解析层次;编码、大小写和Unicode规范化是不同转换,不应混为“清洗一下”。

2.1 针对任意多的分隔符拆分字符串

多个分隔规则可用正则统一表达,但是否捕获分隔符会改变结果列表。括号只用于组合时应选择非捕获组;若要重组原文,则应确认捕获了需要保留的全部字符,而非仅保留一个主分隔符。

正则拆分要明确是否保留分隔符

分隔符可能是逗号、分号或空白时,可用re.split定义模式。捕获括号会把捕获内容也放进结果,非捕获组(?:...)只负责组合规则。原例捕获主分隔符,却未捕获其后的全部空白,因此字段再拼接只重建规范化文本,不能称为原文无损恢复。是否保留分隔信息应由后续用途决定。

正则拆分要明确是否保留分隔符保存独立卡片。

原书依据 · 1 处

2.2 在字符串的开头或结尾处做文本匹配

固定前后缀适合直接用startswith/endswith表达,多个备选可合为字符串元组。它检查的是文字边界而非完整路径或URL的语义,简单任务无需先构造复杂正则。

固定前后缀可直接匹配

检查固定前缀或后缀,可用startswith/endswith;多个选择可传字符串元组,例如name.endswith((".c", ".h")),列表或集合需先转换。配合any能判断是否有匹配项。它只是文字边界检查,不替代URL、路径或输入安全的完整验证;采用简单表达主要为清楚,不保证所有负载下都比其他实现更快。

固定前后缀可直接匹配保存独立卡片。

原书依据 · 1 处

2.3 利用Shell通配符做字符串匹配

Shell风格通配符适用于比固定前缀更灵活、又无需完整正则的模式。它能匹配普通字符串,不会自行遍历目录;大小写处理应看所用函数与平台规范化规则,而非简单等同底层文件系统。

通配符匹配要明确大小写规则

按*.py、?oo.txt等Shell通配模式匹配字符串,可用fnmatch;这些语法不是正则表达式,也不局限于实际文件名。fnmatch会用平台的os.path.normcase规范化名称和模式,fnmatchcase则保持显式大小写比较;不能把它们等同于探测当前文件系统的大小写特性。此边界已查官方文档(2026-10-27)。若要展开路径,应另用相应路径工具。

通配符匹配要明确大小写规则保存独立卡片。

原书依据 · 1 处

2.4 文本模式的匹配和查找

正则首先需要说明在哪儿开始、是否覆盖全部输入,以及要列表、分组值还是逐个匹配对象。compile保存可复用模式,捕获组提供结构化字段;Python字符串与正则又分别解释转义,原始字符串减少前一层干扰。

匹配起点与覆盖范围须明确

从开头识别模式可用match,它允许只匹配前缀,不能据成功就认定整串有效。findall搜索多处匹配并收集结果,finditer逐个提供匹配对象。完整输入校验需明确终点与换行规则;Python的$也可在末尾换行前匹配,原书把它当绝对整串保证过强,已查官方re文档(2026-10-27)。日期形状匹配也不等于日历有效性验证。

匹配起点与覆盖范围须明确保存独立卡片。

原书依据 · 1 处

捕获结果形状随接口变化

括号捕获把整体匹配拆成可取字段:匹配对象的group(0)是整体,group(1)等取子组,groups()返回子组元组。findall的输出也受捕获组数量影响,原例三个日期字段使结果成为元组列表。需要位置或完整匹配上下文时,可用finditer逐个处理匹配对象;不要把不同接口结果都当成原始字符串列表。

捕获结果形状随接口变化保存独立卡片。

原书依据 · 1 处

正则字面量要考虑双层转义

正则写在Python源码里时,字符串字面量先解释一次,正则引擎再解释模式中的反斜线。以r前缀表示原始字符串,可减少第一层处理,让r"\d+"较直接表达数字模式,但原始字符串仍受Python字面量语法限制。重复使用时可compile保存模式;模块级函数也缓存近期模式,显式编译并不等于消除全部性能成本。

正则字面量要考虑双层转义保存独立卡片。

原书依据 · 1 处

2.5 查找和替换文本

字面替换可直接用replace,按模式重排字段则用sub及捕获组引用。若替换结果需要计算,可让sub把每次的匹配对象交给回调,由回调返回替换字符串;subn还提供替换次数,便于检查操作规模。

模式替换可重排或计算字段

要改写匹配到的字段,可用re.sub,并在替换模板里引用捕获组,例如日期中指第3组的内容,不是捕获组数量。复杂转换可传回调:sub对每次匹配传入匹配对象,函数取组并返回新文本。需要替换次数时用subn得到(新文本, 次数)。简单固定文本可直接replace;这些操作生成新字符串,不自动验证输入日期是否合法。

模式替换可重排或计算字段保存独立卡片。

原书依据 · 1 处

2.6 以不区分大小写的方式对文本做查找和替换

忽略大小写控制的是查找接受什么文本,不会自动让替换文本继承原来的大小写。可在回调中识别全部大写、全部小写或首字母大写等有限类别,再生成相应输出;这仍不是任意混合大小写的保真转换。

忽略大小写不等于保留字形

查找或替换时设IGNORECASE能接受大小写变体,但固定替换词不会自动继承原词外观。若需保留简单风格,可用回调查看匹配文本是否全大写、全小写或首字母大写,再转换替换词。原matchcase只覆盖这些分支,不保持任意混合大小写模式;Unicode特殊折叠还需要另查规则,不能把ASCII词例推广到所有文字。

忽略大小写不等于保留字形保存独立卡片。

原书依据 · 1 处

2.7 定义实现最短匹配的正则表达式

贪婪重复会优先尝试更多字符,因而一段引号模式可能跨过中间的结束符。非贪婪修饰让重复先尝试较少字符,再按后续模式要求扩展;它改变尝试顺序,而不是赋予对所有结构的正确解析能力。

非贪婪重复优先尝试较短范围

当"(.*)"跨过多组引号时,可用"(.*?)"让重复优先尝试较少字符,以便后续结束引号更早满足。它仍要满足整个模式,不能理解为在所有起点与分支中寻找全局最短串。转义引号或嵌套结构还需相应语法,简单非贪婪模式不等于完整字符串解析器。

非贪婪重复优先尝试较短范围保存独立卡片。

原书依据 · 1 处

2.8 编写多行模式的正则表达式

跨行匹配失败可能源自点号默认不包含换行。可以在局部模式中显式纳入换行,或用DOTALL改变点号行为;非捕获组仅组合分支,不给结果增加捕获项。

跨行匹配须显式包含换行

用点号匹配多行文本时,默认行为会在换行处受限。可用DOTALL让点号包含换行,或在局部模式中明确列出需要的字符范围;(?:...)只分组而不增加捕获结果。C风格注释例还用非贪婪重复寻找结束符,但它没有处理完整语言词法或嵌套注释,不能直接当成可靠源码解析器。

跨行匹配须显式包含换行保存独立卡片。

原书依据 · 1 处

2.9 将Unicode文本统一表示为规范形式

相同文本可由不同代码点序列表示,例如预组成的ñ与n加组合波浪号。NFC/NFD为标准等价表示提供一致形式;兼容规范化会进一步合并某些区别,而去除音符又是另一种有损变换,不能混为一谈。

Unicode需规范化

视觉相同的文本可能使用不同代码点序列,直接比较并不相等。需按标准等价关系比较时,可先统一为NFC的规范组合形式或NFD的规范分解形式,如预组成ñ与n加组合波浪号。这里改变的是Unicode表示,不是选择UTF-8等字节编码;它也不能消除所有相似字形的差异。规范化形式应由实际比较契约决定。

Unicode需规范化保存独立卡片。

原书依据 · 1 处

兼容规范化可能丢失区分

NFKC/NFKD在规范等价之外还处理兼容分解,例如把某些连字拆成普通字母序列。这样便于宽松匹配,也可能丢失原本需要保留的区别,不能把它当成无损清理。NFC/NFD与兼容形式用途不同,选择之前应明确哪些表示应被视为相同;此边界已据Unicode官方FAQ核验(2026-10-27)。

兼容规范化可能丢失区分保存独立卡片。

原书依据 · 1 处

2.10 用正则表达式处理Unicode字符

Unicode正则的字符类需要按准确类别理解,数字不只ASCII,但也不是所有具有数字意义的字符。规范化可统一表示,却不会自动解决多字符大小写折叠;需要超出标准re行为时,再比较第三方实现的明确规则。

Unicode数字须分清类别

处理Unicode字符串时,Python正则的\d默认匹配Nd类十进制数字,包含ASCII之外的数字,但不是所有带数值含义的字符;若只允许ASCII数字,可明确写[0-9]。原书“任意Unicode数字”过宽,已据官方re文档核验(2026-10-27)。指定代码点范围也只代表所列范围,不能自动覆盖某种语言的全部书写情况。

Unicode数字须分清类别保存独立卡片。

原书依据 · 1 处

大小写折叠需明确比较语义

有些大小写转换会让一个字符变成多个字符,因此忽略大小写匹配不能简单等同于先upper再比较。原例意在展示德语ß与SS的边界,实际文本有损坏,不照抄为可信运行输出。规范化、大小写转换和完整折叠解决不同问题,应根据目标字符集及引擎规则选择。

大小写折叠需明确比较语义保存独立卡片。

原书依据 · 1 处

regex扩展匹配能力

regex是提供额外匹配能力的第三方实现,原书以完整Unicode大小写折叠与近似匹配作为扩展参考。项目说明已核验这两类能力(2026-10-27),完整折叠还与行为模式和标志有关,不能因安装就假定所有规则与re相同。它适合进一步比较机制,不构成本次更换依赖或运行安装的结果。

regex扩展匹配能力保存独立卡片。

原书依据 · 1 处

2.11 从字符串中去掉不需要的字符

strip系列只处理字符串两端,参数表达一组可去除字符,不能用于按原样删除一个完整前缀。内部空白的删除或压缩属于另一个转换目标;与生成器结合可逐行处理,而不先加载整个文件。

两端裁剪不同于内部替换

去掉字符串两端不需要的空白或字符,可用strip,或只处理一侧的lstrip/rstrip。显式参数是一组字符而非整个前后缀,strip("-=")会反复去除两端的这两种字符。它不改变内部内容;删除内部空格与把连续空白压成一个空格又有不同语义,应明确选择replace或模式替换。逐行生成器可延后处理,但裁剪仍可能丢弃有意义格式。

两端裁剪不同于内部替换保存独立卡片。

原书依据 · 1 处

2.12 文本过滤和清理

字符清理可声明为代码点到字符、代码点或删除的映射,translate按规则应用。分解后去标记或丢弃非ASCII都可能改变文本含义,目标必须先明确;组合类别和数字类别也要准确,不把旧版本字符总数当常量。

清洗是映射问题

当清理需要逐字符重映射时,可用translate表把代码点映射到替代字符串、代码点或None;None表示删除,规则集中后较易检查。例如把制表符换空格,与直接删除它含义不同。可以结合Unicode分解与属性分类生成规则,但清理目标应由数据契约决定,带音符文本不代表恶意。简单replace也可能更合适,性能需在实际负载下比较。

清洗是映射问题保存独立卡片。

原书依据 · 1 处

有损字符清理须确认目标

分解后丢弃非ASCII能得到受限文本,却会永久丢掉不能表示的字符;去音符也可能合并本应区分的名称。仅在目标契约允许这种损失时采用,并保留所需原始信息。用combining筛选只能反映规范组合类别,不能无条件称为删除全部Unicode标记;该属性边界已据官方unicodedata文档核验(2026-10-27)。

有损字符清理须确认目标保存独立卡片。

原书依据 · 1 处

数字规范化应按类别映射

需要把不同文字中的十进制数字统一为ASCII时,可先选Unicode Nd类别,再按数值映射到0到9的代码点。这个目标不同于删除所有非ASCII字符,后者会把数字也丢掉。原书的460个数字统计依赖当时Unicode数据库,不能当成固定总数;转换也不负责解释小数点、正负号或完整数值格式。

数字规范化应按类别映射保存独立卡片。

原书依据 · 1 处

2.13 对齐文本字符串

对齐先指定方向、宽度和填充,字符串方法处理简单情况,format则把这些要求与数字精度等放进统一规格。宽度是格式目标,不等于按终端显示单元测量所有Unicode文本,也不自动截短内容。

对齐格式应显式指定方向宽度

需要定宽显示字段时,可用ljust/rjust/center,或在format规格中写<、>、^表示左、右、居中,再指定宽度与填充字符。format还可结合数字精度,例如format(x, ">10.2f")。宽度通常是最小字段宽度,超长内容不会因此被截断;字符数也不等于所有终端的显示列宽,不能仅凭ASCII例保证中文或控制序列对齐。

数值还可用f或e/E选择定点或科学计数表示,用逗号指定分组。固定逗号分组不自动读取本地化规则;translate交换逗号和小数点只是字符映射,不能当成完整地区格式器。格式结果是文字,不能用显示位数证明底层运算已按相同精度完成。

对齐格式应显式指定方向宽度保存独立卡片。

原书依据 · 2 处

2.14 字符串连接及合并

片段很多时,join集中说明分隔符和目标文本;若最终只是输出,也可能不必先构造整串。生成器可以把片段生成与消费方式分开,消费方再选择整合或分批I/O。批量阈值与真实缓冲行为都需要明确,不能用函数调用数直接推断系统调用成本。

多片段合并先明确消费目标

需要一个完整字符串时,可用分隔字符串的join合并片段,非字符串先按需要转换。少量连接用+也可清楚表达,长循环拼接则可能产生额外分配与复制,应比较实际负载。若只是打印多个值,可直接用sep;若写文件,可考虑分批输出。Python层write次数不等于实际系统调用次数,缓冲和片段大小都会影响取舍。

多片段合并先明确消费目标保存独立卡片。

原书依据 · 1 处

片段生成与输出策略分离

让生成器只yield文本片段,消费方再决定join成完整文本、逐段写出或合并小批量,可使生产逻辑不绑定单一输出方式。原combine按追加后的字符数超过阈值才输出,因此maxsize不是严格块大小或字节上限,大片段仍可能直接超出。需要硬性内存或传输限制时,必须再定义分割与编码规则。

片段生成与输出策略分离保存独立卡片。

原书依据 · 1 处

相邻字面量会在源码中连接

Python源码中相邻的字符串字面量会连接,例如"Hello" "World"成为一段文字;这只适用于字面量,不能把变量也这样并排。它可用来组织长常量,也可能把列表里漏掉的逗号悄悄变成连接。数据条目数量异常时应检查这种情况,例如布尔掩码筛选需位置对齐所需的列对齐会因此被破坏。

相邻字面量会在源码中连接保存独立卡片。

原书依据 · 1 处

2.15 给字符串中的变量名做插值处理

字符串插值把占位字段连接到显式值或映射,缺失字段可选择报错或保留简单占位。vars提供可用环境,safesub通过字典缺失钩子定义策略;栈帧技巧则隐式依赖调用环境,其行为和可修改性必须按Python版本核对。

映射插值须明确缺失策略

格式模板可用format传命名值,或format_map传映射;vars也可从存在属性字典的对象取值。缺失字段通常报错,原safesub继承dict并用missing(key)返回花括号占位,适合保留简单未提供字段。它不代表所有属性访问或格式规格都会成功,更不是安全沙箱。

结构图:

classDiagram
    dict <|-- safesub
    class safesub {
        +__missing__(key)
    }

图沿用原类型和参数;钩子返回形如{key}的字符串,不向方法签名补造类型注解。

映射插值须明确缺失策略保存独立卡片。

原书依据 · 1 处

栈帧访问依赖作用域与版本

从调用者栈帧取f_locals可省去显式传值,却让函数依赖调用环境和解释器细节。原sub用safesub构造一份映射来插值,不能据此断言f_locals写入永远无效:Python 3.13起,优化作用域(如函数)的f_locals返回可写穿代理,修改可反映到局部环境。已据官方数据模型核验(2026-10-27),不沿用原书绝对安全保证。

栈帧访问依赖作用域与版本保存独立卡片。

原书依据 · 1 处

2.16 以固定的列数重新格式化文本

textwrap按指定宽度整理段落,首行与后续行可用不同缩进。目标终端宽度可以作为输入来源,但整理器的字符处理规则和真实显示效果仍需针对文本检查。

段落重排应区分首行后续缩进

需要把长段落整理到指定宽度时,可用textwrap.fill(text, width),用initial_indent控制首行、subsequent_indent控制后续行。终端列数可作为宽度参考,但制表符、长单词及宽字符的显示需按具体规则验证,不能把英文空格文本例直接当所有终端的排版保证。它重排文本,不保留原始换行布局。

段落重排应区分首行后续缩进保存独立卡片。

原书依据 · 1 处

2.17 在文本中处理HTML和XML实体

生成HTML文本时需要把具有标记意义的字符转义,还原字符引用则方向相反。字符引用让字符能用ASCII文本表达,也不同于字节编码本身;处理完整HTML/XML时仍应让合适解析器理解结构。

HTML转义与实体还原方向不同

输出HTML文字时,escape把&、<、>等转为字符引用,quote选项再决定是否处理引号;反向还原字符引用则是另一操作。现代html.unescape按HTML规则处理命名与数字引用,已查官方html文档(2026-10-27)。原HTMLParser.unescape属于旧用法,不能无版本核验照搬;完整HTML/XML应交合适解析器,不靠反复字符串替换理解结构。

HTML转义与实体还原方向不同保存独立卡片。

原书依据 · 1 处

字符引用与字节编码分属两层

要在ASCII输出中保留非ASCII字符的可表达形式,可在相应编码处理中用xmlcharrefreplace,把不能编码的字符写成数字字符引用,例如ñ可表达为&#241;。输出先是ASCII字符组成的表示,后续按HTML/XML规则解释才得到原字符;这不同于直接输出其UTF-8字节,接收方必须知道采用哪一层约定。

字符引用与字节编码分属两层保存独立卡片。

原书依据 · 1 处

2.18 文本分词

分词把原字符流转成带类型的标记流,命名捕获组提供类型,匹配内容提供值。连续扫描必须覆盖空白等所有合法文本,失败还要区分结束与非法后缀;重叠规则的分支次序也会改变结果。

分词需识别类型并覆盖输入

把文本转成标记流时,可为每类词法模式命名,再由匹配的组名与文本形成(type,value)。连续扫描还要识别空白,即使后续会过滤它。原scanner.match遇到不识别字符就停止,停止本身不证明已到输入末尾;若目标是完整输入,需核对消费位置并报告未知后缀,否则会静默接受一段前缀。

分词需识别类型并覆盖输入保存独立卡片。

原书依据 · 1 处

词法规则重叠须明确优先级

正则分支按给定优先级尝试,不会自动按词法目标选最长标记。识别<=与<时,若短分支在前,就可能拆成<和=;固定重叠运算符需合理排列。关键字print与标识符printer还表明,长短排序不足以替代标识符边界规则。应按可接受语言设计规则,不按正则源码字符数机械排序。

词法规则重叠须明确优先级保存独立卡片。

原书依据 · 1 处

2.19 编写一个简单的递归下降解析器

先用文法规定允许的结构,再把规则映射为消耗标记的方法,才能清楚地处理优先级与括号。前瞻辅助函数区分可选与必需符号,循环表示重复,递归处理嵌套;同一结构也可求值或构树。朴素算法、完整输入检查和库生成方式分别有不同边界。

文法声明允许的标记结构

解析前先写文法:规则名可展开为更细规则或输入标记,::=描述展开,|给出选择,EBNF的重复记号可表示零次或多次。算术例用expr、term、factor分层,并以NUM与括号等作为标记。文法规定允许组合,词法规则先把字符分成标记;仅有能识别数字和符号的正则,还没有定义合法表达式结构。

文法声明允许的标记结构保存独立卡片。

原书依据 · 1 处

解析器分层表达

手写递归下降解析器时,可把每条规则映射为一个函数或方法:遇到子规则就调用它,遇到终结标记就检查并消费,重复部分用循环处理。括号中的expr再次调用表达式规则,体现递归;expr调用term、term调用factor体现下降。函数返回该规则的解析结果,错误时明确失败;这种映射仍需能前进的文法与完整输入契约。

解析器分层表达保存独立卡片。

原书依据 · 1 处

前瞻检查区分可选与必需

一标记前瞻让解析器在消费前查看下一个类型。原_accept(toktype)匹配才前进并返回True,不匹配则保持位置;_expect(toktype)要求必须匹配,否则抛语法错误。_advance负责更新当前与前瞻标记。这里没有恢复已消费输入的通用回溯机制,不能把“不前进”误写成已发生回退。

前瞻检查区分可选与必需保存独立卡片。

原书依据 · 1 处

文法层次决定运算优先级

把加减放expr层、乘除放term层、数字与括号放factor层,递归求子结果时就体现乘除优先。若把四种运算放同一重复层,3+4*5可能按从左到右得到35,而分层得到预期23。循环如何累积还决定结合方向;规则不是仅为代码好看,它限定表达式含义。

文法层次决定运算优先级保存独立卡片。

原书依据 · 1 处

同一语法可求值或构树

解析规则可以直接计算数值,也可构建保存运算结构的元组树,如加号节点含左右子结果。ExpressionTreeBuilder复用ExpressionEvaluator的解析控制,并改写expr、term、factor的结果构造。

结构图:

classDiagram
    ExpressionEvaluator <|-- ExpressionTreeBuilder
    class ExpressionEvaluator {
        +parse(text)
        +_advance()
        +_accept(toktype) bool
        +_expect(toktype)
        +expr()
        +term()
        +factor()
    }
    class ExpressionTreeBuilder {
        +expr()
        +term()
        +factor()
    }

图采用原例声明和调用表达的复用意图;源文本缩进有错误,不声称原样可运行。parse负责取得解析结果,数值与树是不同结果契约;这种继承不证明期待数值的调用方可以无差别替换成构树器。

同一语法可求值或构树保存独立卡片。

原书依据 · 1 处

朴素下降不能直接处理左递归

规则若在消费任何输入前再次调用自身,如items先调用items,朴素递归下降就会无限递归。可把合适的重复结构改写为先消费基础项再循环,或采用支持相应文法的专门算法。这个限制针对原例直接调用方式,不能扩大为任何递归下降或现代解析器都绝不支持左递归。

朴素下降不能直接处理左递归保存独立卡片。

原书依据 · 1 处

完整解析须确认标记已消费

若目标是验证完整表达式,取得顶层规则结果后还应确认没有剩余标记。原parse直接返回expr结果,合法前缀后跟额外标记时可能未被拒绝;这是对已读代码的推导,尚未运行。词法层也要报告未识别的后缀,见分词需识别类型并覆盖输入;两层检查共同防止把局部成功当成完整合法。

完整解析须确认标记已消费保存独立卡片。

原书依据 · 1 处

PLY以规则生成解析流程

PLY以lex/yacc风格规则组织词法和语法处理:原例用正则定义标记,用处理函数的文档串写产生式,再由lex()、yacc()构建处理器。它把扫描和解析的部分控制交给库,语义动作仍由开发者定义。复杂语法可先研究这种成熟工具,不能把简单计算器例当作完整语言实现,也不默认本轮安装依赖。

PLY以规则生成解析流程保存独立卡片。

原书依据 · 1 处

2.20 在字节串上执行文本操作

字节串与文本有相似方法,却代表不同对象:一个元素是字节数值,文本元素则是字符。模式和替换也要匹配输入表示。格式化与文件名处理又带有版本和平台边界,不能把Python 3.3的所有报错沿用到现代环境。

字节操作需匹配输入表示

在bytes或bytearray上拆分、搜索与替换时,应提供匹配的字节参数;正则模式也要用字节形式,不能混用str模式与bytes数据。相似方法名不表示文本编码已被理解;bytearray可变也不说明所有方法原地修改。先决定处理原始字节还是字符,再选择解码边界与返回类型。

字节操作需匹配输入表示保存独立卡片。

原书依据 · 1 处

字节索引和格式化有独立语义

bytes按索引取元素得到字节整数,str取元素得到字符;打印bytes展示的是其表示,显示文字需要按明确编码解码。原书3.3中bytes不支持%格式化的报错已过时:%格式化自3.5加入,已查官方类型文档(2026-10-27)。这不等于bytes拥有str的format接口;文本格式化后编码仍是不同路径。

字节索引和格式化有独立语义保存独立卡片。

原书依据 · 1 处

文件名表示决定解码边界

在支持相应接口的平台,用bytes路径列目录可得到bytes名称,避免该处先解码成str;用文本路径则通常得到解码后的名称。应按真实文件系统编码与后续用途处理,不能把原例UTF-8字节或规范化结果推广为所有平台行为。原始文件名字节不是已经解释好的显示文本,转换仍需明确边界。

文件名表示决定解码边界保存独立卡片。

原书依据 · 1 处

第3章 数字、日期和时间

数值表示决定能精确表达什么,日期时间则还依赖日历和时区规则。Decimal并不消除所有舍入,浮点比较也需要误差语义;时间间隔、当地时间和绝对时刻不能随意替换。先明确领域含义,再选择运算和格式。

3.1 对数值进行取整

取整改变计算中使用的值,格式化则得到指定样式的文字。round的位数可正可负,中点采用就近偶数规则,但判定依据是实际表示值;它不能从根本上消除二进制表示误差。

取整规则不同于显示精度

需要数值按指定位置取整时,可用round(value, ndigits),负位数可指向十位或百位等;实际值恰在中点时采用就近偶数规则。十进制外观看似中点,不保证二进制浮点表示也恰在中点。若只要输出固定小数位,应格式化为字符串;事后round也不能替代对精度需求、累计误差和数值类型的判断。

取整规则不同于显示精度保存独立卡片。

原书依据 · 1 处

3.2 执行精确的小数计算

二进制float不能精确表示所有十进制小数,Decimal可以从十进制文本构造,并用上下文控制有效位数和舍入。十进制表示并不保证每次运算都无限精确;误差还取决于算法和累计顺序。

Decimal表达意图

需要十进制表示及明确精度、舍入规则时,可从文本构造Decimal,再用localcontext限定计算上下文,避免先经过已有二进制float误差。ctx.prec控制有效数字数目,不是小数点后固定位数;除不尽或超出精度时仍需舍入。选择它应来自真实数值契约,不表示所有运算都无限精确,也不代替业务舍入与范围规则。

Decimal表达意图保存独立卡片。

原书依据 · 1 处

浮点误差还取决于算法

同样的浮点数据,用不同算法或运算次序,误差可能不同。原例把巨大正值、小值与巨大负值顺序累加,小值可能在抵消前被舍去;fsum用于更稳健的求和,但不解决所有数值算法的误差传播。float精度讨论应看有效数字、量级和条件,不能把原书17位说成固定小数点后17位,也不能笼统忽略工程误差。

浮点误差还取决于算法保存独立卡片。

原书依据 · 1 处

3.3 对数值做格式化输出

数值格式把对齐、精度、千位分组和科学计数等输出要求组合起来。固定逗号分组不是自动本地化,替换符号也不等于实现完整地区格式规则;同一format思路在文本对齐部分已有主要讲解。

对齐格式应显式指定方向宽度关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

3.4 同二进制、八进制和十六进制数打交道

进制转换改变整数的文本表示,不会创建另一种整数类型。负号文本与约定位宽的补码又不同,必须先说明数值范围和位宽,才能解释二进制输出。

进制文本与固定位宽要分开

要输出或读取不同进制,可用bin/oct/hex生成带前缀文本,或format选b/o/x,再用int(text, base)按指定进制还原。负整数默认带负号,不是固定位宽补码。原例对相应负值加2**32,是在约定32位表示下计算无符号解释,不能当任意整数自动截断。Python八进制字面量用0o前缀,如0o755;这只是数值表示,不执行权限修改。

进制文本与固定位宽要分开保存独立卡片。

原书依据 · 1 处

3.5 从字节串中打包和解包大整数

整数与字节互转需要同时约定字节顺序和长度。相同字节按不同端序会变成不同数值;长度不足会溢出,而按最短长度编码也可能不符合固定字段协议。

整数编解码须明确字节序

将字节串解释为整数,可用int.from_bytes并明确大端或小端;反向to_bytes还需输出字节数。原例0x01020304用大端为01 02 03 04,小端为04 03 02 01,变的是传输排列而非整数值。固定struct字段也可分高低字再组合大整数,但字段宽度与顺序必须一致,不能按本机习惯猜测外部协议。

整数编解码须明确字节序保存独立卡片。

原书依据 · 1 处

整数打包宽度须满足范围

把整数打包到固定字节数时,容量不足会失败,不能靠格式化文本绕开。对非负无符号值,可用(bit_length+7)//8求最少字节数;零长表示是否允许仍由协议决定。固定字段协议需要按约定宽度填充并校验范围,而非总用最短长度;负数还需另定符号约定,本例不提供通用有符号打包方案。

整数打包宽度须满足范围保存独立卡片。

原书依据 · 1 处

3.6 复数运算

复数显式表示实部与虚部,j表示平方为-1的虚数单位。Python内建复数支持常见算术、共轭和模,复数函数则应选择cmath等支持相应定义域的实现,而不是假定实数函数自动返回复数。

复数函数须显式选择定义域

需要复数计算时,可用complex(real, imag)或j后缀构造,real、imag取实虚部,conjugate取共轭,abs取模。实数与复数函数的定义域不同:math.sqrt(-1)在原例报域错误,cmath.sqrt(-1)则得到虚数单位。应明确数据与函数的复数支持,不能因为某库有数学函数就假定它支持所有复数操作。

复数函数须显式选择定义域保存独立卡片。

原书依据 · 1 处

3.7 处理无穷大和NaN

无穷大和NaN是特殊浮点值,普通算术可能把它们继续传下去而不直接失败。检测应使用表达数值性质的函数,尤其不能用与NaN相等来判断NaN;还需避免把示例传播规律扩大到每个API。

特殊浮点值须按性质检测

处理可能出现无穷大或NaN的结果时,可用isinf/isnan显式检测。NaN与自身的普通相等比较也为False,不能用x == float("nan")识别它。某些无效运算如无穷大相除会产生NaN,常见算术也可能继续传播;但不能据此断言所有函数都不会抛错或一定返回NaN,应按实际操作定义处理。

特殊浮点值须按性质检测保存独立卡片。

原书依据 · 1 处

3.8 分数的计算

有理数以整数分子和分母保存比例,能直接表达分数算术。限制分母则是另一个近似目标,从float转换还原的也只是已保存的数值,不会自动找回输入时的十进制意图。

分数精确表示与近似要分开

需要按整数比例计算,可用Fraction保存分子与分母,运算结果仍可查看这两部分。limit_denominator限制分母是在寻找近似值,不保证数值不变;转float也需接受其表示能力。从float.as_integer_ratio构造分数,得到的是该浮点数实际保存值的精确比例,不等于恢复用户原先想输入的十进制小数。

分数精确表示与近似要分开保存独立卡片。

原书依据 · 1 处

3.9 处理大型数组的计算

NumPy数组按统一dtype解释多维元素,运算通常逐元素进行,与列表连接或重复不同。广播把形状兼容的输入用于同一运算,基础切片又可能共享数据;因此既要理解值如何计算,也要理解哪些操作修改原数组以及空间如何增长。

数组运算不同于列表连接

同样写+或*,列表可能连接或重复,而NumPy数组通常按元素计算,可把多项式或通用函数作用到整组数据。数组按dtype解释元素,结果与类型、形状有关,不能把数组乘法一概当矩阵乘法。向量化减少Python层逐项处理,但不保证任何输入都更快;需要结合数据规模和临时结果观察。

原例np.where(a<10, a, 10)按位置保留较小值,其余换成10,返回选择后的结果数组。

数组运算不同于列表连接保存独立卡片。

原书依据 · 1 处

广播须核对兼容形状

把标量或较小数组参与大数组运算时,广播可按兼容形状复用它。原例把四项向量加到三行四列数组,每行使用同一组列增量;并非任何不同形状都能相加。兼容条件从末维核对,相同或其中为1才可对齐,已据官方广播文档核验(2026-10-27)。概念上的扩展也不等于必须先复制整块输入。

广播须核对兼容形状保存独立卡片。

原书依据 · 1 处

NumPy基础切片可共享原数据

对数组取基础切片可得到共享存储的视图,原例对子区域+=10会改变原数组;若需要独立数据,应明确复制。普通a+向量产生结果而不改a,与原地更新不同。此边界已据官方视图文档核验(2026-10-27);不能把所有索引结果都当视图,也不能把所有数组都视为连续布局。

NumPy基础切片可共享原数据保存独立卡片。

原书依据 · 1 处

数组容量须算上结果与临时量

大型数组即使能紧凑存储,也需预算元素数、每项字节数与中间结果。教学估算:10000×10000共有一亿项,若每项8字节,仅数据区约800MB,额外输出和临时数组还会增加占用。原书“根本不是问题”不构成任意环境容量保证;分块、原地操作或输出策略要按实际契约选择。

数组容量须算上结果与临时量保存独立卡片。

原书依据 · 1 处

3.10 矩阵和线性代数的计算

线性代数的矩阵乘法与逐元素数组运算不同,选择对象与函数时需要先说明含义。本书用matrix展示转置、逆和乘法,并调用linalg求行列式、特征值及方程解;今天不应据此把matrix当作默认新建方式。

线性代数须明确运算对象语义

处理矩阵时,要区分逐元素运算与线性代数运算。原matrix示例以*作矩阵乘法,T表示转置,I表示逆,linalg还提供行列式、特征值和solve方程求解;能否求逆或求解仍取决于矩阵性质。现代NumPy官方文档已不建议新用matrix,推荐普通数组(2026-10-27核验);不能把原matrix的*语义直接搬给ndarray。

线性代数须明确运算对象语义保存独立卡片。

原书依据 · 1 处

3.11 随机选择

随机选择与随机数生成要分别说明返回什么、会不会改变输入以及边界。随机种子用于控制确定性序列,不代表加密不可预测性;书中具体输出只是示例,不是应重复出现的结果。

抽样与洗牌的修改语义不同

从非空序列取一个元素可用choice;sample返回无放回抽样的新列表,并不把原序列中的元素删除,重复值的不同位置仍可分别被选中。shuffle则原地打乱次序。已据官方random文档核验这些区别(2026-10-27),不能把无放回误写成输入被修改。

抽样与洗牌的修改语义不同保存独立卡片。

原书依据 · 1 处

随机数接口须说明范围

生成随机值时先明确范围:randint(a,b)包含两个整数端点,random()的浮点范围是[0,1),getrandbits(k)给非负随机比特值而不保证最高位为1。不同分布也不是同一接口的别名,uniform与gauss分别服务不同分布。书中几次输出只用于展示调用,不是概率或均匀性的实测证明。

随机数接口须说明范围保存独立卡片。

原书依据 · 1 处

随机种子控制确定性序列

伪随机算法按状态产生确定性序列,设定种子有助于复现,但调用顺序、并发和版本都会影响复现范围,不能承诺全部API跨版本输出不变。Mersenne Twister适合一般随机模拟,却不满足密码用途的不可预测性;此边界已查官方文档(2026-10-27)。本轮未生成安全令牌或替换随机源。

随机种子控制确定性序列保存独立卡片。

原书依据 · 1 处

3.12 时间换算

timedelta表达以天、秒和微秒为基础的时长;datetime表达具体时间点。规范化后的seconds只是日内余项,总量要用total_seconds。日历月长度变化,因此月份运算需要不同于固定时长的规则。

时长余项不同于全部秒数

处理时间间隔时,timedelta可累加天、小时等固定单位。days与seconds是规范化分量,seconds不包含已经折入days的部分;需要全间隔的秒数应使用total_seconds。具体日期可与时长相加减,闰年由日历规则处理;不能把一个分量误当总时长,也不能把无时区示例自动推广为跨时区真实经过时间。

时长余项不同于全部秒数保存独立卡片。

原书依据 · 1 处

日历月不能用固定天数替代

按月推进日期时,月份的天数可变,timedelta因此不接受months。dateutil.relativedelta可表达按日历月变化,或把两个日期的差分解为月与日;这与固定总天数是不同描述。应先说明要日历位置变化还是固定时长,遇到月末还需按相应日历规则判断,不能统一写成加30天。

日历月不能用固定天数替代保存独立卡片。

原书依据 · 1 处

3.13 计算上周5的日期

计算“上一次星期几”前,要先决定是否允许今天。原函数用星期编号差取模,并把零改为七,因此严格回到此前一周;dateutil的weekday相对规则在已经同星期时可能不移动,并不是无条件同义替代。

上次星期几须定义是否含今天

找严格早于起点的上一次目标星期,可用星期编号差模7,再把0改为7,得到应回退的1至7天。原函数返回datetime并保留起点时分,不自动变午夜。dateutil的FR(-1)在当天已是周五时可保持当天,已据官方relativedelta说明核验(2026-10-27);比较两种方法前必须先对齐是否含今天的契约。

上次星期几须定义是否含今天保存独立卡片。

原书依据 · 1 处

3.14 找出当月的日期范围

本月范围可以定义为月初到下月月初的左闭右开区间,不必先创建日期列表。关键前提是输入先归一化到月初;逐步迭代还需保证步长让过程向终点前进,原例并非完整支持正负步长的range替代。

月份范围须先归一化月初

要遍历整个月,可先把日期归一化为本月1日,再按该月天数得到下月1日,以[start,end)迭代。原get_month_range只在未传参数时归一化,直接传月中日期会得到月中到下月中,不能满足它宣称的任意输入月范围。monthrange返回月初星期编号和天数,前项不是第一个工作日日期;replace参数为day,不是days。

月份范围须先归一化月初保存独立卡片。

原书依据 · 1 处

日期迭代须保证向终点前进

用生成器每次输出当前日期再加step,可避免先保存全部结果。原date_range以start为循环条件,只适合递增且能前进的步长;零步长会不终止,负步长也未提供对应的逆向判断。还需明确终点是否包含及返回date还是datetime,不应把这个简例当成完整的内建range语义。

日期迭代须保证向终点前进保存独立卡片。

原书依据 · 1 处

3.15 将字符串转换为日期

解析日期与输出日期是两个方向:strptime按格式解释输入,strftime按规则形成文字。自己按分隔符解析时,构造datetime可检查日历值,但文本宽度和其他允许形式仍需要单独定义;性能也须与目标格式契约一起比较。

日期解析须定义格式与有效性

把日期文本变成datetime可用strptime声明格式,再用strftime形成需要的输出。若为固定格式改用split和int,datetime构造会检查日历值,却不自动强制文本恰为YYYY-MM-DD宽度,空白等形式也需另定。月份和星期的文字输出可能受区域设定影响;原书七倍计时只是特定环境例,不能用速度结论替代格式与错误契约。

日期解析须定义格式与有效性保存独立卡片。

原书依据 · 1 处

3.16 处理涉及到时区的日期问题

墙钟读数必须先有时区解释,才能转换为同一瞬间在其他地区的表示。夏令时使本地时钟的连续性与真实经过时长不同,原pytz例需normalize或经UTC计算;现代zoneinfo采用另一套接口,不能机械搬用旧库方法。

时区先本地化

无时区的年月日时分只是一组墙钟读数,需先明确它代表哪个地区的规则,才能转换为其他地区同一瞬间的表示。本书pytz用localize建立这种解释,再用astimezone转换。现代标准库zoneinfo自3.9提供IANA时区支持,已查官方文档(2026-10-27);它不照搬pytz的localize/normalize接口,“几乎任何问题都应使用pytz”不再作为当前结论。

时区先本地化保存独立卡片。

原书依据 · 1 处

本地时间加法须定义经过时长

跨夏令时转换时,想表达真实经过一段时间,可先转UTC运算再转回当地显示,避免把跳过的墙钟时间误当有效结果。原pytz示例也提供normalize修正路径,但不同库的算术语义不能混用。UTC有助表示瞬间与经过时长,却不替代每天当地某时等日历计划的规则选择,也不会消除输入时区的歧义。

本地时间加法须定义经过时长保存独立卡片。

原书依据 · 1 处

时区名称不等于固定偏移

地域时区名称标识随日期变化的规则,单个数值偏移只是某一时刻的结果。原US/Central例从-06:00变为-05:00,说明仅保存一个偏移不能表达全年地区规则。国家码查询返回的是名称列表,选择还需要地点与业务语境;不能把国家、时区名和固定小时差视为同一概念。

时区名称不等于固定偏移保存独立卡片。

原书依据 · 1 处

第4章 迭代器和生成器

迭代器是逐次提供值的协议,生成器是保存暂停位置的一种实现。遍历、切片、排列组合、合并和管道分别重组这个取值过程。惰性减少不必要工作,却延长了状态与资源的生命周期,消费顺序和耗尽条件因此成为接口的一部分。

4.1 手动访问迭代器中的元素

可迭代对象提供取得迭代器的入口,迭代器保存下一步消费的位置。手工next时还要决定怎样识别结束;默认值只有与合法数据不冲突时才可直接用作结束标记。

迭代协议分离容器

可迭代对象与迭代器承担不同角色:iter取得遍历状态,next推动状态并产生下一个值,结束以StopIteration表示。容器可产生自己的迭代器,消费方不必知道底层来自列表、文件或生成器;可迭代对象本身却不一定能直接next。迭代器通常单次消费,不能把再次迭代等同于自动重置。

迭代协议分离容器保存独立卡片。

原书依据 · 1 处

手动迭代须区分结束与有效值

不用for而手动next时,可捕获StopIteration,或指定耗尽时返回的默认值。原文件行示例用None识别结束,因为正常行是字符串;若数据本来允许None,就应选与有效值明确不同的标记。需要精细消费控制时这很有用,但不能为省异常处理而把某个合法值误当结束。

手动迭代须区分结束与有效值保存独立卡片。

原书依据 · 1 处

4.2 委托迭代

自定义容器若只是希望逐项访问内部内容,可让iter直接返回内部容器的迭代器。Node示例仅把请求交给_children,因此循环取得直接孩子,不隐含整棵树的递归遍历。

容器迭代可委托内部对象

让自定义容器可迭代时,iter可直接返回内部对象的迭代器,把推进与结束交给既有实现。原Node的_children保存孩子,for node in root只访问直接孩子,不自动包含自身或后代。

结构图:

classDiagram
    class Node {
        +__init__(value)
        +add_child(node)
        +__iter__()
    }
    Node o-- "*" Node : _children保存引用

聚合不表示独占子节点生命周期;iter返回_children的迭代器,未补造具体返回类型名。Self大小写与方法缩进在源文本有排字问题,图表达已读说明和调用的设计意图。

容器迭代可委托内部对象保存独立卡片。

原书依据 · 1 处

4.3 用生成器创建新的迭代模式

生成器函数的调用先创建可推进的对象,函数体随next运行到yield暂停,并在下次请求时继续。保存局部执行状态让自定义遍历较容易表达,但步进范围仍需保证前进和终止。

生成器保存流程

生成器用yield产出一个值并暂停,局部变量与执行位置保存在其执行帧里,下次next再继续。调用生成器函数通常先得到生成器对象,函数体不会立刻完整执行;正常返回表示结束。它让遍历逻辑保持顺序写法,却不保证内存恒定,暂停帧仍可能持有较大的对象。

生成器保存流程保存独立卡片。

原书依据 · 1 处

浮点步进迭代须能实际前进

用生成器产生浮点范围时,原frange在x时yield再累加increment。步长必须让当前值实际向终点前进:零、错误方向,或浮点加法后数值不变,都可能破坏终止。浮点累计还可能改变边界是否命中,因此不能把它当成整数range所有语义的直接延伸;该边界由已读循环与前述浮点表示机制推导。

浮点步进迭代须能实际前进保存独立卡片。

原书依据 · 1 处

4.4 实现迭代协议

深度优先遍历可先产生当前节点,再委托各子树;生成器的暂停状态替代了手工管理多个迭代器的工作。显式DepthFirstIterator展示相同协议需要保存的节点、孩子和子树状态,两种形式都依赖所遍历结构的前提。

两种遍历实现共享迭代协议

先yield自身,再yield from各孩子的depth_first,可表达先序深度遍历。生成器保留暂停状态;显式迭代器则需维护当前节点、孩子迭代器和正在处理的子树,iter返回自身,next逐步推进。

结构图:

classDiagram
    class Node {
        +add_child(other_node)
        +__iter__()
        +depth_first() DepthFirstIterator
    }
    class DepthFirstIterator {
        +__init__(start_node)
        +__iter__() DepthFirstIterator
        +__next__()
    }
    Node ..> DepthFirstIterator : 显式版本创建
    DepthFirstIterator --> Node : 保存起点引用

图只画原文第二个显式迭代器版本,未把生成器版本的返回值也写成该类。原例按无环树遍历,未处理循环引用或去重;源码多处缩进排字有误,保留协议与状态机制,不声称原样可运行。

两种遍历实现共享迭代协议保存独立卡片。

原书依据 · 1 处

4.5 反向迭代

反向迭代需要能以相应顺序取得值,不能只因为对象有长度就断言支持。自定义反向入口可直接生成所需顺序;先转列表则增加一次完整消费与存储。

反向迭代须有可用访问协议

反向遍历可用reversed,输入需提供reversed,或支持长度加整数下标的序列协议;仅能求长度还不够,已查官方内建函数文档(2026-10-27)。自定义反向入口可直接生成结果;把普通迭代器先收集为列表再反转,需要完整消费与额外空间,不适用于无限流。

反向迭代须有可用访问协议保存独立卡片。

原书依据 · 1 处

4.6 定义带有额外状态的生成器函数

生成器的局部状态不必都隐藏在函数里。把生成器放进类的iter,可以通过属性暴露历史、通过方法控制它,同时保留消费接口;类实例与实际返回的迭代器仍是不同对象。

状态观察与迭代推进可分离

需要在遍历时观察额外状态,可让类保存历史或控制方法,并在iter里用yield产生值。linehistory先把当前行写入history再yield,因此历史包含当前行;这与先yield再追加的1.3示例不同。

结构图:

classDiagram
    class linehistory {
        +__init__(lines, histlen=3)
        +__iter__()
        +clear()
    }
    class deque
    linehistory o-- deque : history

实例本身没有next,手动消费先iter(lines)。多个迭代器仍可共享对象历史与底层来源,不能自动当成独立快照。图保留真实类型和构造参数,聚合表示可观察引用。

状态观察与迭代推进可分离保存独立卡片。

原书依据 · 1 处

4.7 对迭代器做切片操作

islice以消费的方式取得迭代流的某一段,跳过前部也必须推进底层来源。它适合不提供下标切片的生成器,却不提供随机定位或回看;能否回看需要另行保存数据。

迭代切片会推进底层来源

生成器没有普通下标切片接口时,可用islice(it,start,stop)顺序取得一段。它要先访问并丢弃前面的元素,再逐项产生目标段,因此不是常数时间随机跳转,也不能恢复已消费内容。若要重复读取,应有重新构造来源或保存结果的策略;先转列表只适合规模可控的有限输入,不能因未知长度就无限收集。

若只知道要跳过前N项而保留其余,可把stop设为None,例如islice(items,3,None)对应从第3个下标继续到结束,不是只取前三项。

迭代切片会推进底层来源保存独立卡片。

原书依据 · 2 处

4.8 跳过可迭代对象中的前一部分元素

按条件跳过开头,与在全流中过滤有不同语义。dropwhile第一次遇到假条件后就停止筛选,之后全部保留;已知数量则可用islice从某位置一直到结束。

迭代切片会推进底层来源关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

跳过前缀不同于全流过滤

要丢掉满足条件的开头一段,可用dropwhile:只要条件为真就跳过,第一次为假起连同后续所有元素一起返回,不再逐项过滤。跳过开头注释因此不同于删除文件所有注释。若输入始终满足条件,有限输入会全被消费,无限输入则可能一直等不到输出;选择前要明确真正需要前缀跳过还是全流筛选。

跳过前缀不同于全流过滤保存独立卡片。

原书依据 · 1 处

4.9 迭代所有可能的组合或排列

排列与组合解决不同枚举目标:排列计顺序,组合忽略选择顺序,可重复组合再允许同一位置多次选取。函数按输入位置处理,不会自动按值去重,结果流式产生也不减少候选总数。

排列组合须明确顺序与重复

枚举前先定义顺序与重复:

  • permutations列出有序选择,可指定长度。
  • combinations忽略选择顺序,同一位置不重复选。
  • combinations_with_replacement允许同一位置多次选择。

位置不同但值相同的输入仍可能产生相同值元组,不会先做值去重。这些是枚举而非随机抽样,也不修改原输入;按迭代产生结果仍可能面对迅速增长的候选总量。

排列组合须明确顺序与重复保存独立卡片。

原书依据 · 1 处

4.10 以索引-值对的形式迭代序列

enumerate把推进的序号与原值配对,起点可以按用户行号习惯设为1。返回的值本身若也是元组,需要保留第二层解包结构;编号也应明确是消费序号、行号还是其他实际位置。

编号迭代须说明起点与结构

遍历时需要序号和值,可用enumerate,默认从0计,显示文件行号时可显式从1起。每次返回(序号,原值),若原值是二元组,应写n, (x,y),而非把外层当三个元素。这个序号是当前消费顺序,不自动等于字节偏移;同一词在一行出现多次时,索引列表也可能重复该行号,去重需要另定规则。

编号迭代须说明起点与结构保存独立卡片。

原书依据 · 1 处

4.11 同时迭代多个序列

zip按位置同时推进多个来源,每步产生一个元组;默认在最短来源耗尽时结束。zip_longest改为持续到最长并填补缺项,因此选哪一种取决于如何理解长度差和缺失。

配对迭代须明确长度差策略

把多路数据按位置配对,可用zip;默认遇到最短输入结束,较长尾部不会在结果里出现。需保留长侧可用zip_longest并指定填充值,但要区分填充值与真实数据,且无限来源不会因此自然结束。若业务要求等长,应明确验证,不能让默认截断掩盖错配。结果是单次消费的迭代器,构建字典或列表时也需考虑各自的键与容量规则。

配对迭代须明确长度差策略保存独立卡片。

原书依据 · 1 处

4.12 在不同的容器中进行迭代

chain把多个来源接成一个连续消费序列,不必先创建合并容器。它不交错来源,也不把原来无序的容器变成有序或去重结构;应保留输入各自的语义。

顺序连接来源不必先合并容器

要对多个来源的元素执行同一处理,可用chain先消费第一路,再依次消费后续路,而不先用+构造一个合并序列。来源可属于不同容器类型,连接也不会自动排序或去重;前一路若无限,后续路可能永远到不了。它简化统一处理并减少不必要复制,内存与性能仍取决于来源和消费者。

顺序连接来源不必先合并容器保存独立卡片。

原书依据 · 1 处

4.13 创建处理数据的管道

生成器管道让不同阶段各自发现、打开、展开与过滤数据,末端消费者需要一项时才推动上游。数据流与执行拉取方向相反,避免全量中间列表有助控制占用;打开的资源还需要独立退出契约。

管道按需取数

把发现文件、打开、展开行、筛选和转换拆成生成器阶段,末端消费者每次请求才推动上游,便于组合并避免全量中间列表。

结构图:

flowchart TD
 A[gen_find发现文件] --> B[gen_opener逐个打开]
 B --> C[gen_concatenate展开行]
 C --> D[gen_grep筛选]
 D --> E[提取并转换字节列]
 E --> F[sum消费聚合]

箭头表示数据方向,执行由sum向上游拉取;节点是函数阶段而非代码类型。占用仍由各阶段状态、单项大小及消费者决定,不能保证任意管道恒定内存。

管道按需取数保存独立卡片。

原书依据 · 1 处

参数展开可能破坏惰性与生命期

原例的文件生成器在取得下一文件前关闭上一文件。若调用chain(*files),参数展开会先耗尽files,等开始读行时,先前对象已可能关闭。问题在提前展开与资源生命周期的组合,而非chain绝不能读文件。应逐个取得并消费子迭代器,保持使用发生在其有效期内,不先收集整批打开对象。

参数展开可能破坏惰性与生命期保存独立卡片。

原书依据 · 1 处

生成器资源须考虑提前终止

在yield之后才写f.close,只能保证恢复并执行到该处时发生关闭。消费者提前停止、异常或放弃迭代时,这条路径可能未走到;原例不因此自动具备全部退出路径的清理保证。资源拥有者需明确安排退出时关闭,不能仅靠继续取下一项或等待回收。这是对原例控制流的推导,尚未执行故障试验。

生成器资源须考虑提前终止保存独立卡片。

原书依据 · 1 处

4.14 扁平化处理嵌套型的序列

扁平化递归下降到嵌套来源,并逐项交出叶子;什么是叶子需要显式定义,否则字符串也会被继续展开。yield from简化委托,并不会自动解决循环引用或无限来源的问题。

扁平化须定义不可再分的叶子

递归生成器可把嵌套可迭代来源展开为单值流:遇到允许展开的对象就递归并用yield from交出其结果,否则产出叶子。字符串与字节串通常应视为叶子,用ignore_types排除,不能只因可迭代就无限拆分。字典默认会展开键;循环引用、极深嵌套与无限来源还需要另外约束。

原书从collections导入Iterable属旧接口,现代应显式从collections.abc导入;官方迁移说明记录旧别名在3.10删除(核验2026-10-27)。

扁平化须定义不可再分的叶子保存独立卡片。

原书依据 · 1 处

4.15 合并多个有序序列,再对整个有序序列进行迭代

有序合并只需保留各路当前候选,从最小项所属来源再取下一项,因而不必预先装载所有输入。代价是每路输入的有序性已由上游保证,合并函数不会替调用方排序或验证。

惰性有序合并依赖输入已排序

多路输入已按同一规则有序时,heapq.merge可逐项产生整体有序结果,无须先合成大列表再排序。它比较各路当前候选,输出最小项后只推进那一路;输入若乱序,结果也可能乱,函数不会先检查或修复。文件逐行合并还要区分文本顺序与数值、时间等业务顺序,并让文件在消费完成前保持打开。

惰性有序合并依赖输入已排序保存独立卡片。

原书依据 · 1 处

4.16 用迭代器取代while循环

双参数iter把重复无参调用与结束值判断组合为迭代器。哨兵既要匹配读取模式,也必须确实表示结束,否则正常数据会被误吞;循环体还应使用本次产生的值。

可调用迭代须约定结束哨兵

iter(callable,sentinel)重复调用无参对象,返回值与哨兵相等时停止,该值不交给循环体。lambda可封装需要块大小的read或recv。文本读到结尾返回空字符串,二进制则为空字节串,哨兵需匹配;正常结果若也可能等于哨兵,就不能靠此机制区分。原替代例遍历变量是chunk,处理也应使用chunk而非旧data;错误仍需调用方处理。

可调用迭代须约定结束哨兵保存独立卡片。

原书依据 · 1 处

第5章 文件和I/O

文件接口把字节存储、缓冲和文本编码分层。内存流、压缩流、映射文件和描述符暴露不同能力,不能假设每个文件型对象都有fileno或buffer。路径检查、临时资源、读写和关闭也有各自竞争及所有权边界。

5.1 读写文本数据

文本文件接口负责在字节与字符之间按指定编码转换;打开模式决定读取、覆盖或追加,with决定正常及异常离开时关闭。换行转换和错误处理是另外两项契约,解码没报错并不能证明文字解释正确。

编码属于边界

文本I/O在外部字节与程序str之间按编码转换;应根据数据协议显式指定encoding,而非猜测。sys.getdefaultencoding()并不是open默认文件编码的可靠查询:默认行为还受Python版本、区域与UTF-8模式影响,已查官方open说明(2026-10-27)。latin-1可解码任意字节,却不证明原文本就是该编码;ignore会丢数据,replace会替换错误,二者都不能修复错误的编码选择。

编码属于边界保存独立卡片。

原书依据 · 1 处

文本换行转换须显式约定

文本读取默认识别常见换行,并统一为\n;newline空字符串仍识别换行但保留原样。写出时默认把\n转换为系统行分隔符,newline空字符串或\n可禁止这种转换。编码正确与换行是否保真是不同问题;即便latin-1能逐字节映射字符,未经控制的换行或内容处理也会破坏字节往返。

文本换行转换须显式约定保存独立卡片。

原书依据 · 1 处

文件模式与关闭是不同契约

rt读取文本,wt会截断已存在内容,at追加;选择模式先明确是否允许覆盖。with在控制流退出其作用域时关闭文件,避免遗漏手动close的路径;它不会把多步写入变成事务,也不保证完整持久化。大文件若只需逐行处理,可迭代读取而不先read全部;容量仍取决于单行和处理逻辑。

文件模式与关闭是不同契约保存独立卡片。

原书依据 · 1 处

5.2 将输出重定向到文件中

print的file参数选择接收文本的输出对象,除了文本接口之外还必须具备写权限。原示例rt只允许读取,无法满足此条件。

打印重定向须可写文本流

print(…,file=f)把格式化后的文本写入指定输出对象;目标需提供可用的文本write能力。普通文件应选允许写入或追加的文本模式,原例rt是只读模式,不能因带有t就能打印。二进制流不能直接接收print写出的str;应先明确编码或使用文本包装,不把重定向与字节写入混为一谈。

打印重定向须可写文本流保存独立卡片。

原书依据 · 1 处

5.3 以不同的分隔符或行结尾符完成打印

print的sep控制多个参数之间的分隔,end控制整次调用的结尾。它会对参数作字符串表示,因此对混合类型行可比先join更直接,但不负责CSV转义等格式协议。

打印分隔符不等于序列化格式

print(*row,sep=“,”,end=“\n”)可把混合类型的一行按分隔符输出;sep位于参数之间,end只在该次调用结尾。join要求输入为字符串,必要时先显式转换。逗号拼接不会自动转义字段中的逗号、引号和换行,不能仅凭这种输出就宣称形成合规CSV;格式协议应由相应序列化工具承担。

按_order连接字段可保持声明顺序,却仍只是字符串拼接;字段中若含逗号、引号或换行,as_csv这个名字不会自动提供CSV转义。应与实际csv序列化接口衔接。

打印分隔符不等于序列化格式保存独立卡片。

原书依据 · 2 处

5.4 读写二进制数据

二进制接口读写字节而不作文字编解码,只有解释为文本时才需要编码边界。实现缓冲区接口的对象可直接提供其底层数据,但这种内存布局不能自动当作跨平台文件格式。

二进制避免拷贝

实现缓冲区接口的对象可以直接提供内存给二进制write,readinto也可把数据写入已有可写缓冲区,避免先构造完整bytes再复制的一部分开销。它不等于整个I/O路径零拷贝,也不消除编码、布局或平台差异。array原生整数的字长和字节序可能依平台变化;要交换文件须另定义稳定格式,而非把内存原样输出就认为可移植。

二进制避免拷贝保存独立卡片。

原书依据 · 1 处

二进制与文本须显式转换

rb读取bytes,wb写入支持字节缓冲区的对象,不会自动把str编码成字节。bytes单项索引和迭代给出整数,str单项则是字符字符串;要处理文字需显式decode/encode并选择正确编码。按固定字节数分块时也可能截断多字节字符,不能把每块都当独立完整文本;需要按协议组织边界或持续解码。

二进制与文本须显式转换保存独立卡片。

原书依据 · 1 处

5.5 对已不存在的文件执行写入操作

排他创建把“只在不存在时写入”的条件放进打开动作,避免先查存在再普通写入的窗口。它防止覆盖既有路径,但不等于后续整段写入有事务保证。

排他创建避免先查再覆盖

只允许新建文件时使用x模式,如xt或xb:路径已存在则打开失败,而w会截断原内容。先exists再w存在检查与使用之间的竞争窗口,不能可靠兑现“不覆盖”约束。排他创建约束的是创建动作;写入失败、部分内容与后续发布还需另定处理,不能把它当完整事务。

排他创建避免先查再覆盖保存独立卡片。

原书依据 · 1 处

5.6 在字符串上执行I/O操作

内存流让文本或字节数据具有文件式读写接口,便于把数据提供给只需要这些接口的函数。模拟的是接口而非系统资源,所以依赖文件描述符的代码仍不适用。

内存流只模拟所需文件接口

StringIO保存文本,BytesIO保存字节,并提供read、write、seek、getvalue等文件式操作,可用于构造测试输入或收集输出。读取位置会随消费前进,需要时显式回到起点;它们的内容仍占内存。二者没有真实系统文件描述符,不能只因像文件就替代要求fileno的管道、套接字或系统调用。

内存流只模拟所需文件接口保存独立卡片。

原书依据 · 1 处

5.7 读写压缩的数据文件

压缩层负责把压缩表示转成解压后的字节,文本层再负责字符编码;因此压缩格式、文本模式和编码是不同选择。包装已有流时还应确认谁负责关闭底层资源。

压缩与文本解码分属两层

gzip.open和bz2.open提供压缩文件接口:rt/wt读写文本并编解码,rb/wb处理解压后的字节;选择模式和encoding仍需遵循数据协议。compresslevel可调整压缩工作的程度,但压缩率与耗时要在目标数据上测量,不能只按级别保证结果。还可包装已有二进制文件对象,此时应确认底层对象的关闭责任。

压缩与文本解码分属两层保存独立卡片。

原书依据 · 1 处

5.8 对固定大小的记录进行迭代

按块读适合固定长度记录,但每次请求一个长度不等于每次都得到完整记录。iter与partial只简化重复调用,调用方仍要决定尾部不足如何处置。

固定记录读取须处理不足一条

iter(partial(f.read,N),b” “)若使用含空格哨兵会错误;二进制文件结束应以空字节串b”“为哨兵。每次请求N字节,末块可能不足N;若协议要求完整固定记录,应检测并报错或按协议处理,不能当正常记录。文本按字符读取与二进制按字节读取不同,也不能把文件方案无条件套到可能短读的网络接口。

固定记录读取须处理不足一条保存独立卡片。

原书依据 · 1 处

5.9 将二进制数据读取到可变缓冲区中

readinto把读到的数据填进既有缓冲区,返回值说明这次有多少字节有效。复用同一块内存可以减少分配,但也意味着保留旧引用或视图会观察到后续覆写。

缓冲区读取须按有效长度处理

readinto写入预分配可写缓冲区,必须用返回的实际字节数n界定有效内容;不足一条记录时,剩余位置可能仍是旧内容或初始零,不能整块当新数据。按getsize分配后再读也需检查文件是否变化及读取是否完整。原固定记录循环在n小于记录长时直接退出,会丢弃部分尾块;是否报错应按协议决定。

缓冲区读取须按有效长度处理保存独立卡片。

原书依据 · 1 处

内存视图共享数据也共享变化

memoryview可在支持缓冲区的对象上建立视图,切片仍引用同一数据;向可写视图赋值会改变原缓冲区,不必先复制整个内容。代价是所有使用者要协调生命周期与修改:缓冲区被复用后旧视图也看到新数据,保存快照需显式复制。零拷贝描述这一层的数据共享,不保证系统I/O没有其他拷贝。

内存视图共享数据也共享变化保存独立卡片。

原书依据 · 1 处

5.10 对二进制文件做内存映射

内存映射让文件区域通过虚拟地址按需访问,提供类似字节数组的索引,而不是先复制整个文件到Python缓冲区。映射权限、回写策略、原始描述符与共享访问的同步需分别管理。

mmap像字节数组

mmap把文件区域映射到虚拟内存,可用字节索引、切片或缓冲区视图随机访问;访问页面时由系统按需处理,不是先把整个文件装进Python数组。ACCESS_READ只读,ACCESS_WRITE可写回,ACCESS_COPY只改私有副本。映射不自动提供跨进程同步或事务。原例os.open得到的描述符还须单独关闭;with关闭映射不等于替它关闭原始描述符,已查官方文档(2026-10-27)。

mmap像字节数组保存独立卡片。

原书依据 · 1 处

映射视图的解释受布局约束

memoryview(m).cast(“I”)让同一映射字节按原生无符号整数解释,写视图会改原数据;它没有把文件转成新数组。整数宽度、字节序、缓冲长度与对齐等限制影响解释,原例四字节值只是当时平台结果。仍引用映射的视图也需在关闭前妥善结束使用,不能把任意文件当任意原生类型布局。

映射视图的解释受布局约束保存独立卡片。

原书依据 · 1 处

5.11 处理路径名

路径拆分、拼接与用户目录展开应使用理解目标路径语法的接口,而不是随意分隔字符串。路径计算只是表示处理,并不证明目标存在或可访问。

路径处理须匹配目标平台语法

basename/dirname拆分名称与目录,join组合部分,splitext拆后缀,expanduser显式展开用户目录。os.path采用运行平台的路径规则;在一台机器处理另一平台格式,应选择相应posixpath或ntpath,不能假定自动识别任意斜杠形式。已查官方说明(2026-10-27)。这些操作不自动证明文件存在,后缀也不保证内容格式。

路径处理须匹配目标平台语法保存独立卡片。

原书依据 · 1 处

5.12 检测文件是否存在

存在、文件类型、链接目标和元数据回答不同问题。检测的结果只能反映这次查询,权限和符号链接语义也会影响解释,不能当作后续操作必然成功的承诺。

路径检测不保证后续可操作

exists检测可访问的目标是否存在,isfile/isdir判断类型,islink判断链接本身,realpath解析路径,大小和时间可由元数据查询获取。断裂符号链接可使exists为假而islink为真;权限也可能使exists返回假,元数据查询则可能报错,已查官方说明(2026-10-27)。文件可在检查后改变,操作时仍须处理错误。

路径检测不保证后续可操作保存独立卡片。

原书依据 · 1 处

5.13 获取目录内容的列表

目录列表先给出条目名称,过滤类型或读取元数据需用它们相对被查询目录构成的路径。按后缀与按真实文件类型是两种筛选,结果也不是不可变化的目录快照。

目录名称与完整路径须分清

listdir给出指定目录的条目名,而非自动带目录前缀的路径;检查isfile、isdir或stat时,应与该目录正确拼接,避免误查当前工作目录。后缀、glob或fnmatch只能按名称规则筛选,不能证明条目确实是普通文件。元数据另查并处理条目消失或权限错误;名称的解码和显示也需要各自的边界规则。

目录名称与完整路径须分清保存独立卡片。

原书依据 · 1 处

5.14 绕过文件名编码

文件名编码与文件内容编码不同。某些平台可保留字节路径以绕过字符串解码,但这也是接口和平台契约,不能成为跨平台统一文件名规则。

字节路径保留名称原始表示

文件内容的encoding与文件名的文件系统编码分属两个边界。在支持字节路径的平台,给listdir等接口字节目录名可得到字节名称,用它们继续访问可避免强行按某编码解释。组合路径应保持类型一致,显示时再单独处理;字节路径支持与规范化规则依平台,不能把原Mac示例推广成所有系统的UTF-8或分解形式约定。

字节路径保留名称原始表示保存独立卡片。

原书依据 · 1 处

5.15 打印无法解码的文件名

代理转义保留无法按文件系统编码解释的字节,让程序仍能访问名称;显示该字符串则可能触发终端编码错误。诊断表示与真实访问名称应分开,不能把显示修饰当成改名或已恢复正确语言。

名称可往返不代表终端能显示

surrogateescape把某些不可解码字节保留为低代理区码点,可按相同机制还原字节供文件访问;它不是找回了被丢失的高代理,也不说明原名一定是latin-1。终端严格编码可能拒绝这类字符,可用repr的转义形式作诊断显示。若还原字节再按latin-1显示,得到的只是该显示选择,并不证明原始文字正确;实际访问继续保留原名称。

名称可往返不代表终端能显示保存独立卡片。

原书依据 · 1 处

5.16 为已经打开的文件添加或修改编码方式

文本I/O以文本包装层叠加在缓冲字节层和原始文件层之上。更换文本层涉及资源所有权,先detach可避免旧包装析构时误关共享底层;原包装随后不能再使用。

文本包装叠加在字节层之上

TextIOWrapper负责字符编解码,BufferedWriter等负责缓冲字节,FileIO关联原始文件描述符。下图表示原写入示例中的包装持有关系,并非三个类之间的继承。

结构图:

classDiagram
 class TextIOWrapper {
  +write(text)
  +detach()
 }
 TextIOWrapper --> BufferedWriter : buffer
 BufferedWriter --> FileIO : raw

二进制流可再包装文本层,但需要正确encoding;这些层职责不同,越过文本层访问字节也会越过其编码契约。

文本包装叠加在字节层之上保存独立卡片。

原书依据 · 1 处

更换包装须先分离底层所有权

直接用旧文本对象的buffer创建新包装并覆盖变量,旧对象释放时可能关闭共享底层,使新对象无法使用。detach会分离并返回底层缓冲,原包装失效;再给该缓冲建立新文本层,明确最终关闭责任。它不自动解决已有缓冲内容、解码状态或任意时刻切换编码的问题,更不应为演示随意更改实际stdout。

更换包装须先分离底层所有权保存独立卡片。

原书依据 · 1 处

5.17 将字节数据写入文本文件

通过文本对象的buffer可绕过编解码层访问字节,但是否存在该属性要由对象接口确定。混用缓冲层还需要明确先后和位置,不能当成无条件的通用流写法。

绕过文本层须确认缓冲接口

文本流write接收str;标准输出在具备buffer时可用其字节接口输出bytes,绕过文本编解码。被替换为StringIO等对象的stdout未必有buffer,不能无条件访问。混用文本层和底层字节操作还要协调缓冲与位置,必要时先flush,避免看起来与调用顺序不同;直接buffer读取也不会替文本解码状态作通用同步。

绕过文本层须确认缓冲接口保存独立卡片。

原书依据 · 1 处

5.18 将已有的文件描述符包装为文件对象

整数文件描述符标识已打开的系统通道;open可给它加高层文件接口,closefd控制包装关闭时是否关闭底层。该选择只划分所有权,并不复制通道或消除平台与缓冲限制。

包装描述符须明确关闭责任

open(fd,mode)可包装已经打开的整数文件描述符,默认关闭包装时也关闭fd;closefd=False保留底层给原拥有者管理。新包装不会自动复制独立通道,多个包装共享底层时需协调缓冲、位置和关闭。普通文件与socket描述符跨平台行为不同;socket文件接口应按makefile等适合平台的契约处理,不能用历史性能断言代替验证。

包装描述符须明确关闭责任保存独立卡片。

原书依据 · 1 处

5.19 创建临时文件和目录

临时资源既要避免创建时覆盖或冲突,也要安排退出清理。高层临时文件与目录接口替调用者管理常见生命周期;低层mkstemp/mkdtemp把更多责任交还给调用者。

临时资源须选择清理责任

TemporaryFile提供用后关闭的临时文件,NamedTemporaryFile另提供可传递的名称,TemporaryDirectory管理临时目录及清理。with让退出时执行相应清理;写后要读仍需seek回起点。保留命名文件如delete=False时,应另定删除责任。mkstemp返回描述符和路径,mkdtemp返回路径,低层结果需自行管理,不能只取一个名字就认为资源会自动消失。

临时资源须选择清理责任保存独立卡片。

原书依据 · 1 处

临时路径不是跨平台访问保证

tempfile可用prefix、suffix、dir定制名称及目录,实际默认位置可查gettempdir,不应硬编码原示例系统路径。是否有可见名称、能否由其他代码再次打开、何时删除和权限受平台及接口选项影响;需要外部程序访问时,先确认命名和关闭契约。创建时防竞争不等于任意跨用户访问或崩溃后清理都自动成立。

临时路径不是跨平台访问保证保存独立卡片。

原书依据 · 1 处

5.20 同串口进行通信

串口传输字节,设备双方须约定端口、波特率、数据位、校验和停止位,必要时再加超时与流控。库封装可以减少系统差异,但不能代替硬件协议和阻塞条件的明确约定。

串口通信须对齐参数与字节协议

串口读写需要匹配设备的波特率、数据位、校验及停止位;发送文本前按设备协议编码,并约定命令终止符。pySerial封装read/write、超时、流控与握手等能力,但端口名称和支持选项依系统与设备。readline还需终止符或超时策略,避免把等待误当完成;历史整数端口例不当现代通用调用。pySerial API已核验(2026-10-27)。

串口通信须对齐参数与字节协议保存独立卡片。

原书依据 · 1 处

5.21 序列化Python对象

pickle把对象状态编码成Python可恢复的字节,并能在同一流中按序保存多项。恢复依赖可用的代码与受信任输入;资源本身不能简单冻结,能保存的状态和重建副作用必须分清。

对象序列化依赖代码与格式契约

pickle的dump/load面向文件,dumps/loads面向内存字节;多个对象可依次写入并按相同顺序读回。函数、类等通常按可导入的名称关联,不把整份实现封进数据,因此恢复需要兼容代码、协议与状态设计。长期存储或跨语言交换还需评估更独立的格式;代码改变不必然让所有旧pickle失效,但应显式管理演化与迁移。

对象序列化依赖代码与格式契约保存独立卡片。

原书依据 · 1 处

反序列化不能信任任意输入

pickle恢复对象时可能导入模块并执行重建逻辑,所以不能对不受信任的数据load/loads;“内部系统”也不自动等于可信来源。它是可触发代码执行的对象重建机制,不是单纯的被动文本解析。来源认证与输入控制必须在重建前成立,不能先加载再判断对象是否安全。

反序列化不能信任任意输入保存独立卡片。

原书依据 · 1 处

恢复状态不等于保存运行资源

打开文件、线程、连接等运行资源不能简单作为pickle状态保存。可用getstate选择可序列化的必要状态,再由setstate重建资源。倒计时例保存剩余计数,加载时重新启动线程,恢复的是数值与行为安排,而非原线程、栈或精确时序;保存期间的并发一致性和重建副作用也需另约定。

恢复状态不等于保存运行资源保存独立卡片。

原书依据 · 1 处

大对象序列化效率须看协议

序列化大数组时要考察复制量、格式、对象类型和收发双方能力。原书对pickle大数组效率的判断有版本背景:协议5自3.8支持带外缓冲,但对象提供者与消费者都需配合,并非所有pickle自动零拷贝,已查官方文档(2026-10-27)。是否选分块文件或HDF5应按需求验证,不能据旧结论直接排除当前方案。

大对象序列化效率须看协议保存独立卡片。

原书依据 · 1 处

第6章 数据编码与处理

外部数据格式是契约:CSV涉及字段,JSON涉及类型映射,XML涉及树及命名空间,二进制涉及布局和长度。编码成功不等于业务有效,解析成功也不等于输入可信;应把增量处理、校验及资源界限明确组织起来。

6.1 读写CSV数据

CSV先解决字段分隔、引号和行的表示,再由应用决定字段名、类型与缺失值。位置行、命名元组和字典行是访问方式的选择,不能自动消除外部数据的结构和合法性校验。

CSV是外部契约

CSV字段可能包含分隔符、引号或换行,应使用csv读写器而非简单split逗号。默认reader返回字符串列表,非原文所说元组;文件通常应以newline空字符串打开,让csv处理换行。字段名、缺失值、列数和类型转换仍需应用定义;DictReader与namedtuple只改变访问方式,不自动完成验证。官方说明已核验(2026-10-27)。

CSV是外部契约保存独立卡片。

原书依据 · 1 处

外部表头不自动适合命名字段

把CSV表头用作namedtuple字段前,需检查合法标识符、关键字、重复及前导下划线等限制。仅把非法字符换成下划线可能造成重名,也不保证全部合法。可建立显式字段映射或选字典访问,并保存原外部名称与内部名称的关系,不能静默清洗后假定身份不变。

外部表头不自动适合命名字段保存独立卡片。

原书依据 · 1 处

表格类型转换须验证列与值

csv默认值为字符串,转换成数值等类型要定义每列规则、空值及异常处理。zip转换函数与一行会默认按短侧截断,必须先保证列数符合契约,避免丢列而未报错。转换出浮点数也不等于适合所有金额语义;具体精度、范围与有效性由业务决定,原示例只演示转换安排。

表格类型转换须验证列与值保存独立卡片。

原书依据 · 1 处

6.2 读写JSON数据

JSON表达有限的数据类型,不自动携带Python类实现;元组、键类型和非有限数值等都需要明确转换契约。钩子可改变解析结果或编码表示,但自定义重建会引入另一层输入验证与类不变量问题。

JSON钩子承接类型

JSON把对象、数组和标量映射为Python数据;dumps/loads处理内存表示,dump/load处理文件。object_pairs_hook接收成员对,object_hook接收解析后的字典,default可将自定义实例变成可编码结构。钩子只提供转换入口,不自动验证类型、字段或版本;普通dict现有插入顺序保证,不能因旧例使用OrderedDict就认定现代dict一定丢序。

JSON钩子承接类型保存独立卡片。

原书依据 · 1 处

JSON往返不保留全部类型

JSON对象键是字符串,Python元组通常编码为数组再读成list,因此往返不保证原Python类型和键身份。编码器只支持规定的基本键类型,任意对象键并非都会自动转成字符串。顶层标量也是合法JSON,列表/字典并非唯一合规顶层;NaN等非有限数值与严格互操作另需约束,已查官方说明(2026-10-27)。

JSON往返不保留全部类型保存独立卡片。

原书依据 · 1 处

对象重建须验证字段与不变量

用类型名和字段字典重建对象时,应限制可选类并验证允许字段、类型与版本。直接new绕过init再setattr,不等于完成构造器的不变量检查;字段还可能覆盖标记或对象属性。原例return缩进在字段循环内会过早结束,必须先完成全部赋值;这仍是示意映射,不是可直接信任外部数据的通用对象加载器。

直接调用类的new只获得尚未完成常规初始化的实例;原Date此时没有year等字段。绕过init后须补齐完整且合法状态,子类new也可能有自己的参数与副作用。用setattr保留属性协议比直接写字典更通用,但它不代替验证,也不保证每个中间状态可用。

对象重建须验证字段与不变量保存独立卡片。

原书依据 · 2 处

数据展示与传输表示应分开

检查深层对象可用pprint改善可读性;JSON输出可用indent排版、sort_keys明确键排序。它们改变展示或输出形式,不验证数据语义,也不自动形成可签名的规范编码。若输入已经经object_hook变成普通自定义类,仍需default等编码规则,不能把漂亮打印与任意实例可序列化混同。

数据展示与传输表示应分开保存独立卡片。

原书依据 · 1 处

6.3 解析简单的XML文档

树式XML解析先构建元素层次,再相对某个元素查询子路径。标签、元素文本和属性值各有接口,路径是否匹配取决于起始节点与命名空间,而非只看末端名称。

XML查询相对于当前元素

ElementTree.parse构建文档树;从RSS根查channel/item,再从每个item查title等子项,路径含义取决于当前起点。tag是标签名,text是元素相关文本,get读取属性,不能把属性与子元素混用。find、iterfind、findtext对应不同结果用途;树式解析需容纳整树,数据过大可考虑增量方式。XML前提还包括命名空间与外部输入的适当处理。

XML查询相对于当前元素保存独立卡片。

原书依据 · 1 处

高级XML需求须核对实现能力

需要更完整XPath、XSLT或验证时,可考察lxml;它提供与ElementTree相近的树操作接口,便于复用部分解析写法。但相似API不等于所有边界和安全配置完全一致,也不保证任意工作负载都更快。选择解析器应依据需要的功能、输入与验证方式,而非把换导入视为无条件等价替换。

高级XML需求须核对实现能力保存独立卡片。

原书依据 · 1 处

6.4 以增量方式解析大型XML文件

增量XML解析把事件推进与已处理子树释放结合起来。end事件适合消费完整子元素,标签栈负责匹配所在路径,消费后从父节点移除能减少树中保留的数据;下游仍可能持有引用。

XML适合增量解析

iterparse逐步产生事件,end阶段可处理已完成子树;标签和元素栈可跟踪路径。处理后从父节点remove,才能避免树继续累积全部已处理节点;若消费者保留元素引用,内存仍不会立即释放。原例在yield恢复后才移除,提前停止时也不会自动走完;内存还受未匹配子树、单项大小和聚合结果影响,不能宣称任意文件恒定占用。

XML适合增量解析保存独立卡片。

原书依据 · 1 处

增量事件要区分结构与完成

XML的start事件适合记录进入节点,子元素及文本此时未必齐全;需要完整元素应在end时处理。start-ns/end-ns提供命名空间声明事件,与普通节点事件作用不同。原parse_and_remove跳过根的start,并用栈精确匹配相对路径;它不是完整XPath引擎,且直接匹配根子节点时取父栈下标的边界需要修正。

增量事件要区分结构与完成保存独立卡片。

原书依据 · 1 处

流式处理须比较总资源与吞吐

原XML计数例整树解析约450MB、增量约7MB,整树版又约快两倍,展示用更少保留状态换取额外管理开销的取舍。这些是原环境测量,不是当前性能承诺。评估时应同时记录输入规模、峰值内存、总耗时及聚合结果占用;流式不意味着每一步更快,也不能忽略下游Counter等增长。

流式处理须比较总资源与吞吐保存独立卡片。

原书依据 · 1 处

6.5 将字典转换为XML

用元素对象构造XML可把标签结构与文本值分开,再由序列化器转义文本。它免去手工拼字符串的常见漏转义,但不自动为任意字典设计有效XML模式。

XML构造应分离结构与文本

创建Element节点,把值放进text,再由tostring输出,可让序列化器转义文本中的小于号等字符,避免把值误当标签;属性用set明确建立。原dict_to_xml只处理一层键值,嵌套对象、合法标签名、类型及顺序契约需另定义。手工escape可处理部分文本字符,但不能取代完整XML结构构造。

XML构造应分离结构与文本保存独立卡片。

原书依据 · 1 处

6.6 解析、修改和重写XML

元素的直接子节点具有顺序,修改结构应在父节点上删除、插入或追加,再序列化。树内容修改与原始文本排版保真不同,写出声明与编码也需要明确选择。

XML结构修改发生在父节点

要删XML子元素,在直接父节点remove找到的元素;新增用Element并在父节点insert/append,索引表示子节点顺序。查询结果可能不存在,应先定义这种情况如何处理。原getchildren旧接口已移除,可直接迭代元素或转list后查位置,见3.9迁移说明(核验2026-10-27)。重写树不保证保留原排版,序列化编码与声明也应明确。

XML结构修改发生在父节点保存独立卡片。

原书依据 · 1 处

6.7 用命名空间来解析XML文档

命名空间使标签身份由URI与本地名共同决定,短前缀只是便于书写的别名。默认命名空间也影响其作用范围里的子标签,所以只限定最外层html仍无法匹配里面的head/title。

XML标签身份包含命名空间

XML命名空间中的标签按URI和本地名区分;ElementTree用{URI}local形式表示,不能只看显示前缀或裸标签。默认命名空间也适用于内部相关子标签,所以查询每一层都需正确限定。命名空间URI在此是身份,不要求先访问该网址才能解析;声明的作用域可由iterparse命名空间事件跟踪。

XML标签身份包含命名空间保存独立卡片。

原书依据 · 1 处

命名空间助手只做路径替换

XMLNamespaces把短名映射成带花括号的URI片段,再用format_map展开查询字符串,减少重复输入。它保存的是调用方指定映射,不自动从任意文档恢复全部声明或验证XPath。

结构图:

classDiagram
 class XMLNamespaces {
  +__init__(**kwargs)
  +register(name, uri)
  +__call__(path)
 }
 XMLNamespaces --> dict : namespaces

图表示实例持有映射与真实方法入口;返回的是格式化路径,查询仍由解析器执行。

命名空间助手只做路径替换保存独立卡片。

原书依据 · 1 处

6.8 同关系型数据库进行交互

DB-API把连接、游标、参数化执行与提交组成常见交互方式。相似接口便于迁移编程习惯,但占位符、事务和类型适配仍由具体驱动约定;绑定值与拼接SQL结构要分清。

数据库参数须交给驱动绑定

来自用户的数据值应通过驱动参数绑定传给SQL执行接口,避免用字符串格式化混入语句。占位符样式由驱动规定,可查看paramstyle,不能把sqlite问号直接当所有后端通用形式。值绑定不替代动态表名或列名的结构选择约束;这些结构通常需显式允许列表,而不是把任意输入拼进去。

数据库参数须交给驱动绑定保存独立卡片。

原书依据 · 1 处

数据库通用接口不消除类型差异

DB-API常用连接、游标、execute/executemany与commit组织交互,行可用元组表达。日期、时间戳与Decimal等映射依后端和驱动,不能假定同一Python类型跨库意义完全一致。提交、回滚与错误后的事务状态也应按实际接口明确;高层ORM能隐藏部分SQL,却不取消类型、事务或查询行为的责任。

数据库通用接口不消除类型差异保存独立卡片。

原书依据 · 1 处

6.9 编码和解码十六进制数字

十六进制把每个字节表示成两个ASCII数字字符,编码结果的字节形式与显示文本仍需区分。大小写接受策略由具体接口及参数决定,不是编码机制本身的绝对限制。

十六进制表示仍须区分字节文本

binascii的十六进制编解码与base64.b16encode/decode可在字节和十六进制表示间转换;编码结果为bytes,显示为文本可再按ASCII解码。Base16编码使用大写,解码默认拒绝小写,但可用casefold参数放宽,不能说永远只接受大写,已查官方API(2026-10-27)。格式合法性和长度仍须检查;这不是加密。

十六进制表示仍须区分字节文本保存独立卡片。

原书依据 · 1 处

6.10 Base64编码和解码

Base64用有限ASCII字符表示二进制数据,便于放到文本载体里;字符表示不改变其可逆且公开的编码性质。文本与字节的接口转换应显式完成,不能据可读形式推断安全性。

Base64是表示编码并非加密

Base64把字节编码成ASCII范围的表示,b64encode输出bytes;需要文本字段时再按ASCII解码,接收时按相应规则还原字节。它用于适配文本通道,不隐藏内容,也不自行提供完整性或来源验证。解码是否严格拒绝额外字符、使用哪种字母表和填充规则,需由所选接口与协议明确,而非只靠往返示例保证。

Base64是表示编码并非加密保存独立卡片。

原书依据 · 1 处

6.11 读写二进制结构的数组

结构化二进制记录需要固定字段布局、字节序与宽度,Struct把这种约定集中起来。逐记录读与整块读后按偏移解析有不同占用,二者都需验证输入足够完整并维持来源的生命期。

二进制记录须固定布局与字节序

Struct格式集中规定字段布局;示例是小端标准尺寸的一个32位整数与两个64位浮点数,共20字节。pack按格式编码,unpack要求匹配长度;采用原生布局时还会涉及平台尺寸及对齐,不能只复用字段名字。把格式集中在实例可减少维护时多处不一致;格式正确仍不等于字段业务值有效。

二进制记录须固定布局与字节序保存独立卡片。

原书依据 · 1 处

按偏移解包避免输入切片

整块二进制数据可用unpack_from(data,offset)直接按偏移解包,避免为每条记录先切出新输入字节串;输出元组与字段对象仍会产生,不能说完全没有临时对象。循环前应确认数据长度是记录大小的整倍数,或明确定义尾部;逐块read同样需处理短块。使用生成器读取时,必须在底层文件关闭之前完成消费。

按偏移解包避免输入切片保存独立卡片。

原书依据 · 1 处

二进制结构化数组需对齐格式

NumPy fromfile可按明确dtype把二进制记录读成结构化数组,减少逐条Python元组处理。dtype的字段宽度、字节序与排列必须和文件一致,它不会自动识别任意文件的真实模式。已有图像、shapefile或HDF5等成熟格式,先考察专用解析器,避免只按局部记录布局误读完整格式。

二进制结构化数组需对齐格式保存独立卡片。

原书依据 · 1 处

6.12 读取嵌套型和大小可变的二进制结构

复杂二进制格式先要分清固定文件头、嵌套字段与带长度的记录。描述符把字段访问转换为按偏移解包,元类把字段声明编译成这些描述符;变长区域则先取得一个有界字节块再按所选类型解释。便利接口仍需严格校验长度与资源限制。

变长记录须核验长度头的含义

变长二进制记录的长度头必须说明是否包含头本身。原例头为4字节,记录总长应减4才是载荷,再验证其非负、未超可用数据且是16字节点坐标记录的整倍数。读取还须检查实际字节数,并限制数量和分配规模;否则恶意或损坏长度可能导致越界、短读甚至负数read读取剩余全部。示例方法只演示布局,不自带完整验证。

变长记录须核验长度头的含义保存独立卡片。

原书依据 · 1 处

字段描述符实现按需解包

Structure持有底层字节,StructField保存格式和偏移,实例访问字段时才unpack_from;不访问的字段无需先全部展开。

结构图:

classDiagram
 class Structure {
  +__init__(bytedata)
 }
 class StructField {
  +__init__(format, offset)
  +__get__(instance, cls)
 }
 Structure <|-- PolyHeader
 PolyHeader --> StructField : 字段描述符
 Structure --> memoryview : 首版_buffer

实线空心三角为继承,普通箭头为持有;类访问返回描述符本身,实例访问返回解包值,单字段与多字段结果形状不同。按需解包减少无用工作,却不自动验证业务字段。

字段描述符实现按需解包保存独立卡片。

原书依据 · 1 处

元类把字段声明变成访问器

StructureMeta在创建类时读取_fields_,依字段格式和累计偏移安装StructField,并计算struct_size;Structure.from_file据此读取固定头。

结构图:

classDiagram
 type <|-- StructureMeta
 class StructureMeta {
  +__init__(clsname, bases, clsdict)
 }
 class Structure {
  +__init__(bytedata)
  +from_file(f)
 }
 StructureMeta ..> Structure : 创建其类对象
 StructureMeta ..> StructField : 安装描述符
 Structure <|-- PolyHeader

继承与创建依赖是不同关系;省去重复偏移不等于格式自动正确。示例字节序前缀沿后续字段保留,可显式切换;原生对齐、继承布局及短读仍需另定义,不能当通用C结构布局器。

元类把字段声明变成访问器保存独立卡片。

原书依据 · 1 处

嵌套结构共享取决于底层缓冲

NestedStruct在第一次访问嵌套字段时按偏移切片并构造子Structure,再把结果缓存到实例属性,避免重复构造。

结构图:

classDiagram
 class NestedStruct {
  +__init__(name, struct_type, offset)
  +__get__(instance, cls)
 }
 Structure <|-- PolyHeader
 Structure <|-- Point
 PolyHeader --> NestedStruct : min和max描述符
 NestedStruct ..> Point : 按区域构造并缓存

要让嵌套切片共享原内存,底层必须保留memoryview等视图语义。原后版Structure把bytedata原样保存,若输入bytes则切片仍复制,不能沿用首版视图保证。缓存实例还意味着后续修改和生命周期要有明确契约。

嵌套结构共享取决于底层缓冲保存独立卡片。

原书依据 · 1 处

记录读取与解释可分开

SizedRecord先保存一块带边界的记录字节,再由iter_as选择格式字符串或Structure类型解释,使读取与字段表示分离。

结构图:

classDiagram
 class SizedRecord {
  +__init__(bytedata)
  +from_file(f, size_fmt, includes_size=True)
  +iter_as(code)
 }
 SizedRecord --> memoryview : _buffer
 SizedRecord ..> Struct : 格式字符串分支
 SizedRecord ..> Structure : 类型分支

箭头表示持有或使用依赖,无继承关系。iter_as逐项生成结果,但from_file已读入整条载荷;它不是整文件零缓冲流式解析,格式或类型仍须与载荷长度匹配。

记录读取与解释可分开保存独立卡片。

原书依据 · 1 处

6.13 数据汇总和统计

表格分析把外部数据装入列与行,再明确筛选条件、分组键和聚合口径。统计计数首先反映记录而非真实世界总量,日期、缺失值与重复记录会影响解释。

表格汇总须先明确筛选口径

Pandas DataFrame可先检查列值、按条件筛选,再用value_counts统计频数或groupby分组后size计行数。示例只统计派出队伍的请求记录,不能据此直接称某邮编真实老鼠最多;缺失、重复及收录范围都会影响解释。按日期分组前也要明确字符串格式与日期类型,按计数排序和按时间排序回答不同问题。

表格汇总须先明确筛选口径保存独立卡片。

原书依据 · 1 处

分析示例需核对库版本接口

原Pandas例中skip_footer与Series.sort属于旧接口写法,当前读CSV用skipfooter,按值排序可用sort_values;已查读取API与排序API(2026-10-27)。还需核对引擎支持、缺失值和排序是否原地;历史行数及统计结果不当当前城市数据,也未实测。

分析示例需核对库版本接口保存独立卡片。

原书依据 · 1 处

第7章 函数

函数不仅封装计算,也封装调用约定。位置与关键字参数、默认值、注解和返回结构决定调用者怎样使用它;闭包、partial和回调再把部分状态带到未来。状态是绑定引用还是独立快照、异常如何回传,需要显式约定。

7.1 编写可接受任意数量参数的函数

可变参数把额外位置参数收集为元组、额外关键字参数收集为字典。它放宽调用形式但不会免除参数含义与校验,位置收集之后的命名参数仍可保持显式接口。

可变参数收集不等于任意语义

定义中的*args收集额外位置参数为元组,**kwargs收集额外关键字参数为字典;仍可保留必填的first等显式参数。*args后声明的参数只接受关键字形式,因此灵活收集与清晰接口可以并存。收集本身不会验证每项含义或类型,也不意味着数量和资源可以无限;调用中的*展开与定义中收集是两个方向。

可变参数收集不等于任意语义保存独立卡片。

原书依据 · 1 处

7.2 编写只接受关键字参数的函数

仅关键字参数要求调用方写出参数名,使含义不清的布尔开关等更容易阅读,也让帮助信息展示真正接口。是否有默认值仍需独立定义。

仅关键字防误用

在单独*或*args之后声明的参数只能按名称传入,如recv(maxsize,block=False),减少布尔位置参数含义不明。没有默认值的keyword-only参数仍必填;默认值与仅关键字是两种不同约束。显式声明也让帮助和签名工具看见参数,通常比把所有选项藏进kwargs更清楚。

仅关键字防误用保存独立卡片。

原书依据 · 1 处

7.3 将元数据信息附加到函数参数上

函数注解为参数与返回结果提供元数据,默认不会替函数检查类型或强制返回结果。工具可以读取它们赋予静态或运行时意义,但评价和读取时机有版本差异。

函数注解不自动执行类型检查

参数与返回注解说明预期用法,可被文档、类型检查器或框架解释;普通函数不会仅因写了int注解就自动拒绝其他输入。annotations可访问相关元数据,但求值时机不能沿用旧版固定假设:3.14起采用延迟求值机制,已查官方指南(2026-10-27)。读取外来注解也不应当纯被动数据操作。

函数注解不自动执行类型检查保存独立卡片。

原书依据 · 1 处

7.4 从函数中返回多个值

return后的逗号会把多个值组合为一个元组,调用方可以接收整体或按结构解包。这个结果契约与第一章的解包规则相衔接,而非函数真实返回多条独立通道。

解包是结构契约关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

7.5 定义带有默认参数的函数

默认值在定义函数时求值并绑定对象,因此可变对象可能在多次调用间共享。未传参数、显式传None和传其他假值也应分别建模,必要时用私有哨兵标识缺省。

默认参数会冻结

默认参数表达式通常在函数定义时求值并绑定对象,后续重新绑定外部同名变量不会更新它。绑定可变列表则会在多次调用间共享,并非冻结对象内容;若每次调用应新建,用None或私有哨兵在函数体内创建。只有明确需要共享且管理其修改时,才有理由选择可变默认,不能把共享误当隔离。

默认参数会冻结保存独立卡片。

原书依据 · 1 处

缺省与合法假值须分开判断

用if not value判断缺省会把0、空字符串和空容器等合法值也替换掉。若None专门表示缺省,可用is None;若None也是有效输入,则用独有object哨兵并以is判断是否未传。哨兵需要保持同一身份,不是普通相等比较;约定不向调用者暴露它,不能声称绝不可能有人显式传该对象。

缺省与合法假值须分开判断保存独立卡片。

原书依据 · 1 处

7.6 定义匿名或内联函数

lambda用单个表达式创建函数,适合短小回调,其结果就是返回值。表达式可以包含条件表达式或推导式,但复杂控制流仍用def更清楚;“内联”也不代表编译器优化保证。

匿名函数限表达式而非无分支

lambda表达式可为排序key等短回调创建函数,单个表达式的结果作为返回值。它不能放普通语句块或try语句,但表达式仍可含条件表达式、推导式与函数调用,不能说一切分支和迭代都禁用。复杂逻辑、异常处理或需要清楚命名时用def;lambda在此是语法形式,不保证调用被编译器内联。

匿名函数限表达式而非无分支保存独立卡片。

原书依据 · 1 处

7.7 在匿名函数中绑定变量的值

自由变量通常在函数执行时查找,循环创建的函数因此可能都看到最终值。默认参数则在创建函数时取当前对象,可用于保存每次迭代的绑定;这也会改变可调用接口,而非深复制环境。

闭包捕获变量不等于值快照

函数使用外层自由变量时,通常在执行时查找其当时值;循环建多个lambda不自动为每次迭代冻结值,所以可能全看到最后的n。写默认参数n=n可在每次定义时保存当时对象,但调用者仍能显式覆盖该参数,且可变对象后续变化也会被观察到。这个规则同样适用于相关def闭包,不是lambda独有缺陷。

闭包捕获变量不等于值快照保存独立卡片。

原书依据 · 1 处

7.8 让带有N个参数的可调用对象以较少的参数形式调用

partial预先存下部分调用参数,让目标函数适配另一接口需要的较少参数。它既可包装函数也可包装可调用类型;存的是调用配置,不会自动执行目标或解决状态并发。

偏函数绑定适配回调接口

partial(func,…)保存部分参数并返回新可调用对象,调用时再组合剩余参数交给原目标。适合给单参数排序key预置比较点,或给结果回调预置日志对象。位置绑定与关键字绑定规则不同,后续关键字可覆盖预置同名关键字,不能把“固定”理解为完全不可更改;不复制目标所引用状态,也不立即执行函数。

偏函数绑定适配回调接口保存独立卡片。

原书依据 · 1 处

处理器配置可由工厂注入

TCPServer需要按自身参数创建请求处理器;可用partial给EchoHandler预先提供额外ack,同时保留服务器传入的常规参数。

结构图:

classDiagram
 StreamRequestHandler <|-- EchoHandler
 class EchoHandler {
  +__init__(*args, ack, **kwargs)
  +handle()
 }
 TCPServer ..> partial : 调用配置工厂
 partial ..> EchoHandler : 预置ack后构造

partial节点是可调用包装,表示配置工厂而非新处理器子类;继承只存在于EchoHandler与StreamRequestHandler。ack仍须为可与输出字节组合的值,配置注入不改变网络协议本身。

处理器配置可由工厂注入保存独立卡片。

原书依据 · 1 处

7.9 用函数替代只有单个方法的类

只有一个操作且只是保存少量环境的对象,有时可用闭包表达。闭包把函数和它使用的外层绑定一起保留,使后续调用能继续使用配置;选择取决于是否需要更多显式接口。

闭包封装状态

闭包是函数连同其使用的外部变量环境,外层调用结束后仍可保留所需绑定。若类主要保存template并只提供一个open操作,可改成返回opener闭包,接口更轻;但这不表示只有单方法的类一律应删除。需要多操作、显式资源生命周期或可检查状态时,类可能更清楚;捕获环境也不是把所有外部对象深复制。

闭包封装状态保存独立卡片。

原书依据 · 1 处

7.10 在回调函数中携带额外的状态

回调常在另一个调用上下文被触发,所需状态可以由绑定方法、闭包或显式参数携带。状态的放置决定共享范围和更新方式;生成器send还多出启动与结束协议。

回调状态须明确归属与共享

结果回调若要累计序号等状态,可用实例绑定方法把self带入,或由工厂闭包保存外层绑定;也可显式传状态对象再用partial适配参数。每个实例或工厂调用可隔离状态,共用同一对象则共享变化;这些方式不自动保证并发更新安全。原演示apply_async同步执行再回调,不能据名字宣称已经异步调度。

回调状态须明确归属与共享保存独立卡片。

原书依据 · 1 处

nonlocal改外层绑定

嵌套函数若给外层局部变量重新赋值,需用nonlocal声明该绑定;否则赋值会使它成为内层局部变量,先读再写可能报错。nonlocal改变绑定的位置,不是同步机制;修改外层引用对象的内容与重新绑定变量不同。闭包也只保留实际关联的环境,不能声称自动保存业务所需的一切上下文。

nonlocal改外层绑定保存独立卡片。

原书依据 · 1 处

生成器回调须先启动再发送

生成器协程可用send作为回调入口,把结果传进暂停的yield并继续更新局部状态。首次需next或send(None)推进至接收点;之后send的值成为yield表达式的结果。它与普通闭包不同,还存在耗尽、异常和关闭协议;不能把同一个生成器随意并发重入,也不因无需nonlocal就解决这些生命周期问题。

生成器回调须先启动再发送保存独立卡片。

原书依据 · 1 处

7.11 内联回调函数

生成器可把依次发起任务和接收结果写在一段流程中,由外层驱动器取出任务描述并把完成结果送回。队列连接回调与恢复点,但异常、取消及调度仍是驱动器需要完成的协议。

生成器可表达回调恢复流程

驱动器先向队列放None,取出后send给生成器启动;生成器yield出待执行任务,驱动器调用它并把队列put设为完成回调。下一轮get得到结果,再send回上一个yield处继续。

结构图:

sequenceDiagram
 participant W as wrapper驱动器
 participant G as 被包装生成器
 participant A as apply_async
 participant Q as 结果队列
 W->>Q: 放入启动值None
 loop 每项任务
 W->>Q: get结果
 W->>G: send结果
 G-->>W: yield任务
 W->>A: 函数及参数与回调
 A->>Q: 完成后put结果
 end

StopIteration结束流程。原同步apply_async没有真正并发;队列把恢复位置连接起来,而非自动产生异步执行。

生成器可表达回调恢复流程保存独立卡片。

原书依据 · 1 处

任务描述对象分离请求与执行

Async只保存func与args;生成器产出该对象,驱动器读取它并决定如何执行。

结构图:

classDiagram
 class Async {
  +__init__(func, args)
 }
 Async --> callable : func
 Async --> tuple : args示例

箭头表示字段持有关系,tuple是本例调用约定,并非构造器强制检查类型;callable为约定角色。名称Async不表示对象已经排入调度器,真正执行由外部apply_async实现决定。

任务描述对象分离请求与执行保存独立卡片。

原书依据 · 1 处

回调驱动器还需失败完成协议

把成功回调接到队列后,驱动器每轮get等待下一结果;若异步任务失败且没有任何完成消息,可能永久等待。完整协议还需失败传递、取消、超时与清理,并决定是否向生成器throw异常。原装饰器只接*args、未传播生成器返回值,也没有这些保障;改成进程池不会自动补全。此边界来自原控制流推导,未运行故障试验。

回调驱动器还需失败完成协议保存独立卡片。

原书依据 · 1 处

7.12 访问定义在闭包内的变量

给闭包附加访问函数,可把原本隐藏的绑定变成受控的读写接口。进一步把一组闭包放到对象字典可模拟部分实例行为,但特殊方法查找与类协议并非完全相同,维护代价需单独评估。

闭包可通过访问函数暴露状态

在同一外层环境定义主函数和get/set访问函数,再把访问函数附到主函数属性,可让调用者读取或修改共享绑定;set重新绑定时仍需nonlocal。这样能提供重置、清缓存等入口,同时把直接访问改为受控操作。函数属性不是自动绑定方法,参数与状态约定由这些函数自己定义;它也不把隐藏环境变成不可突破的安全隔离。

装饰器可把访问函数附到包装器,供运行时调整闭包配置;外层复制这个函数引用后仍操作原闭包,区别于复制普通配置值后修改外层属性。

闭包可通过访问函数暴露状态保存独立卡片。

原书依据 · 2 处

闭包模拟实例仍须满足特殊协议

ClosureInstance从调用者局部环境挑出可调用对象放入自身字典,Stack工厂的push/pop闭包共享items。

结构图:

classDiagram
 class ClosureInstance {
  +__init__(locals=None)
  +__len__()
 }
 class Stack {
  <<函数工厂非类型>>
 }
 Stack ..> ClosureInstance : 构造并提供闭包
 ClosureInstance ..> callable : 实例字典保存操作

len等特殊调用从类型协议寻找,不能只把同名函数塞进实例字典;因此类上还需显式len转发。它不是普通类继承、描述符等能力的通用替代;自动抓帧还增加实现依赖与可读性成本。

闭包模拟实例仍须满足特殊协议保存独立卡片。

原书依据 · 1 处

局部微基准不证明设计更优

原push/pop微基准闭包版约快8%,只说明当时实现、版本与负载的局部测量。比较方案还应覆盖接口能力、可读性、继承与特殊方法行为,以及目标解释器的真实成本;不能把“少self”当所有版本必快的证明。若没有实际性能需求,闭包模拟完整对象的技巧可能增加维护负担,原数据未在本机复测。

局部微基准不证明设计更优保存独立卡片。

原书依据 · 1 处

第8章 类与对象

对象通过特殊方法加入格式化、上下文、容器和比较协议。property控制单个属性,描述符把访问规则复用于多个属性,继承与委派则组织行为复用。状态机、访问者和弱引用展示了控制流与对象寿命如何影响设计;不能把方便的包装视为自动正确的契约。

8.1 修改实例的字符串表示

对象的调试表示与给用户看的文字可以不同;repr帮助辨认类型和状态,str服务可读输出。可重建表达式是一种有条件的目标,而非任何对象或eval安全性的保证。

repr服务调试

repr通常提供面向调试、可辨类型和关键状态的表示,str面向易读展示;未定义str时可回退repr。格式!r显式选repr,!s选str。repr若适合可写成重建表达式,否则可用有帮助的尖括号文字;它不自动成为安全序列化,也不保证eval(repr(x))==x,后者还依赖构造环境和相等语义,不能为验证而执行不可信文本。

repr服务调试保存独立卡片。

原书依据 · 1 处

8.2 自定义字符串的输出格式

format接口把格式代码交给对象类型解释,不同类型的代码不必共享同一语法。空代码的默认表示、支持的代码集合和未知代码错误都属于类型的输出契约。

对象格式码由类型自行解释

定义format(self,code)可让format(obj,code)与格式字符串调用对象自己的格式规则。原Date把ymd/mdy/dmy映射为年月日排列,空代码选默认;datetime的百分号格式则是另一套规则,不能混用。实现应明确未知代码与返回字符串契约,示例字典缺项会报错,也未替日期值做有效性校验。

对象格式码由类型自行解释保存独立卡片。

原书依据 · 1 处

8.3 让对象支持上下文管理协议

with协议把进入、主体与退出连接起来,as接收进入方法的返回对象,退出方法处理清理和异常。进入失败是另一条路径:还没成功进入就不会由该with调用exit,所以获取中途失败也要自己清理。

上下文退出不涵盖进入失败

with先调用enter,把其返回值赋给as目标,成功进入后才运行主体并调用exit清理。主体异常会把异常信息传给exit;exit返回真值可抑制异常,否则继续传播。若enter自身失败,该with不会替它调用exit,获取到一半的资源须自行清理;退出方法也可能报错,因此“无论如何都清理成功”不是协议保证。语言说明已核验(2026-10-27)。

上下文退出不涵盖进入失败保存独立卡片。

原书依据 · 1 处

上下文可重用与可嵌套不同

首版LazyConnection只保存一条sock,使用中再次进入会报错;退出后清空可再次使用。栈版每次进入新建连接并压栈,退出弹出最近连接,支持顺序嵌套而非共享同一socket。

结构图:

classDiagram
 class LazyConnection {
  +__init__(address, family, type)
  +__enter__()
  +__exit__(exc_ty, exc_val, tb)
 }
 LazyConnection --> socket : 首版单个sock
 LazyConnection --> list : 栈版connections

两条边代表两个替代版本的持有方式,不是同一版同时存两处;栈并不自动让并发交错使用线程安全。原构造器忽略family/type实参、connect失败未关新socket,都需修正。

上下文可重用与可嵌套不同保存独立卡片。

原书依据 · 1 处

8.4 当创建大量实例时如何节省内存

slots为大量固定形状实例提供内存布局选择,可减少逐实例字典开销。它与访问控制不同,而且继承、弱引用与是否仍有字典都会改变实际约束,节省大小应在目标环境测量。

slots限制形状

slots可为属性声明固定槽位,在适当继承布局下省去实例dict,适合大量简单数据对象;它不是安全封装。若基类已有字典,或子类重新引入字典,仍可能添加动态属性;需要弱引用还须满足相应槽位支持。多重继承并非全部禁止,但有布局约束,已查官方说明(2026-10-27)。原428/156字节是历史测量,不能当当前固定节省。

slots限制形状保存独立卡片。

原书依据 · 1 处

8.5 将名称封装到类中

下划线名称表达接口意图,双前导下划线另触发名称重整,减少子类与基类内部名称的意外冲突。二者都不是阻止访问的安全机制,末尾下划线则解决关键词命名冲突。

内部命名约定不等于访问控制

单前导下划线表示内部实现,提醒调用方不要依赖不稳定接口;Python并不因此禁止访问。双前导且非特殊双尾形式的名称会按类名重整,减少子类意外覆盖基类内部属性,而非把数据加密或绝对隐藏。lambda_这类单后缀下划线则用于避开关键词冲突,与私有性不同。

内部命名约定不等于访问控制保存独立卡片。

原书依据 · 1 处

名称重整避免继承意外碰撞

基类B的private会重整为_Bprivate,子类C同写法对应_C__private,因此两者不会因同样源码短名自动覆盖。

结构图:

classDiagram
 class B {
  +__init__()
  +public_method()
 }
 class C {
  +__init__()
 }
 B <|-- C

继承并未合并两个重整后名字,B内部调用也保留其类内名称解析。外部仍可使用实际重整名访问,子类也可有意操作它,所以这是一种避碰规则,不是不可越过的隐藏。

名称重整避免继承意外碰撞保存独立卡片。

原书依据 · 1 处

8.6 创建可管理的属性

property保持属性访问语法,同时让读取、赋值和删除触发不同操作。它适合需要验证或计算的接口,后备存储与验证路径应明确;只有机械转发时不必为每个属性增加一层。

property护不变量

property把读取、赋值、删除分别接到getter/setter/deleter,能在保持obj.name语法时验证输入或计算结果。构造器若也走公共属性赋值,初始化就经过同一验证;后备值另存_first_name避免自递归。它只约束经过该接口的操作,不阻止直接更改后备字段。无额外处理时可用普通属性,需要时再升级,而非每项都机械套get/set。

property护不变量保存独立卡片。

原书依据 · 1 处

计算属性不自动缓存结果

property可让area、perimeter等按当前radius计算,以属性语法统一访问,但每次读取默认都会重新执行getter,不自动缓存。是否有setter决定能否通过该接口赋值;没有setter也不等于所有相关对象都不可变。若操作昂贵、带副作用或面向RPC,显式方法可能更能表达成本与调用边界。

计算属性不自动缓存结果保存独立卡片。

原书依据 · 1 处

重复属性验证宜抽取机制

多个字段复制相同getter/setter验证容易膨胀并产生不一致,可用描述符或闭包把共同规则抽取出来,具体机制由后续章节展开。抽取应保留字段名、错误与存储语义,而非仅减少行数。property本身的fget/fset/fdel可访问对应函数,通常让属性协议触发即可,不把直接调用当日常访问方式。

闭包工厂可把字段名、后备存储名和预期类型保存为配置,再生成property,partial可预置常用类型。它与共享描述符都能减少重复,选择取决于需要的复用与接口。

重复属性验证宜抽取机制保存独立卡片。

原书依据 · 2 处

8.7 调用父类中的方法

super按实际实例的MRO继续查找,不只是静态调用源码里写出的直接父类。多重继承中共同遵守协作协议,才可能避免共享基类被重复执行;方法签名、调用次数和最终终止点都影响正确性。

super沿MRO继续查找

super不是固定父类别名:在实际对象MRO里从当前类之后继续查找。示例C(A,B)次序为C、A、B、Base、object,因此A中的super可调用B,再到Base。

结构图:

classDiagram
 Base <|-- A
 Base <|-- B
 A <|-- C
 B <|-- C
 class A {
  +__init__()
 }
 class B {
  +__init__()
 }
 class C {
  +__init__()
 }

图是继承关系,执行次序由MRO确定;构造进入顺序与返回后print顺序相反。C3还需保持局部顺序及单调性,不能把原简略条目当完整算法,见官方MRO说明(核验2026-10-27)。

super沿MRO继续查找保存独立卡片。

原书依据 · 1 处

协作继承须共享调用契约

菱形继承若手工分别调用两路基类初始化,公共基类可能执行两次。各层用super继续传递且只调用一次,可沿同一MRO串联,但前提是相关方法合作、签名兼容并有适当终止实现。super不会自动修正某层漏调、重复调用或不匹配参数;继承层级看似相近也不能代替实际调用协议。

协作继承须共享调用契约保存独立卡片。

原书依据 · 1 处

属性代理须保留自身存储路径

代理把公开属性赋值转交给内部对象前,应先为自身_obj等状态保留存储路径。原setattr按下划线判断:内部名调用super的赋值逻辑,其余setattr目标对象;缺失属性查询由getattr委托。这样可避免设置_obj又递归代理自己,但下划线规则只是本例约定,也不自动代理所有特殊方法。

删除代理属性也需保留内部状态路径;读回退并不自动过滤所有下划线名称。完整透明性还要按类型补齐len、下标等特殊操作,不能仅靠getattr。

属性代理须保留自身存储路径保存独立卡片。

原书依据 · 2 处

8.8 在子类中扩展属性

property是getter、setter与deleter的组合,子类只替换其中一项时应保留另外两项。要调用被覆盖属性的写入协议,需要取得类上的描述符对象,而非已经求值的实例属性。

扩展属性须保留其余访问器

子类重新写@property会建立新property,原setter/deleter不会自动接上,基类构造时赋值也可能因此失败。只换读取逻辑可用@Person.name.getter保留其他访问器,再在新getter中继续原实现。写入扩展要调用类上原描述符的set,而不是对super().name的读取结果赋值。原@Person.getter漏了.name;扩展的String例没有delete,不能凭转发就产生删除支持。

扩展属性须保留其余访问器保存独立卡片。

原书依据 · 1 处

8.9 创建一种新形式的类属性或实例属性

描述符把属性访问规则封装为可复用对象,放在类上,再根据被访问实例处理数据。规则对象通常共享,而每个实例的数据可保存在自身字典;装到实例上的普通对象不会触发同样的类属性协议。

描述符复用逻辑

描述符对象定义get、set或delete等属性协议,并作为类属性安装。规则对象可在多实例间复用,实际值按传入instance存入其字典,避免把不同实例数据混在描述符自身。

结构图:

classDiagram
 class Integer {
  +__init__(name)
  +__get__(instance, cls)
  +__set__(instance, value)
  +__delete__(instance)
 }
 class Point {
  +__init__(x, y)
 }
 Point --> Integer : 类属性x和y持有规则
 Integer ..> dict : instance数据字典

普通箭头为持有,虚线为操作依赖,无继承;此例依赖实例字典,不自动支持无字典slots对象。property护不变量适合单个属性定制,描述符适合跨字段复用规则。

描述符复用逻辑保存独立卡片。

原书依据 · 1 处

描述符类访问与实例访问不同

实例访问描述符时get接到该实例;类访问则instance为None,常返回描述符自身便于检查和扩展。只把Integer等对象赋给某个实例属性,不会自动触发类属性描述符协议。检查int类型的isinstance也会接受bool等int子类;实际业务若不接受,须定义更严格规则,不能把示例当全部类型约束。

描述符类访问与实例访问不同保存独立卡片。

原书依据 · 1 处

类装饰器可集中安装字段规则

typeassert接收字段到预期类型的映射,返回装饰器,在类上为每项安装Typed描述符并返回类。这样把重复验证集中为声明,初始化赋值也走同一规则。它会改变类属性,字段冲突、类层安装时机与具体存储协议仍须明确;集中声明不代表外部值已完整校验,更不自动维护跨字段不变量。

类装饰器可集中安装字段规则保存独立卡片。

原书依据 · 1 处

8.10 让属性具有惰性求值的能力

惰性属性先按需要计算,再决定怎样存放与失效。仅有get的非数据描述符允许实例同名值遮蔽自己,因而可在首次访问后绕过计算;只读property缓存则保留每次访问入口。

非数据描述符可被实例缓存遮蔽

仅定义get的lazyproperty是非数据描述符;首次访问计算后,把值存为实例同名属性,后续查找优先拿缓存,不再调用描述符。

结构图:

classDiagram
 class lazyproperty {
  +__init__(func)
  +__get__(instance, cls)
 }
 class Circle {
  +__init__(radius)
 }
 Circle --> lazyproperty : 类上area及perimeter
 lazyproperty ..> dict : 同名实例缓存

图表示规则持有与缓存依赖;删除实例同名缓存可再次触发。它需要可保存该属性的实例存储,不能直接假定所有slots对象可用。

非数据描述符可被实例缓存遮蔽保存独立卡片。

原书依据 · 1 处

缓存属性须有失效与写入策略

同名实例缓存可被直接赋值覆盖,删除后才会重算;radius改变也不会自动刷新area。若改成只读property并把缓存放到_lazy_名称,可拒绝公共属性赋值,但每次仍经过getter,依赖变化时仍需显式失效。这里“可变”指属性绑定能改,不表示返回的浮点对象自身可变;并发首次访问还可能重复计算。

缓存属性须有失效与写入策略保存独立卡片。

原书依据 · 1 处

8.11 简化数据结构的初始化过程

用字段声明驱动通用初始化可减少重复赋值,但要明确参数绑定、错误与允许的额外属性。setattr保持属性协议,直接更新字典会绕过它;广泛自动化也可能削弱显式签名。

声明式初始化须约束参数绑定

Structure基类可按_fields把位置值或关键字值赋给子类字段,减少重复初始化。

结构图:

classDiagram
 class Structure {
  +__init__(*args, **kwargs)
 }
 Structure <|-- Stock
 Structure <|-- Point
 Structure <|-- Circle

图为支持关键字的替代版本;子类提供字段声明。必须决定缺失、重复、未知和过多参数的错误,以及额外属性是否允许。示例先部分赋值再发现错误,不具备原子初始化保证;通用*args签名还会隐藏实际参数,需权衡帮助与工具可见性。

声明式初始化须约束参数绑定保存独立卡片。

原书依据 · 1 处

通用赋值应尊重属性协议

通用初始化用setattr会遵循property或描述符等属性协议;直接self.dict.update可能绕过验证,也对无实例字典的对象不适用。setattr仍可能触发副作用或报错,不能说它不作任何假设。抓调用帧locals自动赋值还引入实现依赖,局部变量也可能并非参数;显式声明通常更易理解,原慢50%仅历史测量。

通用赋值应尊重属性协议保存独立卡片。

原书依据 · 1 处

8.12 定义一个接口或抽象基类

抽象基类描述一组要求实现的操作,未完成抽象方法的子类不能正常实例化。注册虚拟子类则只影响类型关系判断,既不注入实现也不验证行为;接口成立仍需测试。

抽象基类声明操作不证明行为

ABCMeta与abstractmethod可声明必须补齐的操作,未实现的抽象类不能实例化。

结构图:

classDiagram
 class IStream {
  <<abstract>>
  +read(maxbytes=-1)
  +write(data)
 }
 class SocketStream {
  +read(maxbytes=-1)
  +write(data)
 }
 IStream <|-- SocketStream

这里是显式继承;补齐方法名不自动验证签名、返回语义或异常契约。abstractmethod可与property、classmethod、staticmethod组合,通常放在紧邻函数的内层。

抽象基类声明操作不证明行为保存独立卡片。

原书依据 · 1 处

虚拟子类注册不注入实现

ABC.register可使某类型及相关实例通过该ABC的类型关系检查,但它不改变实际继承MRO、不提供抽象方法实现,也不验证读写是否真符合约定。注册整个IOBase范围尤其宽,不能据isinstance为真就认定每个流同时可读可写。真实支持能力应按接口契约验证,避免用宽泛注册掩盖不兼容。

虚拟子类注册不注入实现保存独立卡片。

原书依据 · 1 处

抽象类型分类取决于运算契约

标准容器、I/O与数值ABC便于按能力分类,但分类并非单看数学名称。Decimal表示实数值,却不必注册为numbers.Real,因为类型体系还涉及运算兼容等契约。应验证实际库对象的关系和用法,而非强迫所有近义类型归同一类别;现代容器ABC位于collections.abc,不沿用旧collections入口。

抽象类型分类取决于运算契约保存独立卡片。

原书依据 · 1 处

8.13 实现一种数据模型或类型系统

描述符验证可拆成类型、取值和长度组件,再通过协作调用组合成字段约束。字段规则与最后存储分开便于复用,但组合顺序、错误信息和非法值覆盖仍是实际设计的一部分。

验证组件通过协作调用组合

Typed检查类型,Unsigned检查小于零,最后Descriptor保存值;UnsignedInteger把Integer与Unsigned合并,super按MRO串联验证后存储。

结构图:

classDiagram
 class Descriptor {
  +__init__(name=None, **opts)
  +__set__(instance, value)
 }
 class Typed {
  +__set__(instance, value)
 }
 class Unsigned {
  +__set__(instance, value)
 }
 Descriptor <|-- Typed
 Descriptor <|-- Unsigned
 Typed <|-- Integer
 Integer <|-- UnsignedInteger
 Unsigned <|-- UnsignedInteger

箭头均为继承。共同签名与每层正确调用super是组合前提,类变量expected_type提供类型参数,不能凭多重继承自动证明任意组合顺序都正确。

验证组件通过协作调用组合保存独立卡片。

原书依据 · 1 处

验证名称不替代真实边界条件

MaxSized原检查len(value)>=size就拒绝,因此size=8只允许长度小于8,不是最多8;Unsigned只排除小于0,不保证有限浮点值,NaN和正无穷可能通过。类型检查isinstance也可能接受子类,如bool属于int。字段验证需明确实际业务范围,不能根据类名或预期例子认定已覆盖所有非法值。

验证名称不替代真实边界条件保存独立卡片。

原书依据 · 1 处

约束声明可自动绑定字段名

check_attributes装饰器可把声明键填进描述符name后安装;checkedmeta则在创建类时扫描类字典,为其中描述符填名,减少重复写字段名。两种时机不同,已有描述符实例若重复共享也可能被后续改名。自动命名不等于自动推导所有规则,继承和动态安装仍须考虑;通用opts更应约束可改属性,避免覆盖核心方法。

约束声明可自动绑定字段名保存独立卡片。

原书依据 · 1 处

装饰器组合以包装次序实现

替代方案的Typed、Unsigned、MaxSized是修改类方法的装饰器:先保存旧set,新方法检查后调用旧方法,形成包装链。它与同名mixin类方案不同,不经过同一super链;顺序改变可能先做范围检查再做类型检查。应对目标输入验证错误契约;原几乎快100%只是历史微基准,不能保证当前所有负载更快。

装饰器组合以包装次序实现保存独立卡片。

原书依据 · 1 处

8.14 实现自定义的容器

容器ABC指定最小必要方法,并可由这些操作派生常用能力。继承可检查是否补齐入口,但真实排序、不变式与复杂度仍取决于实现;不要把提供的方法集合误认成性能和正确性保证。

容器基类以少量操作派生能力

Sequence要求getitem和len等核心操作;MutableSequence再要求赋值、删除和insert,从中派生append、remove、count等常用方法。

结构图:

classDiagram
 Sequence <|-- SortedItems
 MutableSequence <|-- Items
 class SortedItems {
  +__getitem__(index)
  +__len__()
  +add(item)
 }
 class Items {
  +__getitem__(index)
  +__setitem__(index, value)
  +__delitem__(index)
  +insert(index, value)
  +__len__()
 }

继承指向collections.abc中的现代类型,派生方法会调用核心操作;因此其正确性、切片语义与复杂度也受这些操作影响,不自动等于内建list。

容器基类以少量操作派生能力保存独立卡片。

原书依据 · 1 处

有序容器须维护初始化不变量

SortedItems先排序初始元素,再用bisect.insort把新元素插到有序位置,才能维持整体有序。原初始化条件写反:应在initial非None时sorted(initial),否则空列表;Items的list(initial)判断也有相同错误。二分定位不等于整体插入O(log n),列表移动仍可能线性;元素还需具有一致的可比较关系。

有序容器须维护初始化不变量保存独立卡片。

原书依据 · 1 处

8.15 委托属性的访问

委托用持有对象实现操作转交,选择性暴露能力而不建立继承关系。缺失属性的回退委托可减少样板,但已有属性及特殊操作走不同查找路径,透明代理需要逐项定义协议。

属性代理须保留自身存储路径关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

委托通过持有关系复用行为

B持有A,把spam等操作显式交给内部对象,自己仍可提供bar;这可替代不合语义的继承,也便于限制暴露的方法。

结构图:

classDiagram
 class A {
  +spam(x)
  +foo()
 }
 class B {
  +__init__()
  +spam(x)
  +foo()
  +bar()
 }
 B --> A : _a持有并委托

普通箭头是持有而非继承。显式委托能明确接口;getattr只在正常属性查找失败时回退,会暴露目标中更多名字,不能默认等于严格接口白名单。

委托通过持有关系复用行为保存独立卡片。

原书依据 · 1 处

代理需显式实现特殊操作

getattr能把缺失的普通方法查找交给目标,却不能自动支持len、下标等由类型特殊协议查找的操作。ListLike若要支持这些行为,需要在自身类型定义len、getitem等转发。赋值和删除还应区分代理自己的状态与目标状态;原下划线过滤只用于赋值/删除,读取并未同样过滤,不能宣称整个代理只暴露公开属性。

代理需显式实现特殊操作保存独立卡片。

原书依据 · 1 处

8.16 在类中定义多个构造函数

命名类方法可表达不同数据来源的构造方式,同时保留正常构造器的清晰参数。类方法收到实际调用类,使用cls创建可使派生类复用入口,但其构造签名仍须兼容。

备选构造入口应表达来源

Date.today这类命名类方法清楚表达“按当前本地日期创建”,比无参数Date的隐含含义更易读。classmethod收到调用类cls,再用cls(…)构造,所以子类调用可返回子类对象;前提是子类构造契约兼容。主构造器仍可执行必要验证,不必把原“只赋值”建议绝对化;备选入口不应绕过共同不变量。

备选构造入口应表达来源保存独立卡片。

原书依据 · 1 处

8.17 不通过调用init来创建实例

对象分配与初始化是两个步骤,直接调用new可跳过init,调用者随即承担建立完整有效状态的责任。反序列化场景尤其要验证输入字段,不把对象存在等同于对象可用。

对象重建须验证字段与不变量关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

8.18 用Mixin技术来扩展类定义

mixin提供可组合的附加行为,借助MRO把工作继续交给实际容器或服务类。无状态组件通常更易组合;含状态时还需协调初始化参数、命名及拦截覆盖范围。

混入类把附加行为接入协作链

日志、只写一次与字符串键检查可作为独立mixin,与实际映射类型组合。

结构图:

classDiagram
 StringKeysMappingMixin <|-- StringOrderedDict
 SetOnceMappingMixin <|-- StringOrderedDict
 OrderedDict <|-- StringOrderedDict
 class StringKeysMappingMixin {
  +__setitem__(key, value)
 }
 class SetOnceMappingMixin {
  +__setitem__(key, value)
 }

箭头为继承,调用按实际MRO依次检查并交给下一实现;mixin自身不是完整映射。重复赋值限制并不禁止原值为列表时继续append,也不意味着整份映射不可变。

混入类把附加行为接入协作链保存独立卡片。

原书依据 · 1 处

有状态混入须协商初始化

无实例状态的mixin较少带来初始化冲突,slots=()表达本例不新增槽位。若需要状态,使用独立名称及专属仅关键字参数,处理自己的配置后把其余args/kwargs交给super。组合双方仍须遵守兼容协议;带状态并非绝对不可用,无状态也不自动保证任意继承组合有效。

有状态混入须协商初始化保存独立卡片。

原书依据 · 1 处

覆写单入口不覆盖全部修改路径

给映射子类覆写setitem可拦截显式下标赋值,但不能由此保证构造、update等所有内建路径都会经过它。应逐项确认目标类如何调用其原语,否则只写一次或键类型约束可能被绕过,见Python问题记录(核验2026-10-27)。检查后再设置也不自动原子或线程安全;包装方法、继承和装饰器都需验证实际覆盖。

覆写单入口不覆盖全部修改路径保存独立卡片。

原书依据 · 1 处

类方法包装可替代部分混入

LoggedMapping装饰器保存原get/set/delete方法,再把带日志的新方法安装到类上;它是修改同一类型的方法链,而非加入新继承层。可在少量可选行为上减少多重继承,但包装顺序、重复应用和原方法调用仍需明确。它同样只拦截被包装入口,不自动覆盖所有容器修改路径。

类方法包装可替代部分混入保存独立卡片。

原书依据 · 1 处

8.19 实现带有状态的对象或状态机

状态模式把某状态下允许的操作集中到独立实现,主对象保存数据并委托当前状态。状态转换可以改变委托目标,也可在受限类型布局下改变对象类型;减少分支不自动证明更快或更安全。

状态对象集中同一状态行为

Connection保存当前状态类,read/write/open/close转给它;Open与Closed分别实现允许动作及转换。

结构图:

classDiagram
 class Connection {
  +new_state(newstate)
  +read()
  +write(data)
  +open()
  +close()
 }
 class ConnectionState {
  +read(conn)
  +write(conn, data)
  +open(conn)
  +close(conn)
 }
 ConnectionState <|-- ClosedConnectionState
 ConnectionState <|-- OpenConnectionState
 Connection --> ConnectionState : _state引用状态类

继承组织状态协议,持有箭头为委托;数据留在Connection,状态静态方法接收它。NotImplementedError只在调用时提醒未实现,若要阻止实例化须用ABC等机制。

状态对象集中同一状态行为保存独立卡片。

原书依据 · 1 处

状态迁移须声明非法动作

连接初始关闭,open转为打开,close转回关闭;关闭时读写、重复打开或重复关闭在本例都报错。

结构图:

stateDiagram-v2
 [*] --> CLOSED
 CLOSED --> OPEN : open
 OPEN --> CLOSED : close

图仅表示合法迁移,其他动作按上述契约处理,不能因无边就默许忽略。状态模式让这些规则集中,却不自动使检查加执行原子化;本例只打印读写,没有真实网络I/O。

状态迁移须声明非法动作保存独立卡片。

原书依据 · 1 处

改变对象类型不等于普通状态赋值

替代状态实现把class改成OpenConnection或ClosedConnection,让同一实例直接分派到不同方法,省去状态对象委托。它要求类型布局等允许改变,不能对任意类型使用;方法选择和工具观察也随类型改变,理解成本更高。避免一层间接不构成目标环境必快的证据,清晰的状态数据与显式委托常更容易维护。

改变对象类型不等于普通状态赋值保存独立卡片。

原书依据 · 1 处

8.20 调用对象上的方法,方法名以字符串形式给出

按字符串调用方法分成属性查找和调用两步;methodcaller则把方法名与参数保存成可复用调用器。方法名如果来自外界,还应限制可调用范围,不能把动态查找当授权。

字符串方法调用先查找再执行

getattr(obj,name)先取属性,再带参数调用;methodcaller(name,…)把名字与参数预置,稍后接收对象执行,适合排序key等回调。目标属性必须存在且可调用,参数与状态还需符合契约。外来名称需限定允许操作,避免暴露不该调用的方法;原methodcall拼字应为methodcaller,机制本身不保证更高性能。

字符串方法调用先查找再执行保存独立卡片。

原书依据 · 1 处

8.21 实现访问者模式

访问者将树的节点表示与具体处理分开,使同一表达式能被求值或编成指令。访问入口按节点类型名分派,具体方法决定是否以及按何种顺序遍历子节点;增加节点类型仍需补齐各处理器。

访问者分离节点与处理操作

NodeVisitor按节点类型名找visit_Name,Evaluator计算数值,StackCode产生指令;节点类只保存结构。

结构图:

classDiagram
 class NodeVisitor {
  +visit(node)
  +generic_visit(node)
 }
 class Evaluator {
  +visit_Number(node)
  +visit_Add(node)
 }
 class StackCode {
  +generate_code(node)
  +binop(node, instruction)
  +unaryop(node, instruction)
 }
 NodeVisitor <|-- Evaluator
 NodeVisitor <|-- StackCode
 NodeVisitor ..> Node : 按实际类型名分派

虚线是访问依赖,非节点继承关系。新增操作可新建访问者;新增节点也需补齐相关处理方法。generic_visit在本例报未知类型,不自动继续父类型处理。

访问者分离节点与处理操作保存独立卡片。

原书依据 · 1 处

表达式节点显式保存操作数

表达式树用Number保存值,UnaryOperator保存一个operand,BinaryOperator保存left/right;Add等只标记运算类型。

结构图:

classDiagram
 class Number {
  +__init__(value)
 }
 class UnaryOperator {
  +__init__(operand)
 }
 class BinaryOperator {
  +__init__(left, right)
 }
 Node <|-- Number
 Node <|-- UnaryOperator
 Node <|-- BinaryOperator
 BinaryOperator <|-- Add
 BinaryOperator <|-- Sub
 BinaryOperator <|-- Mul
 BinaryOperator <|-- Div
 UnaryOperator <|-- Negate
 BinaryOperator --> Node : left及right
 UnaryOperator --> Node : operand

继承表示节点类别,持有边表示树结构。运算逻辑在访问者中,树本身不自动处理求值、环检测或未知类型。

表达式节点显式保存操作数保存独立卡片。

原书依据 · 1 处

遍历顺序决定栈指令语义

生成栈机代码时,先递归产生左操作数指令,再产生右操作数指令,最后追加运算指令;数字节点产生PUSH。这个后序顺序使运算时操作数已在栈上,减法除法还需保持左右顺序。求值访问者可直接返回结果,但深树仍可能触及递归限制;原Negate求值应先访问operand,不能直接对Node取负。

遍历顺序决定栈指令语义保存独立卡片。

原书依据 · 1 处

8.22 实现非递归的访问者模式

非递归访问驱动器把未完成工作保存在显式栈中,生成器yield出子任务,再通过send取得子结果。递归调用转换为暂停与恢复后,Python调用栈不随同样方式加深,但显式栈仍按深度增长。

显式栈驱动暂停的访问过程

驱动器观察栈顶:节点替换为对应访问结果,生成器接收上次结果并yield下一任务,普通结果弹出保存给上一层。

结构图:

flowchart TD
 A[查看栈顶] --> B{类型}
 B -->|节点| C[分派访问并压入结果]
 B -->|生成器| D[send上次结果并压入产出]
 B -->|普通值| E[弹出并保存结果]
 D -->|结束| F[弹出生成器]
 C --> A
 E --> A
 F --> A
 D --> A

各节点表示驱动步骤而非代码类型。访问方法仍递归调用self.visit时不会自动消除递归;需改成yield子任务,显式栈和暂停帧仍消耗与深度相关内存。

显式栈驱动暂停的访问过程保存独立卡片。

原书依据 · 1 处

任务标记应区别于正常结果

若把所有Node都解释为待遍历任务,就无法把Node作为普通计算结果返回。用Visit(node)显式包住子访问请求,可把控制消息与数据区分开,返回Node时就不会误启动遍历。这个区别类似协议中的标签,而非仅靠“值看起来像节点”猜测;若其他结果也与控制类型冲突,同样需进一步定义封装契约。

任务标记应区别于正常结果保存独立卡片。

原书依据 · 1 处

生成器返回值须由驱动器接收

同步生成器允许return value,并把值放到StopIteration.value,原“使用return就SyntaxError”不是此版本机制的正确概括,已查语言说明(2026-10-27)。但本例驱动器捕获结束后只弹栈,没有取异常的value,所以其访问方法仍用yield交付结果;仅把yield改成return会丢结果,语法允许不等于本协议支持。

本章 readline 以普通生成器的 return 返回拼接好的字节串,调用者用 yield from readline(client) 接收它;这提供了委派同时传递中间等待事件和最终返回值的实例。send 的参数进入暂停的 yield 表达式,委派的最终结果来自子生成器的 StopIteration.value。任务错误传播与 close 清理仍需独立设计。

生成器返回值须由驱动器接收保存独立卡片。

原书依据 · 2 处

8.23 在环状数据结构中管理内存

对象可达性与资源释放时机应分开考虑。父对子节点强引用、子对父节点弱引用可以保留导航而不额外维持父的生存;不过弱引用可能失效,垃圾回收也不是外部资源关闭协议。

弱引用不维持目标存活

weakref.ref不因这条引用而让目标保持存活;调用弱引用对象可得到仍在的目标,否则为None。树中父强持有children、子弱指向parent,可避免这两条边形成强引用环。

结构图:

classDiagram
 class Node {
  +__init__(value)
  +add_child(child)
 }
 Node --> Node : children强引用
 Node ..> Node : parent弱引用

虚线表示此例弱引用而非继承。使用前要取得并检查目标,原parent.setter不支持直接设None,若需要断开需补此契约;弱引用不让任意环自动消失。

弱引用不维持目标存活保存独立卡片。

原书依据 · 1 处

循环回收不替代显式资源关闭

CPython引用计数能处理许多无环对象,循环引用另由循环收集机制处理,回收时机不能作为资源释放保证。现代Python自3.4已改进带del循环的终结,原“只要有析构就永不回收”不成立,已查gc说明(2026-10-27)。仍需考虑复活、异常和实现差异;文件、连接等应显式close或with,不依赖del变量立刻销毁对象。

循环回收不替代显式资源关闭保存独立卡片。

原书依据 · 1 处

8.24 让类支持比较操作

排序支持需要先定义比较依据,再决定如何补齐操作符。total_ordering减少样板,但它不会为不一致的相等和顺序关系修复语义,跨类型不支持也应明确表示。

比较运算须有一致的价值依据

total_ordering可由eq和一个顺序方法补齐缺少的排序操作。House例按总面积比较,所以相等只表达面积相等,不等于房子身份相同;比较依据必须符合用途。对不支持类型应返回NotImplemented让协议继续处理,而非直接假定都有面积字段。原展示lambda只是解释示意,不能当当前装饰器精确源码;它也不替代比较一致性和性能验证。

比较运算须有一致的价值依据保存独立卡片。

原书依据 · 1 处

8.25 创建缓存实例

实例缓存把输入键映射到已有对象,工厂入口可避免缓存命中仍重跑初始化。弱值缓存只在对象仍被其他强引用持有期间复用,而非保证某键终生唯一;并发与绕过入口还需额外约束。

弱值缓存只复用仍存活的实例

WeakValueDictionary弱持有缓存值,其他地方仍强引用对象时可按键复用;对象不再可达时条目可消失,之后同键请求可新建。因此它不是永久单例或持久身份系统。对象应支持弱引用,缓存键也需稳定;先检查再创建并非线程安全的唯一性保证,若并发要求唯一需另做同步。

弱值缓存只复用仍存活的实例保存独立卡片。

原书依据 · 1 处

缓存命中应避免重复初始化

只在new返回已有同类实例,通常仍会继续执行init,可能重置已有状态。单独工厂在命中时直接返回对象,可清晰区分新建与复用;类本身若仍公开,直接构造也可绕过缓存。私有命名或禁止普通init只是接口约定,不构成安全隔离,备用_new必须返回构造好的实例。

元类call在缓存命中时直接返回,可跳过整个普通创建与初始化路径;但示例只支持可哈希位置参数,弱值回收和并发竞态仍需按身份契约处理。

缓存命中应避免重复初始化保存独立卡片。

原书依据 · 2 处

缓存管理器分离复用策略

CachedSpamManager负责按键获取、保存弱值和清空缓存,Spam负责对象数据,使复用策略可独立调整。

结构图:

classDiagram
 class CachedSpamManager {
  +__init__()
  +get_spam(name)
  +clear()
 }
 class Spam {
  +__init__(name)
 }
 Spam --> CachedSpamManager : manager
 CachedSpamManager --> WeakValueDictionary : _cache
 CachedSpamManager ..> Spam : 未命中时创建

箭头区分持有与创建依赖。clear只移除缓存关联,不销毁外部仍持有对象;清空后可能出现同键多个活实例,因此需明确身份保证的范围。

缓存管理器分离复用策略保存独立卡片。

原书依据 · 1 处

第9章 元编程

元编程在已有程序之上建立规则。装饰器介入调用并保留必要身份,签名服务检查与展示;元类介入类创建,动态执行和AST则直接操作程序表示。它们作用时点不同,复杂程度也不同,应先明确要统一的行为,再选择足够的机制。

元编程集中重复定义的规则

元编程让程序通过包装、生成或修改函数与类,集中原本需要复制的规则。装饰器处理可调用或类,元类介入类创建,签名检查与exec/内部结构检查则是其他层面。目的应是减少重复且明确行为,不是越隐蔽越高级;动态代码会增加追踪、接口与错误定位成本,后续条目需分别说明边界。

元编程集中重复定义的规则保存独立卡片。

原书依据 · 1 处

9.1 给函数添加一个包装

包装函数在原调用前后加入处理,再把参数和结果继续传递。装饰语法只是在定义后把名字重新绑定为包装结果,接口和失败语义是否保留取决于实现,而非语法自动保证。

装饰器包装应保留调用契约

@decorator等价于定义函数后把名字绑定为decorator(func)的结果。典型wrapper接收args/kwargs、调用原函数并返回其结果,额外加入日志或计时;包装也可能改变行为,必须明确而非假定总透明。原计时只在成功返回后记录,异常时不记录;time.time是墙钟,不把示例当精确单调基准或生成器实际执行计时。

装饰器包装应保留调用契约保存独立卡片。

原书依据 · 1 处

9.2 编写装饰器时如何保存函数的元数据

包装后的对象需保留名字、文档和注解等可检查信息,wraps提供常用元数据复制并建立被包装关系。签名工具能循此关系展示原接口,但实际包装器仍可接收可变参数。

wraps保留身份

functools.wraps把原函数的常用元数据复制到wrapper并设置wrapped关联,避免名字、文档等只剩包装器信息。inspect.signature通常沿该关系展示原签名,但没有把wrapper真实参数自动改成原函数形式,也不自动检查透传是否正确。元数据保留有助调试与工具,不能据此证明返回值、异常和副作用都透明。

wraps保留身份保存独立卡片。

原书依据 · 1 处

9.3 对装饰器进行解包装

解包装用于取得包装层内部的可调用对象,层数和链是否存在取决于元数据约定。现代wraps维护直接被包装对象的链,原3.3一次绕全部层是历史缺陷,不应成为当前假设。

解包装须沿真实包装链

若装饰器提供wrapped,访问它可绕过一层包装,继续沿链可找到更内层目标;不提供该属性的包装不能据此自动还原。3.4起wraps所设wrapped明确指直接被包装对象,原3.3绕全部层示例是历史问题,见官方说明(核验2026-10-27)。解包装会绕过日志、验证等行为,适合受控调试,不等于撤销外部副作用。

解包装须沿真实包装链保存独立卡片。

原书依据 · 1 处

9.4 定义一个可接受参数的装饰器

带参数装饰器先接收配置并返回真正装饰器,再接收目标函数,最后产生运行时包装器。三个阶段把配置、目标和每次调用参数分开,各自作用时点不同。

带参装饰分清配置与调用阶段

@decorator(x,y)先执行配置工厂得到装饰器,再把函数传入得到包装结果;之后每次调用才运行wrapper。logged例在配置闭包中保存日志级别和消息,wrapper记录后调用目标。定义时取默认模块名与函数名,不等于每次调用重新求配置;若空字符串也合法,原if name/message的真值回退策略需明确。

带参装饰分清配置与调用阶段保存独立卡片。

原书依据 · 1 处

9.5 定义一个属性可由用户修改的装饰器

可调整包装器通过访问函数修改闭包里的配置,再把这些入口作为函数属性公开。外层wraps可复制入口引用,因此仍触及原来的共享状态;直接改外层同名普通属性则未必影响内层。

闭包可通过访问函数暴露状态关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

包装器配置通过访问函数修改

把set_level/set_message等函数附到wrapper,内部用nonlocal修改真正被调用逻辑读取的配置。外层wraps默认复制函数字典时可传播这些入口,仍引用原闭包,因此比修改外层普通level属性更能作用到内层。传播有复制时点与重名冲突边界,不保证所有自定义wraps选项都保留;并发修改也不自动形成一致快照。

包装器配置通过访问函数修改保存独立卡片。

原书依据 · 1 处

9.6 定义一个能接收可选参数的装饰器

同一装饰器支持裸用和带配置调用时,要区分第一步是否已经收到目标函数。把配置限定为关键字,可以减少它们与目标位置参数的歧义,再用partial延后接收目标。

可选装饰参数需区分两种调用

装饰器以func=None加仅关键字配置接收两种形式:@logged直接得到func并包装;@logged(…)先未收到目标,返回预置配置的partial,再接收函数。这样也可支持@logged(),但不是任意位置配置都能自动判别。检查是否缺目标应按明确哨兵约定,配置默认值与包装后的运行参数分别管理。

可选装饰参数需区分两种调用保存独立卡片。

原书依据 · 1 处

9.7 利用装饰器对函数参数强制执行类型检查

类型检查装饰器先把类型声明映射到签名参数,再把每次实参按同一签名绑定后检查。绑定能复用Python的调用规则,但默认参数和可变参数仍有具体处理边界;优化模式关闭检查也改变契约。

签名绑定区分部分与完整调用

inspect.signature得到参数名、种类与默认值;bind_partial允许省略必填参数,适合只声明部分类型,bind则检查一次合法调用所需的参数。bind仍允许省略有默认值的参数,不是必须显式传全部参数;绑定结果默认只含已提供值,要检查缺省值需另行apply_defaults或按契约处理。

签名绑定区分部分与完整调用保存独立卡片。

原书依据 · 1 处

运行类型断言须定义检查范围

typeassert用isinstance检查已绑定且有类型声明的参数,并不自动检查返回值、容器内部元素或业务约束。默认值未提供时不在原检查循环中;可变参数在绑定结果里是元组/字典,不能假定自动逐元素检查。原if not debug会在优化模式直接返回原函数,因此它是可关闭断言,不宜作为始终生效的外部输入保护。

运行类型断言须定义检查范围保存独立卡片。

原书依据 · 1 处

9.8 在类中定义装饰器

定义在类里的装饰器也是可调用属性,使用实例方法时先绑定实例,使用类方法时绑定类。包装器处理的是另一个目标的调用参数,不应把两处self或cls混为一谈。

装饰器所属对象与目标参数分开

实例装饰方法decorator1先绑定装饰器拥有者a,类装饰方法decorator2先绑定A;返回的wrapper再接收被包装函数自己的参数。它可闭包使用拥有者,却不该无端给目标多塞一个self。子类定义体中B尚未创建,不能用B装饰自己的方法;可用已存在的A类方法或其他可用装饰器,原“必须类方法”只适用于给出的写法。

装饰器所属对象与目标参数分开保存独立卡片。

原书依据 · 1 处

9.9 把装饰器定义成类

用实例充当包装器时,call处理调用,而get负责放在类上时产生绑定方法。计数状态存在包装器上,意味着同一类方法被多个实例使用也共享该计数,而非每个业务实例自动独立。

可调用包装器还需方法绑定

Profiled用call计数并转调wrapped,用get在实例访问时构造MethodType,使被包装方法收到业务实例self;类访问则返回包装器本身。

结构图:

classDiagram
 class Profiled {
  +__init__(func)
  +__call__(*args, **kwargs)
  +__get__(instance, cls)
 }
 Spam --> Profiled : 类属性bar持有包装器
 Profiled ..> MethodType : 实例访问时构造绑定
 Profiled ..> callable : __wrapped__调用目标

持有、构造和调用依赖不同;只有call而无get,普通可调用对象不会自动像函数一样补入self。

可调用包装器还需方法绑定保存独立卡片。

原书依据 · 1 处

包装器计数须明确共享口径

Profiled在调用目标前递增ncalls,所以记录尝试调用次数,目标失败也已计入;类属性bar的包装器还被所有业务实例共享。闭包nonlocal计数可以替代可调用类,但暴露接口不同,示例是ncalls()而非数值属性。计数自增不自动线程安全,也不能从次数直接得出执行耗时或成功量。

包装器计数须明确共享口径保存独立卡片。

原书依据 · 1 处

9.10 把装饰器作用到类和静态方法上

多层装饰器由下而上应用,普通包装器若预期输入函数,应先包装函数再交给classmethod或staticmethod建立方法语义。不同版本中描述符的可调用性有变化,不能只用旧错误断言所有顺序永远失败。

装饰顺序须符合输入对象协议

普通函数包装器放在靠近def的内层,classmethod/staticmethod放外层,可让包装器接收函数并保留后续绑定语义;这里“先”是应用顺序,不是源码自上而下。现代staticmethod对象自3.10也可直接调用,原反例的不可调用错误并非所有当前版本都重现,但其他绑定语义仍须核对,见官方说明(核验2026-10-27)。abstractmethod同样按协议放在内层。

装饰顺序须符合输入对象协议保存独立卡片。

原书依据 · 1 处

9.11 编写装饰器为被包装的函数添加参数

包装器新增的参数需要由自己消费,再把其余参数传给目标;这会扩展接口而非保持完全相同。名称冲突检测和对外签名应一起调整,支持kwargs的目标还存在更隐含的冲突可能。

包装器新增参数须处理冲突

wrapper可用仅关键字debug控制日志并在转调前消费它,避免传给不认识debug的目标;但同名参数会被截走,须先检测并定义冲突策略。应从inspect.signature的parameters核对各种参数种类,旧getargspec已在3.11移除,见官方迁移说明(核验2026-10-27)。若目标本来通过kwargs接受debug,也需说明包装改变了该含义。

包装器新增参数须处理冲突保存独立卡片。

原书依据 · 1 处

显示签名也须遵守参数顺序

可通过Signature.replace与Parameter为包装器展示新增keyword-only参数,但必须保持合法顺序,不能把debug无条件追加在**kwargs之后。signature只影响检查工具的视图,实际运行仍由wrapper处理;仅加元数据不形成参数验证。接口改变时应使实际接受规则、帮助信息与冲突错误一致。

显示签名也须遵守参数顺序保存独立卡片。

原书依据 · 1 处

9.12 利用装饰器给类定义打补丁

类装饰器在类创建后接收类对象,可替换或包装其方法而不增加继承层。操作属性入口时尤其要避免无意递归,并保留原方法以继续正常查找。

类装饰补丁应保留原调用路径

类装饰器可保存原getattribute,再安装带日志的新入口并继续调用原实现,避免为日志绕回同一个属性查找入口造成递归。它修改的是类本身,不必加入mixin继承;多个补丁的替换与包装次序会改变最终行为。getattribute比缺失时的getattr范围更广,但特殊协议也有自身查找规则,不能宣称记录所有内部操作。

类装饰补丁应保留原调用路径保存独立卡片。

原书依据 · 1 处

9.13 利用元类来控制实例的创建

类本身也是可调用对象,其调用行为由元类call控制。拦截这一步可以拒绝普通构造、返回已有单例或按键复用实例;缓存命中时不再进入普通创建链,但唯一性的范围需要定义。

缓存命中应避免重复初始化关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

元类调用控制普通实例创建

元类重写call可在类被调用时先判断,再决定是否super().call执行普通创建。

结构图:

classDiagram
 type <|-- Cached
 class Cached {
  +__init__(*args, **kwargs)
  +__call__(*args)
 }
 Cached ..> Spam : 元类控制类调用
 Cached --> WeakValueDictionary : 每类缓存

继承指元类继承type,虚线表示类调用控制关系,不是Spam继承Cached。命中直接返回现有实例,可避免8.25的仅new缓存后init重跑;正常构造之外的入口仍可能绕过限制。

元类调用控制普通实例创建保存独立卡片。

原书依据 · 1 处

单例与参数缓存须约定身份范围

Singleton例每个类保存一个实例,首次构造后再次传参会直接拿旧对象,后续参数不再初始化;Cached例则按位置args元组分组,要求可哈希,且不接受kwargs。弱值对象被回收后可再创建,因此不是永久同键唯一。两者检查后创建都缺并发同步;普通入口单例不自动保证跨进程、清理后或绕入口仍唯一。

单例与参数缓存须约定身份范围保存独立卡片。

原书依据 · 1 处

9.14 获取类属性的定义顺序

prepare在类体执行前提供命名空间,因而可以记录写入或检测重复定义;new在类体结束后再把声明整理为最终类。定义顺序只是声明协议的一部分,与CSV转义和数据库类型映射分别处理。

打印分隔符不等于序列化格式关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

类命名空间可在执行前定制

元类prepare先返回供类体执行的映射,类体写入其中后,元类new可扫描字段并建立_order等声明信息。

结构图:

classDiagram
 type <|-- OrderedMeta
 class OrderedMeta {
  +__prepare__(clsname, bases)
  +__new__(clsname, bases, clsdict)
 }
 OrderedMeta ..> OrderedDict : 旧例准备命名空间
 OrderedMeta ..> Structure : 创建类对象
 Structure <|-- Stock

继承与类创建依赖不同;现代默认类命名空间已保持定义顺序,OrderedDict不是唯一办法。自定义prepare仍可拦截写入,再向type.new提供适当dict;还须保留必要的类创建信息。

类命名空间可在执行前定制保存独立卡片。

原书依据 · 1 处

拒绝重复定义须约定合法重绑定

自定义类命名空间的setitem可拒绝已存在键,从而在类体内发现重复方法名。但属性getter/setter、装饰后的同名重绑定等可能正是合法用法,不能把所有再次写入都当疏失。建立严格规则时应明确哪些声明允许重复与错误时点;类创建后检查只看最终值,可能已经失去早期写入历史。

拒绝重复定义须约定合法重绑定保存独立卡片。

原书依据 · 1 处

9.15 定义一个能接受可选参数的元类

类头关键词能配置类创建过程,且在类体执行之前就供prepare使用。各阶段需要兼容这些参数,并按各自职责消费或转交,不能把类创建配置误混成实例构造参数。

元类配置贯穿类创建阶段

类定义头可带元类配置关键词,prepare先据配置准备命名空间,类体完成后new创建类,init完成额外初始化。配置不必成为类属性,因此不会像类体变量那样直接进入声明命名空间。各参与方法需有兼容接收和转交策略,尤其别把专用配置泄漏给不支持它的基类钩子;原两方法都必写是示例兼容设计,不是所有现代实现的硬性规则。

元类配置贯穿类创建阶段保存独立卡片。

原书依据 · 1 处

9.16 在*args和**kwargs上强制规定一种参数签名

签名对象把参数名、位置规则和默认值显式描述出来,bind再把可变实参映射到这些参数。让检查工具看见签名和在调用时真正执行绑定是两件事,二者结合才形成可观察的运行约束。

签名也是接口

Signature由Parameter描述参数名、种类与默认值,bind可对args/kwargs验证必填、重复、未知或过多实参并得到名称映射。signature让检查工具展示约定,却不自动执行检查,通用函数仍须在运行时bind。默认值未显式提供时不在原映射中,若要设为对象属性需另行补入;这同时关联签名绑定区分部分与完整调用。

签名也是接口保存独立卡片。

原书依据 · 1 处

字段签名可驱动结构初始化

StructureMeta把_fields转换为signature,Structure初始化时bind再按名字setattr,子类声明字段即可获得参数检查。

结构图:

classDiagram
 type <|-- StructureMeta
 class StructureMeta {
  +__new__(clsname, bases, clsdict)
 }
 class Structure {
  +__init__(*args, **kwargs)
 }
 StructureMeta ..> Structure : 建类时安装签名
 Structure <|-- Stock
 Structure <|-- Point
 Structure ..> Signature : bind实参

继承、类创建及使用依赖分开。原元类只取本次类字典_fields,不自动合并基类字段;字段名字与签名合法性仍须检查,验证调用形状也不等于字段值类型正确。

字段签名可驱动结构初始化保存独立卡片。

原书依据 · 1 处

9.17 在类中强制规定编码约定

框架可在定义子类时检查命名或重写签名,让诊断不依赖使用者一定运行某个IDE。创建前检查声明与创建后按MRO查找基类是不同介入时点,警告也不等于禁止使用。

元类介入创建

元类是创建类对象的类型。类体先形成名称空间,再由选定元类参与建立类;元类的new可以在创建前检查或改变定义,init可以对已创建的类做进一步初始化与诊断。框架可将元类放在根类型上,使后续子类定义经过统一规则。

类创建与普通实例创建不是同一阶段;元类call另可控制类被调用时如何生成实例。命名检查、注册等机制应服务明确的框架契约,并考虑多继承的元类兼容性,不把类定义检查误认为全面的运行期行为验证。

元类介入创建保存独立卡片。

原书依据 · 1 处

类定义检查须选择介入时点

元类new适合在创建类对象前检查或改类字典,init适合对已创建并具备MRO的类继续诊断。把元类用于框架根类型,可使后续子类参与同类检查,但多元类兼容和主动绕开框架仍需考虑。原NoMixedCase例return缩进在for内会提前退出,必须检查完相关名字再建类;规则也应针对真实目标而非盲目禁止所有重绑定。

类定义检查须选择介入时点保存独立卡片。

原书依据 · 1 处

重写兼容性不等于签名完全相等

子类改参数名会破坏按关键字调用,改仅关键字为位置也可能改变契约;在类创建时比较基类与覆写签名有助提前告警。但完全相等是较严格的诊断规则,并非行为可替换的充分必要条件,也不检查返回语义。原检查跳过下划线名与非callable对象,因此覆盖范围有限;仅logging.warning也不会阻止类创建。

重写兼容性不等于签名完全相等保存独立卡片。

原书依据 · 1 处

9.18 通过编程的方式来定义类

程序化建类可以直接提供基类和成员映射,而不必拼接整段源码执行。new_class会经过元类选择与命名空间准备,再交回调填入成员;动态生成的类型仍须符合模块身份、声明和实例协议。

程序化建类应保留准备阶段

types.new_class接收类名、基类元组、类头关键词和填命名空间的回调,支持元类选择与prepare流程;直接type(name,bases,dict)不替调用者执行同样的命名空间准备。prepare_class可单独取得元类、剩余关键词和命名空间。回调处理的是prepare返回的映射,不应假定一定普通dict;新方法的super等词法语义也不会仅因装入类就自动获得。

程序化建类应保留准备阶段保存独立卡片。

原书依据 · 1 处

动态类型身份需与模块绑定一致

动态类的module影响表示及序列化查找,应设置为真实模块身份,并让需要导入查找的类在模块相应名称可访问。只改字符串不自动使pickle成功,也不复制类实现。借调用帧确定模块是实现相关技巧,显式传入身份通常更清楚;动态生成仍须考虑名称冲突和版本演化。

动态类型身份需与模块绑定一致保存独立卡片。

原书依据 · 1 处

元组工厂仍须验证字段定义

示范named_tuple用tuple子类保存值,按字段索引装property,并以new检查实参数量,展示声明生成类型。

结构图:

classDiagram
 tuple <|-- Point
 class Point {
  +__new__(*args)
 }
 class named_tuple {
  <<函数工厂非类型>>
 }
 named_tuple ..> Point : 构造类型并安装字段访问器

它不是标准namedtuple的等价实现:需验证字段名与冲突,且未设空slots时仍可能有实例字典;元组元素不可重赋不等于整个对象无额外状态。

把同类访问器安装工作移到元类初始化,可在每个派生类定义时完成;不可变元组内容仍应在实例new阶段创建。字段名冲突、重复和额外实例字典等限制并未因此自动消除。

元组工厂仍须验证字段定义保存独立卡片。

原书依据 · 2 处

9.19 在定义的时候初始化类成员

类定义时安装字段访问器只需对每个新类型做一次,实例分配则在之后每次调用时发生。元组等不可变内容要在new阶段构造,init已经无法重写这些元素。

元组工厂仍须验证字段定义关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

类初始化与实例初始化分时发生

StructTupleMeta在类创建时按_fields安装索引property,StructTuple的new则在每次构造时检查参数并建立元组内容。

结构图:

classDiagram
 type <|-- StructTupleMeta
 class StructTupleMeta {
  +__init__(*args, **kwargs)
 }
 tuple <|-- StructTuple
 class StructTuple {
  +__new__(*args)
 }
 StructTupleMeta ..> StructTuple : 建类时安装访问器
 StructTuple <|-- Stock
 StructTuple <|-- Point

元类控制类对象,普通继承控制实例类别。new为不可变元组建立内容,init时再改元素已经太晚;字段声明仍需验证,原实现不等价于完整namedtuple。

类初始化与实例初始化分时发生保存独立卡片。

原书依据 · 1 处

9.20 通过函数注解来实现方法重载

多分派例把同名方法按参数类型收集成映射,调用时查类型元组选择实现。自定义类命名空间负责保留重复定义,描述符负责方法绑定;这不是Python原生自动重载,也不处理所有调用兼容关系。

同名方法收集需自定义命名空间

普通类体同名定义通常覆盖前值;MultipleMeta用prepare返回MultiDict,写入重复方法名时合并到MultiMethod,new再建类。

结构图:

classDiagram
 type <|-- MultipleMeta
 dict <|-- MultiDict
 class MultipleMeta {
  +__prepare__(clsname, bases)
  +__new__(clsname, bases, clsdict)
 }
 class MultiDict {
  +__setitem__(key, value)
 }
 class MultiMethod {
  +register(meth)
  +__call__(*args)
  +__get__(instance, cls)
 }
 MultipleMeta ..> MultiDict : 准备类体映射
 MultiDict --> MultiMethod : 收集同名实现

继承和创建/持有依赖不同。重复非方法声明也会被这段合并逻辑处理,可能报错;不能认为所有同名赋值都该当作重载。

同名方法收集需自定义命名空间保存独立卡片。

原书依据 · 1 处

精确类型分派不等于子类匹配

MultiMethod以实参实际type元组查映射,跳过方法self;注册时按参数注解建立键,对默认尾参数还注册较短前缀。因此A注解不会自动匹配B子类实例,bool也不会仅因是int子类就命中int键。原call只收位置参数,不支持kwargs;若要支持,须先按候选签名规范化并定义冲突优先级,而非简单改参数列表。

精确类型分派不等于子类匹配保存独立卡片。

原书依据 · 1 处

注解分派须限定注解与重名规则

原注册器要求注解是实际type对象,不能自动处理字符串注解、联合类型或任意现代typing表达式;读取注解的版本求值语义也需另定。相同类型元组重复注册会覆盖旧映射,不自动报告歧义。默认参数缩短映射同样可能碰撞;这是特定演示协议,不是所有Python类型提示都可直接拿来运行时重载。

注解分派须限定注解与重名规则保存独立卡片。

原书依据 · 1 处

显式分派注册可替代重定义收集

装饰器版multimethod用默认方法加match(types)显式注册实现,避免元类在类体收集重复定义;实例访问仍由get绑定self。它仍按精确位置类型查表,未命中才调用默认实现,且默认值会形成多个前缀键。两种方案都有维护和调试成本;简单不同操作用不同名字,通常比隐式分派更清楚。

显式分派注册可替代重定义收集保存独立卡片。

原书依据 · 1 处

9.21 避免出现重复的属性方法

闭包工厂可生成多个遵循同一逻辑的property,每次保存自己的字段名和预期类型。这样抽取重复代码而仍保留属性接口,和可复用描述符是两种相关表达方式。

重复属性验证宜抽取机制关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

属性工厂用闭包保存字段配置

typed_property接收字段名和类型,创建共享这次配置的getter/setter,再返回property;每次工厂调用保留独立闭包,避免复制相同验证代码。partial还可预置str/int形成更短声明。后备名称约定、类型子类语义及缺失值仍需明确,这种工厂不是文本宏,也不会自动验证跨字段关系。

属性工厂用闭包保存字段配置保存独立卡片。

原书依据 · 1 处

9.22 以简单的方式定义上下文管理器

contextmanager把一次生成器暂停点用作with主体的入口和出口连接。yield前准备、yield值供as使用,主体异常在yield处重新进入生成器,因此清理应放finally,正常提交则放正常恢复路径。

生成器上下文用暂停点连接退出

contextmanager把生成器包装成上下文管理器:进入时运行到yield,yield值交给as,退出时恢复;主体异常会在yield处抛回。必须恰好yield一次,资源清理通常用try/finally,若捕获异常却不重抛可能抑制它。仅把代码写在yield后不保证异常时执行;它适合提供资源管理入口,但不自动把已有对象变成同一with协议。

生成器上下文用暂停点连接退出保存独立卡片。

原书依据 · 1 处

浅拷贝事务只隔离列表结构

list_transaction先浅复制列表,正常退出再用切片覆盖原列表,异常路径不提交这份结构修改。它不复制内部元素,若元素本身可变,工作副本修改元素也会影响原对象;主体若直接改原列表也不受保护。没有并发隔离、持久性或一般回滚保证,因此这是有限的列表编辑模式,不是数据库事务。

浅拷贝事务只隔离列表结构保存独立卡片。

原书依据 · 1 处

9.23 执行带有局部副作用的代码

exec中的命名空间与函数编译出的局部绑定并非同一回事。需要可靠取得执行结果时,应显式提供字典并从中读值,而不是依赖旧版locals字典在不同调用间共享的副作用。

exec需要边界

exec会执行代码,应明确代码来源、可用全局和局部命名空间及结果取得方式。需要结果时显式准备glb/loc字典传入,再从loc取值,不依赖它自动生成调用者的局部变量。空globals也不是安全沙箱,解释器可补入内建对象;检查部分AST同样不足以保证任意代码安全。能用闭包、配置数据或常规函数表达时,通常更易控制。

exec需要边界保存独立卡片。

原书依据 · 1 处

局部命名空间副作用有版本边界

函数内裸exec与locals的交互不能靠3.3示例推断当前行为。3.13起优化作用域中locals每次返回独立快照,默认exec的局部命名空间也调整,因此先保存locals再裸exec后读旧字典不再可靠,见官方说明(核验2026-10-27)。需要可检查副作用应把同一个显式字典传给exec,并从该字典读取结果。

局部命名空间副作用有版本边界保存独立卡片。

原书依据 · 1 处

9.24 解析并分析Python源代码

AST把源代码表达为节点结构,访问者可检查名称等语法信息而不直接运行目标。改写AST再替换函数代码则远不止分析,它会改变名字绑定和执行时点,必须验证语义及版本契约。

语法树分析不同于执行代码

ast.parse将源代码解析为节点,CodeAnalyzer通过Name的Load/Store/Del上下文收集名字使用。

结构图:

classDiagram
 NodeVisitor <|-- CodeAnalyzer
 class CodeAnalyzer {
  +__init__()
  +visit_Name(node)
 }
 CodeAnalyzer ..> Name : 读取id和ctx

虚线为分析依赖,继承使用标准ast访问协议。三个名字集合只反映这些语法节点,不是完整作用域、数据流或安全性证明;parse不运行代码,后续compile/exec则是独立执行步骤。

语法树分析不同于执行代码保存独立卡片。

原书依据 · 1 处

全局名下沉会改变读取时点

NameLower把选定全局名的赋值插入函数开头,使循环内部改读局部变量;原变量仍在每次函数调用起始从globals读取,而非装饰时永久绑定。函数运行中全局名再改变,局部快照不会跟随,因此这种优化可能改变语义。插到原文档字符串前还可能影响文档元数据,需按真实函数结构处理;原快20%仅历史基准未复测。

全局名下沉会改变读取时点保存独立卡片。

原书依据 · 1 处

源码重编译须保留函数环境

获取源码、去装饰器行、改AST并重编译,最后替换code,可能遇到源码不可得、缩进、其他装饰器、默认表达式副作用与闭包自由变量不兼容。仅赋回代码对象不证明与原函数语义等价,现代AST节点字段也有版本变化,应依官方AST文档核对(2026-10-27)。不应批量用于所有函数,更不能靠局部语法检查把不可信exec变安全。

源码重编译须保留函数环境保存独立卡片。

原书依据 · 1 处

9.25 将Python源码分解为字节码

反汇编把函数实现展成解释器指令,适合研究执行机制,但指令是实现和版本细节。观察与修改要分开:原始字节码及代码对象的合法性约束很多,错误替换可以直接破坏解释器。

字节码分析依赖解释器版本

dis可反汇编函数,辅助理解名字加载、跳转和调用等实现;字节码不是跨版本稳定格式,也不代表所有Python实现都用相同指令。现代dis提供get_instructions等程序化接口,原“没有这种函数”是旧版背景,见官方文档(核验2026-10-27)。不能把3.3逐字节解析器、指令宽度和旧跳转偏移套到当前解释器。

字节码分析依赖解释器版本保存独立卡片。

原书依据 · 1 处

修改代码对象须满足整套不变量

替换code不仅是换一串字节:参数信息、常量、名字、栈大小、跳转和异常等元数据必须相互兼容,CodeType构造签名也随版本变化。原非法字节例导致段错误,说明不能把运行解释器当成任意字节码验证器。研究时先观察官方反汇编接口,改写需隔离环境与严格版本约束;本次未创建或执行非法代码对象。

修改代码对象须满足整套不变量保存独立卡片。

原书依据 · 1 处

第10章 模块和包

模块给名称和加载行为提供边界。普通包、命名空间包、相对导入和重载分别处理组织、分布、归属及更新;资源读取不应依赖一定存在普通文件路径。导入钩子揭示查找、加载和缓存的分层,打包与环境隔离又是另一层生命周期。

10.1 把模块按层次结构组织成包

普通包目录中的init建立该层命名空间,也可选择重导出子模块。层次文件路径对应导入名称,但代码是否执行还受导入缓存与实际查找机制影响,不能把每次导入都当重新初始化。

包定义命名边界

普通包以目录层次组织模块,init.py定义该层初始化与对外名称;可为空,也可显式导入所需子模块,形成较简洁入口。导入深层模块会先建立父包上下文,但已缓存模块通常不会每次重执行。没有init也可能形成命名空间包,不能把每层必须有init推广为所有包;重导出还会引入导入成本及循环依赖,应有意选择。

包定义命名边界保存独立卡片。

原书依据 · 1 处

10.2 对所有符号的导入进行精确控制

all变量定义星号导入时应导出的名字集合,表达公开接口意图。它不是访问控制:调用方仍可显式访问其他存在的名字,空列表也只影响星号导入的结果。

导出清单只约束星号导入

模块all列出from module import *应导入的名字;未声明时通常选不以下划线开头的名字,空清单则不导入这些符号。清单中名称应实际可用,包还可能涉及子模块加载。它有助限制星号污染,却不阻止显式import或属性访问,更不是安全隔离;公开接口仍需清晰维护。

导出清单只约束星号导入保存独立卡片。

原书依据 · 1 处

10.3 用相对名称来导入包中的子模块

相对导入表达模块在包中的归属,而非相对进程工作目录的文件路径。它让内部依赖少绑定顶层包名字,但要求运行时具备包上下文。

相对导入表归属

from . import grok表示当前包内同级模块,from ..B import bar表示上层包下B中的模块;句点按包上下文解析,不是任意文件系统父目录。只适用from语法,不能写import .grok。直接运行包内文件往往缺少该上下文,使用-m按模块名运行可保留;仅把文件放进某目录不证明具备正确导入身份。

相对导入表归属保存独立卡片。

原书依据 · 1 处

10.4 将模块分解成多个文件

把大模块改为包,可以拆分实现文件,再由init重导出原入口,降低调用方感知变化。惰性加载若用函数替代类则改变对象类别,不能仅因构造调用仍像原样就认定兼容。

拆分实现可保留统一导入入口

把mymodule.py改为同名包,a.py/b.py放实现,再在init重导出A/B,可让调用方继续from mymodule import A,B。内部跨文件依赖用明确相对导入,避免让用户知道所有实现位置。公开入口保持不等于完全兼容:对象模块身份、序列化路径、导入副作用和循环依赖仍需核对。

拆分实现可保留统一导入入口保存独立卡片。

原书依据 · 1 处

惰性工厂替代类会改变接口

用A()工厂在调用时导入真实类,可延后加载,但外部A从类变成函数;isinstance和继承基类用法不再成立,原零参工厂也没透传构造参数。应区分“按需导入”目标与“类接口保持”要求,不能只展示无参创建成功就断言用户无感。模块通常有缓存,延后第一次导入也不等于每次从头加载。

惰性工厂替代类会改变接口保存独立卡片。

原书依据 · 1 处

10.5 让各个目录下的代码在统一的命名空间下导入

命名空间包允许多个可发现目录贡献同一前缀下的子模块,便于独立分发插件。包的搜索路径与普通文件位置不同,诊断应检查真实导入元数据,而不是只猜某个属性是否存在。

命名空间包聚合多处分发内容

隐式命名空间包可在多个模块搜索位置中汇合同名前缀目录,各部分不放该层init,使独立分发的blah/grok等共处spam下。包的path用于继续找子模块,它是可动态更新的特殊可迭代路径,不宜当固定普通只读列表。file缺失或为None等表现依实现版本,不能用旧单一异常作判定,见导入说明(核验2026-10-27)。

命名空间包聚合多处分发内容保存独立卡片。

原书依据 · 1 处

10.6 重新加载模块

reload重新执行模块代码,但不会自动更新所有外部绑定或既有实例。模块字典与对象还可能保留历史状态,所以它不是一次完整替换或可靠热升级。

模块重载不会刷新外部旧引用

重载模块后通过module.name可取得新定义,但早先from module import name绑定的变量仍指旧对象;已有实例也不自动变成新类。多处新旧版本共存会导致不一致,因此重载适合受控调试,不能据一处输出更新就当运行系统已完整升级。还需处理重执行的副作用、依赖顺序和失败后的状态。

模块重载不会刷新外部旧引用保存独立卡片。

原书依据 · 1 处

重载保留字典可能残留旧名称

现代重载用importlib.reload;旧imp模块已在3.12移除。reload保留模块字典,新代码重新定义的名字被覆盖,旧代码存在而新代码未定义的名字可能残留;原“先清空字典”错误,已查reload文档与imp迁移(2026-10-27)。它并非通用线程安全的原子刷新,也不自动重载其他模块。

重载保留字典可能残留旧名称保存独立卡片。

原书依据 · 1 处

10.7 让目录或zip文件成为可运行的脚本

多文件程序可用main模块作为目录或ZIP执行入口,使分发包有清晰的启动点。打包执行不等于安装所有依赖,更不自动提供跨平台启动脚本或解释器。

目录与压缩包须有执行入口

在待执行目录或ZIP根提供main.py,Python可把它作为主程序运行,其他文件成为同一分发内容。这样方便分发多文件应用,但仍需兼容解释器及依赖,ZIP不能无条件承载所有原生扩展加载方式。启动器的shebang参数解释依平台,原env带多个词的示例不保证可移植;应在目标环境验证入口,而非只检查归档存在。

目录与压缩包须有执行入口保存独立卡片。

原书依据 · 1 处

10.8 读取包中的数据文件

包内资源不一定对应可直接打开的磁盘路径,用加载器支持的资源接口比假设工作目录更可靠。得到字节后,文本解释和缺失资源的处理仍需明确。

包内资源不必是普通磁盘文件

按包名和包内相对名读取资源,可避免依赖当前工作目录,也可适配支持资源读取的归档加载器;pkgutil.get_data返回字节,但并非任何加载器或命名空间包都支持它,见官方API(核验2026-10-27)。文本仍需按正确编码解码;包是否包含该资源也要由分发配置保证,不能只在源码目录中有文件。

包内资源不必是普通磁盘文件保存独立卡片。

原书依据 · 1 处

10.9 添加目录到sys.path中

模块搜索路径是环境配置的一部分,硬编码机器目录会降低可迁移性。PYTHONPATH和site处理的pth文件可把配置移出源码,但路径顺序与解释器启动选项仍影响真实导入来源。

模块路径配置须明确解释器环境

PYTHONPATH或被site处理的.pth文件可添加模块搜索位置,减少在源码硬编码机器路径;实际生效受所用解释器、启动模式与安装位置影响。顺序改变还可能遮蔽同名模块,应核对真实来源。file计算相邻源码目录时需用变量本身及正确join,原dirname字面字符串和abspath多实参写法错误;本次不执行路径修改。

模块路径配置须明确解释器环境保存独立卡片。

原书依据 · 1 处

10.10 使用字符串中给定的名称来导入模块

模块名字符串可以交给标准导入接口,不必拼代码送exec。该操作仍会执行模块初始化及依赖导入,动态选择的范围需要由应用契约限定。

动态导入仍执行模块初始化

importlib.import_module(name)按导入机制加载并返回指定模块对象,适合配置化选择;相对名需要额外包上下文参数。它比手拼import源码清楚,但仍执行目标模块初始化,名称也受搜索路径影响;外部输入不应直接成为不受限导入权限。与import的返回层次约定不同,调用后变量绑定由程序自己完成。

动态导入仍执行模块初始化保存独立卡片。

原书依据 · 1 处

10.11 利用import钩子从远端机器上加载模块

导入扩展把找位置、产生加载方案和执行代码拆开。元路径查询器可参与整个查找过程,路径钩子则为特定路径项提供查询器;模块身份、包路径、缓存、失败清理与来源信任都是协议的一部分。原实现基于3.3接口,只用来解释职责,不作为当前可直接安装的加载器。

导入钩子改加载

导入可通过元路径查询器参与全局查找,或用路径钩子为sys.path/包路径项提供查询器。查询器决定能否处理模块,加载器负责取得并执行代码。现代协议围绕find_spec和ModuleSpec及create_module/exec_module组织,原find_module/find_loader/load_module为旧接口,需迁移后才能使用,已查导入文档(2026-10-27)。钩子只改变加载来源,不降低执行任意模块代码的信任要求。

导入钩子改加载保存独立卡片。

原书依据 · 1 处

查询顺序与模块缓存共同选来源

模块先可能由sys.modules命中,未命中才继续查询器查找;把自定义元查询器放前面可优先处理,放后面通常仅补未找到项。优先处理也可能遮蔽本地同名模块,不能视为无影响扩展。原打印每次import日志只在未缓存等前提下成立;重排查询器不会自动替换已加载对象。

查询顺序与模块缓存共同选来源保存独立卡片。

原书依据 · 1 处

远端模块加载也是代码执行

从URL取得源码并compile/exec会在本进程执行远端提供者的程序。普通HTTP目录列表和模块名匹配不验证发布者或内容完整性;远端可变也影响可复现性。此例用于研究导入协议,实际使用需明确可信来源、版本和认证等边界,不把能下载就能安全导入等同。未运行远端加载或开启服务器。

远端模块加载也是代码执行保存独立卡片。

原书依据 · 1 处

查询器与加载器分工需明确

旧例UrlMetaFinder按目录链接判断模块,UrlModuleLoader获取并编译源码,UrlPackageLoader另处理init与包路径。

结构图:

classDiagram
 MetaPathFinder <|-- UrlMetaFinder
 SourceLoader <|-- UrlModuleLoader
 UrlModuleLoader <|-- UrlPackageLoader
 class UrlMetaFinder {
  +find_module(fullname, path=None)
  +invalidate_caches()
 }
 class UrlModuleLoader {
  +load_module(fullname)
  +get_source(fullname)
  +get_code(fullname)
  +get_filename(fullname)
  +is_package(fullname)
 }
 UrlMetaFinder ..> UrlModuleLoader : 模块加载
 UrlMetaFinder ..> UrlPackageLoader : 包加载

图记录原3.3真实类型接口,继承与使用依赖分开,不能作为现代API模板。查询阶段就执行包初始化会混合职责并放大错误,迁移时应按规格查找与执行阶段处理。

查询器与加载器分工需明确保存独立卡片。

原书依据 · 1 处

包身份需要子模块搜索路径

普通模块元数据含名称、来源和包归属;包还需子模块搜索路径path,供后续查询其成员。原UrlPackageLoader应返回加载模块,源码漏return会使查询方拿None;包路径必须按实际父包位置计算,不能始终拼顶层URL。命名空间包没有init,其各部分路径可聚合,但不能把任意init加载异常都解释为“本来就是命名空间”。

包身份需要子模块搜索路径保存独立卡片。

原书依据 · 1 处

路径钩子为单个路径建立查询器

sys.path_hooks依序尝试识别路径项,成功返回该项查询器并缓存到path_importer_cache;不支持的路径应抛ImportError让下一钩子处理,原handle_url的非URL分支返回None不符合这一约定。

结构图:

classDiagram
 PathEntryFinder <|-- UrlPathFinder
 class UrlPathFinder {
  +__init__(baseurl)
  +find_loader(fullname)
  +invalidate_caches()
 }
 UrlPathFinder --> UrlModuleLoader : _loader

图为旧接口类型关系。路径钩子函数是工厂而非类型,返回查询器;包的路径项也可经同机制处理,不能只考虑顶层sys.path。

路径钩子为单个路径建立查询器保存独立卡片。

原书依据 · 1 处

导入缓存应区分层次与失效

sys.modules缓存模块对象,path_importer_cache缓存路径查询器,原例还缓存URL查询器、目录链接和源码文本,各层解决不同重复工作。invalidate_caches清目录链接不等于清源码或重载模块;新增文件可重新发现,也不代表旧对象更新。原链接缓存把basename与按baseurl存的键混查,会反复请求,必须按相同键检索。

导入缓存应区分层次与失效保存独立卡片。

原书依据 · 1 处

递归导入须有加载中状态

查询器自身调用urllib可能触发更多导入,若初始化未结束又重复进入同一查询,会循环创建或无限递归。原例先把链接从None设为空列表,暂时表示正在取链接,再填最终结果,配合URL查询器缓存避免重建。这是特定防重入策略,不是完整线程同步;临时失败不应永久伪装成“确实没有模块”。

递归导入须有加载中状态保存独立卡片。

原书依据 · 1 处

模块创建失败须回滚部分登记

执行模块前先登记对象有助循环依赖找到同一身份,但执行失败时须清理本次插入的部分模块,避免下次命中半初始化状态。setdefault也不会让后面的exec自动只执行一次,原显式load每次仍会重跑;它还会急切构造默认对象。应按标准导入锁、规格和执行协议管理,不能把字典操作当完整导入事务。

模块创建失败须回滚部分登记保存独立卡片。

原书依据 · 1 处

10.12 在模块加载时为其打补丁

导入后钩子把补丁时点延后到目标模块可用时,再调用预注册处理函数。它要区分加载中与加载完成,处理自身的递归导入及失败清理,也需约定重载是否重新打补丁。

导入后补丁须定义执行时点

when_imported为模块名登记处理函数;原例若sys.modules已有对象就立即调用,否则等待导入后处理。sys.modules也可能有尚未完成的模块,不能仅凭存在就认定可安全打补丁。函数替换后,早先外部绑定的旧引用也不会自动更新;钩子应明确幂等、触发次数和失败状态,不把“导入后”当整系统一致切换。

导入后补丁须定义执行时点保存独立卡片。

原书依据 · 1 处

导入中回调须保证防重入清理

旧PostImportFinder先标记正在处理的模块,加载器再调用标准导入,第二次遇同名便放行给其他查询器,从而避免自身无限递归。

结构图:

classDiagram
 class PostImportFinder {
  +__init__()
  +find_module(fullname, path=None)
 }
 class PostImportLoader {
  +__init__(finder)
  +load_module(fullname)
 }
 PostImportFinder ..> PostImportLoader : 返回旧式加载器
 PostImportLoader --> PostImportFinder : _finder持有

图记录原旧接口;实际迁移需按现代规格协议。原skip只在成功末尾移除,导入或回调失败会遗留标记,应保证退出清理,并定义已加载模块在回调失败时如何处置。

导入中回调须保证防重入清理保存独立卡片。

原书依据 · 1 处

10.13 安装只为自己所用的包

用户级安装把包放在当前用户的路径中,避免修改系统级位置,但不自动建立项目隔离。能否使用与能否优先导入取决于当前解释器和环境配置。

用户级安装不等于项目隔离

用户级安装把分发包放进用户site目录,不需把系统site当写入目标;它仍可能影响该用户多个项目,并可能遮蔽其他同名包。具体目录、搜索优先级和是否启用用户site依解释器与环境,不能硬编码历史3.3路径或保证任何环境都接受–user。需要项目依赖隔离时应选独立环境,并核对安装命令对应的解释器。

用户级安装不等于项目隔离保存独立卡片。

原书依据 · 1 处

10.14 创建新的Python环境

虚拟环境为项目提供独立安装位置与解释器入口,仍依赖创建它的基础Python。使用哪一个解释器决定包安装到哪里,激活只是便利入口,不是隔离成立的唯一条件。

虚拟环境隔离依赖而非操作系统

venv通常提供独立site-packages和解释器入口,便于项目分别管理依赖;它仍依赖基础Python与标准库,不是OS容器或安全沙箱。当前可用python -m venv,旧pyvenv命令已移除,见官方说明(核验2026-10-27)。默认不引入系统site包,system-site-packages选项会改变这一边界;创建方式、复制/链接及pip提供也随平台版本而变。

虚拟环境隔离依赖而非操作系统保存独立卡片。

原书依据 · 1 处

10.15 发布自定义的包

可分发的库需要清晰的包结构、版本和构建元数据,还要确保子包及资源被包含。生成归档只完成构建的一部分,目标环境安装与导入才检验分发是否足够。

包分发须包含子包与资源

发布前需声明名称、版本、包发现与资源规则,避免只收顶层包而遗漏子包、文档或运行数据。原setup.py/distutils方案有历史背景:distutils已自标准库移除,当前打包指南以pyproject.toml和构建后端等组织,见官方教程(核验2026-10-27)。应在隔离目标环境验证构建物安装、导入及资源访问;不把生成压缩包视作可用证明。

包分发须包含子包与资源保存独立卡片。

原书依据 · 1 处

第11章 网络和Web编程

网络接口必须把协议单位与传输单位分开:TCP字节流不保留应用消息边界,UDP数据报也不保证送达。HTTP、XMLRPC和自定义RPC在此之上定义交互,认证和TLS保护不同层面。事件循环与进程间句柄传递进一步要求清楚处理部分I/O、关闭与所有权。

11.1 以客户端的形式同HTTP服务交互

HTTP客户端先定义请求方法、地址、查询或主体和头,再按响应类型解释结果。方便的库接口减少样板,但状态、编码、认证、超时和资源生命周期仍需显式考虑。

HTTP请求区分查询主体与响应

GET参数可经urlencode放在查询串,POST表单可编码为请求体字节,头字段通过Request等接口指定;JSON主体又是另一种媒体类型。响应字节与解码文本不同,解析应依协议和内容类型。缺少状态码、超时、大小与错误处理的短例不是完整客户端;请求方法和网络结果也不能仅靠传入字典推断。

HTTP请求区分查询主体与响应保存独立卡片。

原书依据 · 1 处

响应格式解析不证明HTTP成功

Requests的text是解码文字,content是响应内容字节,json()才调用JSON解析;原resp.json属性写法属旧接口。解析成功不代表状态成功,HEAD也不保证每个被索引的响应头都存在,已查官方说明(2026-10-27)。内容还可能经过传输解码,不把content等同原始网络帧;应分别验证状态、格式与所需字段。

响应格式解析不证明HTTP成功保存独立卡片。

原书依据 · 1 处

会话认证与上传需独立管理

客户端可携带认证、Cookies并上传二进制文件,但这些是不同协议步骤:复用Cookies不证明已登录成功,基本认证也不等于传输加密。上传打开文件需要明确关闭责任,超时和异常同样处理。可用受控测试服务检查实际请求,而非用真实敏感账户尝试;原PyPI登录端点及直接OAuth支持说法不当当前通用接口。

会话认证与上传需独立管理保存独立卡片。

原书依据 · 1 处

HTTP库须匹配所需协议

urllib可通过Request、认证处理器和opener等支持比简单GET/POST更多的行为,http.client提供更底层控制;Requests把常见请求、响应与会话操作组织成较方便接口。应按依赖约束、测试和需要的协议功能选择,不能说标准库一旦超过GET/POST就无能为力,也不能认定第三方库自动完成所有认证。

HTTP库须匹配所需协议保存独立卡片。

原书依据 · 1 处

11.2 创建一个TCP服务器

TCP服务器把接受连接与连接内处理分开,socketserver提供处理器入口,流式处理器另提供文件接口。并发模型决定同时处理多少连接,传输字节流本身还需要应用定义消息边界。

服务模型匹配负载

普通TCPServer顺序处理请求;线程或进程变体可并发,但每请求创建工作者会增加资源压力,需要容量和超时策略。固定工作者可限制同时处理量,却不自动限制所有连接排队或缓冲占用。原例16个后台serve_forever再加主线程,共有17个服务循环入口,不能当严格16线程配额;示例并发方式仍需按当前实现验证。

服务模型匹配负载保存独立卡片。

原书依据 · 1 处

请求处理器连接服务器与会话

TCPServer管理接受连接,EchoHandler.handle处理该会话;BaseRequestHandler通过request取得socket,StreamRequestHandler则提供rfile/wfile字节流接口。

结构图:

classDiagram
 StreamRequestHandler <|-- EchoHandler
 class EchoHandler {
  +handle()
 }
 TCPServer ..> EchoHandler : 每请求创建处理器
 EchoHandler ..> socket : 会话字节流

图为流式替代版本,继承与创建依赖不同。文件式按行处理依赖对端提供终止符,仍需限制长度、超时与清理。

请求处理器连接服务器与会话保存独立卡片。

原书依据 · 1 处

TCP收发不能假设一次完整

TCP提供字节流,recv返回当前可得片段,不保证恰是一条完整业务消息。send可能只发部分,需处理返回长度或用sendall;sendall完成也不等于对方业务已处理。协议需另约定长度或分隔,错误与关闭路径也须管理;原首个echo直接send不构成完整发送保证。

TCP收发不能假设一次完整保存独立卡片。

原书依据 · 1 处

监听配置应在激活前完成

TCPServer通常构造时绑定并监听;需预先设socket选项时可延迟绑定激活,再显式server_bind/server_activate。allow_reuse_address是常见配置入口,但地址复用不等于无条件抢占正在使用端口。处理器超时、缓冲与Nagle开关也各有作用;原timeout=5是示例配置,不是所有默认值,已查官方说明(2026-10-27)。

监听配置应在激活前完成保存独立卡片。

原书依据 · 1 处

11.3 创建一个UDP服务器

UDP一次接收一个数据报及来源地址,无须先建立TCP式连接。服务器回发并不自动保证可靠交付,空数据报也可能是有效请求,不能按TCP读空代表关闭的规则处理。

数据报接收须保留来源与边界

UDPServer处理器request包含收到的数据报和服务器socket,client_address提供对端;也可直接recvfrom取得数据和地址,再sendto回应。空数据报是合法消息,原时间服务即用空请求,不能把它当TCP结束。缓冲不足可能截断报文,消息大小、来源验证与处理错误需按协议管理;打印“Got connection”不代表UDP真的建立连接。

数据报接收须保留来源与边界保存独立卡片。

原书依据 · 1 处

UDP可靠性由上层按目标设计

UDP本身不保证报文到达、顺序或不重复;需要时由上层使用编号、超时、重传与去重等机制。是否重传取决于延迟与业务目标,实时媒体可以选择丢弃过时数据,但不能说所有游戏和媒体一律不重传。线程/进程服务器改变处理并发,不为传输补上这些保证,也不能仅因无连接就推导永远更简单。

UDP可靠性由上层按目标设计保存独立卡片。

原书依据 · 1 处

11.4 从CIDR地址中生成IP地址的范围

CIDR前缀定义网络范围,地址、网络和带前缀接口是不同对象。解析和成员判断可用ipaddress,遍历全范围却需考虑规模,接口适配仍可能要转换成字符串。

网络前缀与主机地址须分清

IPv4网络/27保留27位前缀,剩5位给出32个地址;原123.45.67.64/27范围到.95。ip_address表示单地址,ip_network表示网络,ip_interface同时保存主机IP与所属网络。带主机位的.89/27不自动等于严格合法网络输入,需显式选择归一化或接口语义,已查官方API(2026-10-27)。

网络前缀与主机地址须分清保存独立卡片。

原书依据 · 1 处

地址范围遍历不等于可用主机表

网络对象可按范围迭代、索引和检测成员,num_addresses给范围大小;包含网络/广播等地址的完整范围不等于通常的主机列表。IPv6前缀短时范围极大,不应无需求逐个展开。ipaddress对象也未必可直接传给socket等旧字符串接口,需要按接口显式str转换;成员属于某网络不证明它实际可达。

地址范围遍历不等于可用主机表保存独立卡片。

原书依据 · 1 处

11.5 创建基于REST风格的简单接口

WSGI规定服务器如何调用应用及应用怎样返回状态、头和字节结果,路由则在应用层选择处理函数。用HTTP路径和方法提供资源接口有利于跨客户端交互,但遵循WSGI不自动满足完整REST设计或生产安全要求。

REST围绕资源

HTTP资源接口用路径标识所访问对象,再用请求方法表达操作;响应可采用JSON、XML等表示。原PathDispatcher仅按方法和精确路径选函数,展示一种轻量HTTP接口,并未实现完整REST架构约束。WSGI是Python服务器与应用的调用协议,不是REST本身;资源设计、方法语义、认证和错误协议仍由应用明确。

REST围绕资源保存独立卡片。

原书依据 · 1 处

WSGI应用返回字节可迭代结果

WSGI应用接收environ与start_response,前者提供方法、路径和输入流,后者接收状态字符串与响应头对序列;应用返回可迭代bytes块,文本需先正确编码。函数或可调用实例均可作为入口,生成器把正文延后产生。它统一应用和服务器接口,却不自动提供认证、Cookies或重定向策略;示例服务器也不代表生产容量保证。

WSGI应用返回字节可迭代结果保存独立卡片。

原书依据 · 1 处

路由与参数解析须有边界

PathDispatcher保存(method,path)到处理函数的映射,未匹配交404;调用时解析参数再转交handler。

结构图:

classDiagram
 class PathDispatcher {
  +__init__()
  +__call__(environ, start_response)
  +register(method, path, function)
 }
 PathDispatcher --> dict : pathmap
 PathDispatcher ..> callable : WSGI处理函数

箭头分别为持有与调用依赖。参数解析需限制大小和支持的媒体类型,GET查询与POST主体不应混作任意万能字典;原cgi已在3.13移除,迁移须用合适接口,见官方迁移说明(核验2026-10-27)。

路由与参数解析须有边界保存独立卡片。

原书依据 · 1 处

响应模板仍需上下文转义

把HTML或XML模板与控制逻辑分开可改善维护,但str.format不会自动按输出上下文转义。原name来自请求直接放进HTML,可能被解释为标记;应使用适合文本、属性或其他位置的转义机制,并验证响应头编码和错误路径。三引号模板只改变代码组织,不构成注入防护;解析参数成功也不证明值可直接输出。

响应模板仍需上下文转义保存独立卡片。

原书依据 · 1 处

11.6 利用XML-RPC实现简单的远端过程调用

XML-RPC让客户端按名字调用注册的远端函数,传参和结果使用XML表达。接口看似本地方法,但类型映射、网络失败、认证以及调用重试语义仍属于分布式问题。

远端调用须显式注册接口

SimpleXMLRPCServer通过register_function暴露操作,ServerProxy按远端名字调用;示例只注册get/set/delete/exists/keys,未注册的方法不自动成为API。

结构图:

classDiagram
 class KeyValueServer {
  +get(name)
  +set(name, value)
  +delete(name)
  +exists(name)
  +keys()
  +serve_forever()
 }
 KeyValueServer --> dict : _data内存存储
 KeyValueServer --> SimpleXMLRPCServer : _serv
 ServerProxy ..> SimpleXMLRPCServer : XML远程请求

持有与远程请求依赖不同。它没有自动提供持久化、权限或并发隔离,不能把内存键值例当数据库。

远端调用须显式注册接口保存独立卡片。

原书依据 · 1 处

RPC数据映射不保留任意对象

XML-RPC支持有限类型映射,示例传Point后取回字典,而非重新获得Point行为;二进制默认可表现为Binary包装,None需双方允许相应扩展。接口应定义类型和错误,不假定任意Python对象都透明传递。XML互操作有优势,但编码成本与并发能力需按需求验证;“内部网络”也不自动提供认证或可信输入保障。

RPC数据映射不保留任意对象保存独立卡片。

原书依据 · 1 处

11.7 在不同的解释器间进行通信

multiprocessing连接在传输上封装对象消息边界,使用pickle传递Python数据。消息接口仍可能因连接断开或序列化失败而报错,认证也不是加密;它适合清楚限定信任关系的节点通信。

对象消息封装不保证业务交付

multiprocessing.connection的send/recv封装每个可pickle对象的消息边界,避免调用方自行按TCP片段重组;成功recv得到一个解码对象,但断线、EOF或解码仍可能失败。发送成功不证明对端业务已处理。长期连接可降低反复建连成本,连接与监听器需要明确关闭路径,原echo捕EOF并未清理全部资源。

对象消息封装不保证业务交付保存独立卡片。

原书依据 · 1 处

连接认证不等于传输加密

Client与Listener用authkey认证对端,不表示消息内容已加密;recv自动反序列化pickle,连接必须来自可信对端,不能把任意公众连接交给它。网络地址、UNIX域socket路径和Windows管道名是不同传输端点表示。超时能力也要分接口看,Connection.poll支持等待可读超时,原“一切超时只能换库”过强,见官方API(核验2026-10-27)。

连接认证不等于传输加密保存独立卡片。

原书依据 · 1 处

11.8 实现远端过程调用

简单RPC把方法名与参数封成消息,服务端查注册表执行,再编码成功或失败结果返回。把网络细节藏在代理里能简化调用外形,却不消除结果不确定、类型损失和错误协议。

RPC不消除网络

RPC代理把名字、参数和结果经消息连接传输,使调用外形接近本地;但断线、超时、重复、执行后响应丢失等仍需协议处理。客户端失败不代表服务端未执行,不能盲目重试有副作用操作。原一问一答连接没有请求ID与并发复用约定,多个调用共享连接可能串结果;简单代理不提供可靠业务交付保证。

RPC不消除网络保存独立卡片。

原书依据 · 1 处

远程代理把方法调用封成消息

RPCProxy的getattr返回do_rpc闭包,将name/args/kwargs发送;RPCHandler查注册表调用并返回结果。

结构图:

classDiagram
 class RPCProxy {
  +__init__(connection)
  +__getattr__(name)
 }
 class RPCHandler {
  +__init__()
  +register_function(func)
  +handle_connection(connection)
 }
 RPCProxy --> connection : 请求响应通道
 RPCHandler --> dict : 函数注册表
 RPCHandler ..> connection : 读取请求写出结果

持有与使用依赖不同。闭包是调用适配器而非新增方法类型;注册表限制可调用名字,却无法防止解码阶段先执行恶意pickle。

远程代理把方法调用封成消息保存独立卡片。

原书依据 · 1 处

RPC响应须显式区分成功与失败

把Exception对象当失败标志,会让“成功返回异常对象”与真正失败混淆;JSON版把异常转成普通字符串,又会与成功字符串混淆。应设计明确的状态与结果/错误字段,并约定错误码、细节和可重试性。原except只包执行等部分路径,解码、序列化、发送与连接清理也可能失败,不应宣称服务器因此绝不崩溃。

RPC响应须显式区分成功与失败保存独立卡片。

原书依据 · 1 处

更换编码不自动更换传输信任

JSON可减少任意对象重建能力,但若底层Connection.recv仍自动用pickle恢复对象,外层json.loads并未消除那一层风险。内网或共享密钥也不自动证明对端代码可信。迁移时需逐层检查帧传输、编码、类型约束及认证,而非只把最外层dumps/loads替换;与ZeroMQ互换也需适配其真实字节与收发接口。

更换编码不自动更换传输信任保存独立卡片。

原书依据 · 1 处

11.9 以简单的方式验证客户端身份

挑战应答让对方证明知道共享密钥,不必把密钥本身送上连接。摘要比较、随机挑战、完整收发和超时都影响协议,握手认证也不能替代后续流量的加密与完整性保护。

挑战应答证明共享密钥知识

服务器生成新随机挑战,双方用共享密钥计算HMAC,客户端回传摘要,服务器用compare_digest比较,避免普通相等比较的内容相关提前退出。该过程证明持有密钥,不自动标识唯一用户或认证反方向,也不加密后续消息。旧hmac.new省略digestmod不再是当前通用调用,现代需明确摘要算法,见官方API(核验2026-10-27)。

挑战应答证明共享密钥知识保存独立卡片。

原书依据 · 1 处

认证握手也需完整收发协议

TCP一次recv不保证收到完整挑战或摘要,send也可能短写;应在协议规定长度内收齐,并处理EOF、超时及失败关闭。compare_digest仅比较提供值,不能修复缺失或串帧。握手结束后的明文也未因此得到逐消息认证,不能把这个简例当TLS替代;原echo成功退出还缺统一资源清理。

认证握手也需完整收发协议保存独立卡片。

原书依据 · 1 处

11.10 为网络服务增加SSL支持

TLS在连接上提供加密并可验证端点身份。服务器证书、客户端信任链和主机名检查分别回答不同问题;双向认证还需客户端证书和服务端验证策略,单纯包装socket并不自动具备全部保障。

加密连接还须验证目标身份

TLS加密不单独证明连到正确服务,客户端还应验证证书信任、有效性与目标主机名;只设置CERT_REQUIRED不等于旧例已检查名称。现代Python通过SSLContext和适当默认上下文组织验证,原顶层ssl.wrap_socket已在3.12移除,见SSL文档与迁移说明(核验2026-10-27)。不能沿用TLSv1固定旧示例作为当前配置。

加密连接还须验证目标身份保存独立卡片。

原书依据 · 1 处

双向认证需两侧信任配置

常见TLS由服务器提供证书、客户端验证服务器;要验证客户端,服务端还须要求并验证客户端证书,客户端则配置自己的证书与私钥。证书可对外传递,私钥应保留受控;信任某证书不是把任意网络拿到的副本直接信任。自签名可用于明确分发信任的测试,但不能自动替代真实身份核验;原首例注释称要求客户证书而代码未设置,必须区分。

双向认证需两侧信任配置保存独立卡片。

原书依据 · 1 处

TLS混入在接受连接处包装

旧SSLMixin重写get_request,先接收底层连接,再包装TLS并把连接和地址交给服务处理器。

结构图:

classDiagram
 class SSLMixin {
  +__init__(*args, keyfile=None, certfile=None, ca_certs=None, cert_reqs, **kwargs)
  +get_request()
 }
 SSLMixin <|-- SSLSimpleXMLRPCServer
 SimpleXMLRPCServer <|-- SSLSimpleXMLRPCServer
 SSLMixin ..> ssl : 旧式包装连接

图记录本书替代示例的职责,继承与调用依赖不同;原默认ssl.NONE不存在,应为对应合法常量,但整套接口仍需现代化。握手可能阻塞或失败,要考虑超时、关闭和服务并发,不能只增加包装就当部署完成。

TLS混入在接受连接处包装保存独立卡片。

原书依据 · 1 处

高层TLS客户端应传验证上下文

高层XML-RPC客户端可通过支持的传输/上下文配置管理信任与客户端证书,而不是只看URL含https。原VerifyCertSafeTransport用旧TLSv1、未定义cert变量和特定make_connection技巧,不能直接沿用;需依当前接口设置验证、名称检查与证书链。证书里的地址标识也需符合当前验证规则,原只填Common Name不足以当通用成功保证。

高层TLS客户端应传验证上下文保存独立卡片。

原书依据 · 1 处

11.11 在进程间传递socket文件描述符

进程间传递描述符是把同一底层打开资源的访问权交给另一个进程,不是仅发送一个整数即可。接收进程取得自己的有效句柄,发送端与接收端各自管理关闭,适合接收连接与处理会话分工。

传递描述符须转移有效访问权

文件描述符整数只在其进程中解释,不能把数字当普通网络数据发给另一机器就获得连接。send_handle/recv_handle借助受支持的本地进程间机制传递有效资源访问,接收方再构造socket处理;发送方在成功移交后关闭自己的引用。各方还需规定失败与退出清理,关闭一个引用不等于销毁其他进程仍持有的资源。

传递描述符须转移有效访问权保存独立卡片。

原书依据 · 1 处

连接接收与处理可由进程分工

接收进程accept新客户端后把句柄交给工作者,自己继续接受连接,可将会话处理分散到多个解释器。原例单个工作者仍顺序服务被移交会话,不自动形成均衡或并发调度;多工作者需另定义容量、分配与故障恢复。Pipe各端的未用引用要及时关闭,否则退出和EOF判断也会受影响。

连接接收与处理可由进程分工保存独立卡片。

原书依据 · 1 处

辅助数据传递需校验完整协议

UNIX域socket可用sendmsg/recvmsg和SCM_RIGHTS辅助数据传递描述符。接收方要验证控制消息类型、长度与截断情况,并关闭多余或失败路径上的句柄;不能只假定ancdata[0]存在。原用assert做协议校验会在优化模式被移除,ACK也可能短读;Windows使用不同句柄机制,不能照搬UNIX编码。

辅助数据传递需校验完整协议保存独立卡片。

原书依据 · 1 处

11.12 理解事件驱动型I/O

事件循环先收集关心的读写方向,再等待就绪并调用相应处理器。单循环可交错服务多连接,但回调内的阻塞或长计算会延迟所有其他连接;线程池结果需通过安全的通知协议回到循环。

输入输出就绪不等于完成

select等待哪些描述符当前可读或可写,再由回调尝试处理;就绪不保证整条消息、任意长度写入或应用处理已经完成。事件驱动可交错服务多连接,但单个回调长时间计算或阻塞会停住整个循环。原socket未显式非阻塞,仍可能在竞争或大写入等情形阻塞;需要非阻塞及部分完成协议,不能把select包装当全局无阻塞保证。

输入输出就绪不等于完成保存独立卡片。

原书依据 · 1 处

事件处理器声明兴趣并响应

EventHandler用fileno暴露可等待资源,wants_to_receive/send声明当前兴趣,handle_receive/send完成相应处理。

结构图:

classDiagram
 class EventHandler {
  +fileno()
  +wants_to_receive()
  +handle_receive()
  +wants_to_send()
  +handle_send()
 }
 EventHandler <|-- UDPServer
 UDPServer <|-- UDPTimeServer
 UDPServer <|-- UDPEchoServer
 EventHandler <|-- TCPServer
 EventHandler <|-- TCPClient
 TCPClient <|-- TCPEchoClient

图为原协议继承;同名TCPServer/UDPServer是本节自定义类型,不是socketserver类。兴趣随状态变化而变,循环调用协议不自动处理异常、关闭或所有平台的select容量限制。

事件处理器声明兴趣并响应保存独立卡片。

原书依据 · 1 处

事件连接须管理注册与待发数据

新TCP连接建立后需把处理器注册进循环,关闭时移除;写缓冲非空才订阅写就绪,按send实际字节数推进待发部分。还要限制待发队列并对慢客户端施加背压,否则内存可持续增长。原接收EOF即close可能丢弃尚未回显的待发内容,同一就绪批次还可能引用已关闭处理器,必须协调退出时机。

事件连接须管理注册与待发数据保存独立卡片。

原书依据 · 1 处

工作线程结果须显式唤醒循环

线程池完成任务后,将结果排队并向通知socket写信号,循环监听另一端,收到后在循环线程执行完成回调。

结构图:

classDiagram
 EventHandler <|-- ThreadPoolHandler
 class ThreadPoolHandler {
  +run(func, args=(), kwargs, callback)
  +_complete(callback, r)
  +handle_receive()
  +fileno()
 }
 ThreadPoolHandler --> ThreadPoolExecutor : pool
 ThreadPoolHandler --> socket : 成对通知端

持有关系与继承不同。任务离开循环不意味着纯Python计算在所有解释器都获得并行加速,也不等于循环无负担;提交队列、完成队列、通知通道与线程池都要有容量和生命周期。

工作线程结果须显式唤醒循环保存独立卡片。

原书依据 · 1 处

完成通知必须包含失败路径

原_complete先r.result再通知,任务异常会在取结果时抛出,导致没有完成消息,等待方可能永远不知道失败。pending列表又由线程和循环共同修改,遍历后换新列表可能与并发追加竞态,通知字节也可能阻塞或未写出。应以明确同步的队列、成功/失败消息与可恢复唤醒协议处理,回调异常和关闭时也要清理;这只是对原代码推导,未实测。

完成通知必须包含失败路径保存独立卡片。

原书依据 · 1 处

11.13 发送和接收大型数组

缓冲区视图让网络接口直接使用已有连续数组的字节范围,按实际完成量切片推进,可减少Python中间副本。接收方仍需先知道长度与布局,断线或零进展必须成为明确终止条件。

数组传输用视图推进有效范围

将连续缓冲区cast为B视图可按字节传给send/recv_into,随后根据实际完成数切片推进,切片共享原内存,避免反复复制剩余数据。接收缓冲须可写,双方还需约定长度、dtype、形状和字节序;原始内存布局不自动成为跨平台格式。“少复制”限这层Python缓冲,不保证内核网络全链路零拷贝。

数组传输用视图推进有效范围保存独立卡片。

原书依据 · 1 处

传输循环必须检测零进展

当send或recv_into返回0而视图仍非空,原循环切片不前进,会无限重试;接收0通常表示连接关闭,应按未收足报错。还需处理异常、超时与非阻塞暂不可用,不能只循环直到长度为零。若先发送长度头,应验证上限和布局再分配,防止不可信大小引发过量内存;发送完成也需另定义业务确认。

传输循环必须检测零进展保存独立卡片。

原书依据 · 1 处

第12章 并发

并发先决定状态由谁拥有,再决定线程、进程或协程如何调度。Queue把工作与结果交接,锁保护共享不变量,Actor和发布订阅组织消息,生成器调度把等待显式化。完成通知、取消、超时、异常和退出清理都属于协议,不能仅凭用了某个并发工具推断整体安全。

12.1 启动和停止线程

线程对象创建、启动、运行和等待结束各有时点。退出应由任务合作检查信号,并让阻塞操作有可返回的路径;守护线程只改变解释器退出条件,并不保证后台清理完成。

GIL限制CPU并行关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

线程停止需协作

Thread构造不等于开始运行,start后目标独立执行,join等待实际结束。停止通常用任务内检查退出信号,阻塞I/O还需超时或其他解除等待机制,让检查点可达。设置标志不表示线程已经退出,需在适当位置join确认;也不能把普通标志读写当所有共享状态的同步保证,清理应放在退出路径。

线程停止需协作保存独立卡片。

原书依据 · 1 处

守护线程不能承担可靠收尾

daemon只表示当不再有存活非守护线程时,解释器可退出;守护线程仍可在适当阶段join,原“不能连接”错误。退出时它们可能被突然停止,不能依赖它们写完文件或释放资源,见官方说明(核验2026-10-27)。需要可靠收尾应合作停止并等待,而非只把线程设daemon。

守护线程不能承担可靠收尾保存独立卡片。

原书依据 · 1 处

任务逻辑宜与执行机制分离

把可调用任务与线程构造分开,有助在普通调用、线程或适合的进程场景复用;继承Thread也可用,但会把任务绑定到该执行接口。更换进程不是简单复制线程共享状态语义,传参、序列化和停止通信仍需调整。原CountdownThread把n设0、CountdownTask调用参数前后不一致,都不能直接当可运行复用例。

任务逻辑宜与执行机制分离保存独立卡片。

原书依据 · 1 处

12.2 判断线程是否已经启动

启动请求不保证任务已经到达就绪点,Event可在真实里程碑设置,等待方再继续。周期变化或只放行一个工作者则需要不同的状态与等待协议,通知本身不是排队历史。

就绪事件应在真实里程碑设置

Thread.start只请求启动,其他线程若依赖某项准备已完成,应让工作线程完成该步骤后set Event,再由调用方wait。Event是粘性标志,已设置时后来的wait也可继续,适合一次就绪;它只证明设置点已到达,不证明任务以后不会失败。等待也需定义失败与超时,避免线程启动前出错让调用方无限等待。

就绪事件应在真实里程碑设置保存独立卡片。

原书依据 · 1 处

周期通知需要受锁保护的条件

Condition配合受同一锁保护的状态:等待方记住观察值并在while中等待其变化,通知方先改状态再notify_all。原PeriodicTimer每次异或翻转一位,慢线程若错过偶数次tick会再次见相同值,因此不保证每个周期都交付;需要计次数或补偿时应使用代数计数/排队协议。sleep循环也不等于无漂移的精确定时。

周期通知需要受锁保护的条件保存独立卡片。

原书依据 · 1 处

广播标志与计数许可不同

Event.set可释放所有等待者且保持设置状态;Semaphore计数许可,每次release增加许可,使相应数量的acquire成功,常用于逐个放行工作者。先后顺序不保证按线程编号,原Working0/1只是示例。Condition通知还需重新检查实际谓词,不能把一次唤醒当条件一定满足;重复set/clear若无协议也可能丢失一轮通知。

广播标志与计数许可不同保存独立卡片。

原书依据 · 1 处

12.3 线程间通信

队列负责线程安全的入队出队,却只传对象引用;数据交接后谁能修改、何时完成和怎样关闭仍需协议。容量、超时与完成确认能帮助控制流,但不能互相替代。

Queue传递所有权

线程Queue传递的是对象引用,锁保护队列操作,不保护对象后续所有修改。生产者交出可变对象后应停止修改,或传真正不可变数据/受控副本,明确单一拥有者。元组含可变成员也非深不可变,deepcopy同样有对象与资源边界;“所有权转移”是程序协议,不是Queue强制执行。

Queue传递所有权保存独立卡片。

原书依据 · 1 处

终止哨兵需要协调所有消费者

生产者放专用哨兵表示不会再提供相应任务,消费者按身份判断并退出;原重新放回可让其他消费者依次见到。但必须先确保生产者全已完成且不会在哨兵后加任务,并协调有界队列与任务计数。哨兵不自动停止生产者、等待线程或完成未处理任务,也不适合把进程间序列化后的普通object身份原样照搬。

终止哨兵需要协调所有消费者保存独立卡片。

原书依据 · 1 处

队列完成计数不等于线程结束

Queue每次put增加未完成任务计数,消费者处理后task_done,join等待计数归零;它不等待生产者不再放入,也不表示消费者线程退出。异常路径须定义任务是完成、失败还是重试,并恰当配平计数,不能漏调或重复调。单任务Event可发完成信号,但若消费者失败不发信号仍会挂起,成功/失败需有明确结果协议。

队列完成计数不等于线程结束保存独立卡片。

原书依据 · 1 处

有界队列要有背压与满载策略

给Queue设正容量可让过快生产者在满时等待,把积压反馈为背压;也可用超时/非阻塞put选择拒绝、记录或其他策略。容量不是修复循环等待的万能旋钮,阻塞时持有其他资源可能死锁。qsize/full/empty只是瞬时观察,不能当后续get/put不会阻塞的保证,应直接操作并处理Empty/Full。

有界队列要有背压与满载策略保存独立卡片。

原书依据 · 1 处

条件变量可保护自定义优先队列

线程安全优先队列在Condition锁内维护堆与递增序号,put后通知,get用while等待非空再弹出。

结构图:

classDiagram
 class PriorityQueue {
  +__init__()
  +put(item, priority)
  +get()
 }
 PriorityQueue --> Condition : _cv
 PriorityQueue --> list : _queue堆

持有边不是继承。负优先级让数值大者先出,唯一序号让同级按到达顺序比较而不比较载荷;与前章单线程队列相比,这里还需锁保护计数和等待谓词。

条件变量可保护自定义优先队列保存独立卡片。

原书依据 · 1 处

12.4 对临界区加锁

互斥锁保护共同的状态协议,所有相关访问路径必须一致使用它。with帮助配对释放,但锁范围、重入和并发许可是不同选择,既影响正确性也影响竞争与吞吐。

临界区须覆盖完整状态操作

对共享计数的读改写应作为一个受同一锁保护的操作,相关读写路径也应遵守同一协议;只给部分代码加锁无法保护其他绕过路径。with管理成功获取后的释放,减少异常导致漏放锁,但不自动回滚状态或防止一切死锁。锁粒度需覆盖要维持的不变量,不能依赖传统GIL替代业务原子性。

临界区须覆盖完整状态操作保存独立卡片。

原书依据 · 1 处

可重入与锁共享范围分别选择

RLock允许同一线程重复获取,释放也需配平,适合加锁方法再调用使用同锁的方法。原类级RLock由所有计数器实例共享,可减少逐实例锁对象,却会让互不相关实例竞争;实例锁则隔离竞争。只有使用该锁的操作被串行化,不能说类的全部方法和所有外部字段访问自动受保护。

可重入与锁共享范围分别选择保存独立卡片。

原书依据 · 1 处

信号量限制的是持有许可区间

Semaphore(5)允许最多五个成功持有许可的代码区间同时执行,退出释放许可,可用于节流。原fetch_url只把urlopen放在区间内,返回响应后读取和连接寿命不再被许可覆盖,所以不是最多五个完整下载或五条活连接。应按真正要限制的资源定义许可范围,并在异常路径配平。

信号量限制的是持有许可区间保存独立卡片。

原书依据 · 1 处

12.5 避免死锁

统一锁序通过排除锁等待环防止这一类死锁,前提是所有相关获取路径遵守顺序。嵌套场景需知道本线程已持有的锁,而获取失败时也只能释放自己实际已获取的部分。

锁顺序防死锁

多锁统一按全序获取并逆序释放,可排除这些锁之间的循环等待;嵌套获取还应确保新锁严格高于当前已持有者。原按活对象id排序,线程局部列表检查嵌套顺序;所有相关路径必须遵守,重复同一非重入锁应拒绝。它不保证公平或无饥饿,也不解决join、I/O、条件通知等其他等待环,不能宣称系统永远无死锁。

锁顺序防死锁保存独立卡片。

原书依据 · 1 处

多锁获取失败须回退已得部分

原acquire在尝试前就把全部锁记为已获取,finally又无条件释放全部;中途异常时可能释放未获得的锁或掩盖原错误。应记录真正成功的前缀,仅逆序释放这些,并同步恢复线程本地记录。空参数需定义为空操作或拒绝,重复锁需检测;原locks[0]与del[-len(locks):]也没有处理这些边界。

多锁获取失败须回退已得部分保存独立卡片。

原书依据 · 1 处

无死锁不代表无饥饿

哲学家就餐中,每人都先拿相同方向筷子会形成循环等待;把筷子作为统一编号锁,按序取得两支可打破该等待环。但某线程仍可能长期抢不到资源,算法不提供公平性,也未限制忙循环吞吐。看门狗超时只能发现缺少进展的迹象并采取恢复,不能仅凭超时证明根因一定死锁。

无死锁不代表无饥饿保存独立卡片。

原书依据 · 1 处

12.6 保存线程专有状态

线程局部对象为同名属性提供每线程存储,让连接等资源不被不同线程误当同一实例共享。它按线程而非任务隔离,线程池复用或异步任务交错时要重新考虑生命周期。

线程局部状态按线程隔离

threading.local让同一local对象上的普通属性按当前线程分别保存,适合每线程连接。线程专用不等于安全访问控制,也不会深复制所存对象:若把同一个可变对象引用分别放进去,底层仍共享。线程池会复用线程,遗留属性可能流入后续任务;也不能把这种机制直接当异步协程任务局部存储。

线程局部状态按线程隔离保存独立卡片。

原书依据 · 1 处

每线程连接仍须处理进入失败

LazyConnection把sock存在线程局部,使共享管理器可为每个线程建立独立连接;同一线程嵌套仍按例拒绝。connect失败发生于enter内,exit不会自动调用,原保存的socket及属性可能残留,需失败清理。构造器忽略family/type实参也需修正;local只隔离这一处状态,不保证其他共享配置和所有会话处理都线程安全。

每线程连接仍须处理进入失败保存独立卡片。

原书依据 · 1 处

12.7 创建线程池

线程池复用有限工作者并通过Future交付结果,减少每请求创建线程的开销。限制工作者还不足以限制所有排队任务和已接受资源,容量、取消与关闭需与执行一同设计。

线程池限制工作者不限制积压

ThreadPoolExecutor设最大工作者数并复用线程,submit返回Future;同时运行任务受限,但提交队列及已accept的连接仍可能增长。应对排队、慢连接、超时、拒绝与关闭设规则,不能把128工作者直接等于最多128个活连接。手写Queue工作者还需循环取后续任务;原echo_client只get一次就退出,未构成持续可复用池。

线程池限制工作者不限制积压保存独立卡片。

原书依据 · 1 处

Future取结果也传播失败

Future.result等待对应任务完成并取得返回值,任务异常也会在取结果时传播,可配置等待边界;它不代表其他Future均完成。按提交顺序逐个等可能让已完成的后续结果等待慢任务。资源需在任务和池退出时清理,取消也不等于强杀已经运行的线程;不消费Future还可能让失败无人处理。

Future取结果也传播失败保存独立卡片。

原书依据 · 1 处

线程容量须测量实际资源成本

每线程栈会占虚拟地址空间,实际驻留物理内存可能更少,二者不能混为总实际消耗。原两千线程的9GB/70MB及调栈数字是旧平台测量,不保证当前环境;大量等待线程仍有调度与资源成本。stack_size受平台最小值和对齐限制,调小还可能影响深调用,不能用历史例直接推广安全容量。

线程容量须测量实际资源成本保存独立卡片。

原书依据 · 1 处

12.8 实现简单的并行编程

可独立划分的计算先分别处理,再汇总结果,适合进程池利用多个核心。进程之间不共享普通变量更新,任务与结果需跨边界传递,序列化及启动成本可能抵消小任务的收益。

独立分片再归并适合进程池

日志例按文件独立提取主机集合,再做集合并集;pool.map可让这些分片在不同进程处理。并集适合此例归并,但不代表所有任务都可独立或无顺序影响。分片规模要足以抵消启动、读取竞争和传输成本;原四核3.5倍为旧环境结果,不能当当前保证,返回大集合也可能增加通信和聚合占用。

独立分片再归并适合进程池保存独立卡片。

原书依据 · 1 处

进程池任务须可跨解释器恢复

ProcessPoolExecutor要求任务可调用对象及参数、结果符合可pickle与导入等边界,入口模块应可在工作者中正确加载。不是所有实例方法或可调用实例都一律禁止,也不是只要def就必然可用;lambda与局部闭包通常不满足标准pickle路径,见官方说明(核验2026-10-27)。不要假定工作者拥有主线程后续普通变量修改。

进程池任务须可跨解释器恢复保存独立卡片。

原书依据 · 1 处

进程启动方式属于环境契约

进程池可用map或submit/Future,with退出通常等待已提交工作完成;任务仍可能失败、取消或使工作者退出。启动方式和默认工作者数依版本、平台和配置,现代默认已不能概括为“UNIX总fork”,应明确mp_context等实际选择。混用线程与进程时尤其要评估fork继承状态,不能只凭启动顺序就证明无死锁。

进程启动方式属于环境契约保存独立卡片。

原书依据 · 1 处

12.9 如何规避GIL带来的限制

传统启用GIL的CPython限制同一解释器中多个线程同时执行Python代码,但程序性能和响应还取决于算法、阻塞与扩展行为。进程或释放GIL的原生计算可以改变并行路径,代价和正确性应分别核验。

GIL限制CPU并行

在启用GIL的CPython中,同一解释器通常一次只有一个线程执行Python字节码;等待I/O常释放它,因此线程仍可组织并发。现代有可选free-threaded构建,不能把此限制扩为全部Python实现与版本。GIL也不保证复合业务操作原子;CPU代码久占执行或C扩展不释放锁还会影响其他响应线程,所以“只影响纯CPU任务”同样过窄。

GIL限制CPU并行保存独立卡片。

原书依据 · 2 处

并行方案先评估计算与传输成本

性能瓶颈先定位,再比较算法改进、适合的原生库、独立进程或其他解释器;线程数增加不是唯一途径。进程池能让独立解释器利用多核,但任务过小、序列化过大或状态耦合会抵消收益。原pool.apply是同步等待,不自动重叠同一线程后续工作;它的(args)也不等于单元素元组,应明确参数封装。

并行方案先评估计算与传输成本保存独立卡片。

原书依据 · 1 处

释放GIL须隔离解释器操作

原生计算在允许释放GIL区间里执行时,不应随意调用需要线程状态的Python C API或操作Python对象;独立C数据本身仍可能有竞态,需另同步。ctypes是否释放取决于加载接口,CDLL类常规调用与PyDLL不同,不能说任意ctypes调用都自动释放,见官方文档(核验2026-10-27)。Cython等也需符合其明确nogil约束,改成C不自动并行。

释放GIL须隔离解释器操作保存独立卡片。

原书依据 · 1 处

12.10 定义一个Actor任务

Actor把状态放在任务自身,通过消息请求操作,简化共享锁关系。线程加邮箱可提供异步执行,但排队不代表完成,停止、失败与结果回复也需要显式协议。

Actor隔离状态

Actor以消息驱动自身行为,通常由自己处理内部状态,向其他Actor发送请求而不直接共享修改。线程加Queue可作简单实现,但邮箱只传对象引用,发送者继续修改载荷仍会破坏隔离。异步发送不等于完成确认;需要结果可设计回复或Future式对象,Actor模型并不禁止请求响应,只是不把普通send自动视为同步调用。

Actor隔离状态保存独立卡片。

原书依据 · 1 处

邮箱任务须定义启动停止协议

Actor持有邮箱,send入队,run取消息;close发送终止哨兵,join等任务退出事件。

结构图:

classDiagram
 class Actor {
  +send(msg)
  +recv()
  +close()
  +start()
  +join()
  +run()
  +_bootstrap()
 }
 Actor <|-- PrintActor
 Actor --> Queue : _mailbox
 Actor --> Event : _terminated

继承与持有不同。原join在start前无终止事件,重复start、close后继续send等均未定义;后台daemon不保证退出时所有消息已处理。哨兵终止不替代失败报告或任务取消。

邮箱任务须定义启动停止协议保存独立卡片。

原书依据 · 1 处

Actor结果也需要失败通道

Worker把函数请求与Result对象一起入邮箱,正常计算后set_result并设置Event。若函数抛错,原实现会结束工作者却不完成该Result,调用方result可能永久等待;后续排队任务也无结果。因此需成功、异常、超时及停止时的完成规则,不能只保证Actor终止事件被设就认为请求已处置。

Actor结果也需要失败通道保存独立卡片。

原书依据 · 1 处

生成器关闭不能吞掉终止信号

简化生成器Actor的send直接同步执行到下一yield,并没有线程邮箱的异步语义。close注入GeneratorExit后,应结束或重抛;原捕获后只打印又回循环yield,会触发“生成器忽略关闭”错误。预激、发送、异常和关闭都是协议的一部分,不能只因代码短就认为与线程Actor完全等价。

生成器关闭不能吞掉终止信号保存独立卡片。

原书依据 · 1 处

12.11 实现发布者/订阅者消息模式

发布订阅把发送者与收件名单分开:发送者面向命名交换对象,交换对象维护订阅集合并逐个转发。这个例子同步调用订阅者的 send;它是否只是入队、是否阻塞,取决于订阅者实现。订阅的生命周期、异常传播和共享消息所有权仍要明确定义。

交换对象解耦消息布线

发布者只知道交换对象,订阅者通过 attach 和 detach 改变接收集合。Exchange.send 遍历当前订阅者并调用各自 send,因此新增日志观察者无需修改发布者。命名交换对象由全局字典保存,名称相同的任务连接到同一中介。

结构图:

classDiagram
class Exchange {
  +attach(task)
  +detach(task)
  +send(msg)
}
class DisplayMessages {
  +send(msg)
}
Exchange o--> DisplayMessages : 订阅集合中的一个接收者

DisplayMessages 是原例的计数打印接收者;其他订阅者只须提供 send。该协议允许线程 Actor、生成器或网络适配器参与,但并不自动统一它们的执行、缓冲和失败语义。

交换对象解耦消息布线保存独立卡片。

原书依据 · 1 处

广播不保证隔离与送达

逐个调用 send 的广播会把同一个消息对象交给多个接收者。若其中一个同步修改可变消息,后续接收者会看到修改;需要不可变消息或明确的复制、所有权协议。集合没有承诺业务发送顺序,慢接收者会拖住发送者,异常也会中断尚未执行的转发。

这个交换对象没有持久化、确认、重试或线程互斥。并发 attach、detach 与遍历集合可能冲突;给每个接收者建立线程安全队列也不能自动保护交换对象自身。应分别设计订阅集合的同步、慢消费者策略和失败处置,再决定是否满足所需送达保证。

广播不保证隔离与送达保存独立卡片。

原书依据 · 1 处

订阅清理必须有所有权

用上下文管理器把订阅限制在一个代码范围内,可以在正常结束或异常退出时执行 detach,避免临时观察者永久留下。但“退出就删除”只有在当前范围确实拥有该注册时才成立。

示例集合把重复 attach 合并成一个成员,而 subscribe 的 finally 无条件删除:预先已有的订阅或嵌套订阅可能被内层提前移除。附加操作又在 try 之前,部分附加失败时不会清理已附加成员。可记录本次新增成员、使用独立订阅令牌或引用计数,并对部分成功提供回滚;具体策略由订阅生命周期决定。

订阅清理必须有所有权保存独立卡片。

原书依据 · 1 处

12.12 使用生成器作为线程的替代方案

生成器在 yield 处主动交还控制,调度器把尚未结束的生成器放回就绪队列,从而在一个线程内交替推进任务。消息调度再把任务及其消息配对;I/O 调度则把任务挂到文件描述符的等待表,就绪后恢复。三者共享暂停和恢复机制,但需要分别管理任务生存期、异常和资源。

生成器返回值须由驱动器接收关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

协作任务只在让出时切换

协作调度器从双端队列取出一个生成器,以 next 推进到下一次 yield,再把它放回队尾;遇到 StopIteration 才将其移除。队列实现轮转,生成器保存局部变量和执行位置,因而许多任务可以在一个系统线程里交替推进。

这种并发依靠任务主动让出。长时间计算或阻塞库调用会阻塞整个调度循环,既没有抢占,也没有多核并行。yield 是切换点,公平性和延迟仍取决于每次推进所做工作的上限。

协作任务只在让出时切换保存独立卡片。

原书依据 · 1 处

消息队列消除递归调用链

生成器 Actor 的调度队列存放“目标生成器、消息”对,调度器调用 actor.send(msg) 后再取下一项。一个任务发消息给自身,只是追加队列项,不会在当前调用栈中递归执行自己,因此计数器可以反复自投递而不积累递归深度。

新生成器先以 None 启动,之后 send 的值成为其暂停处 yield 表达式的结果。示例的未知名字被静默忽略,已终止任务仍留在名称字典里;这不是完整的任务注册和失败协议。接收者退出、积压消息、取消及错误报告均须另行处理。

消息队列消除递归调用链保存独立卡片。

原书依据 · 1 处

就绪队列连接事件与协程

协程 yield 一个事件对象以声明等待条件。事件把任务登记到读或写等待表;select 报告就绪后,事件执行一次实际 I/O,并把任务与结果放回就绪队列。调度器用 task.send(result) 恢复任务,使结果到达原 yield 表达式。

结构图:

classDiagram
class YieldEvent {
 +handle_yield(sched, task)
 +handle_resume(sched, task)
}
class ReadSocket {
 +handle_yield(sched, task)
 +handle_resume(sched, task)
}
class WriteSocket {
 +handle_yield(sched, task)
 +handle_resume(sched, task)
}
class AcceptSocket {
 +handle_yield(sched, task)
 +handle_resume(sched, task)
}
class Scheduler {
 +new(task)
 +add_ready(task, msg)
 +run()
}
YieldEvent <|-- ReadSocket
YieldEvent <|-- WriteSocket
YieldEvent <|-- AcceptSocket
Scheduler --> YieldEvent : 登记并恢复等待任务

Socket 包装器的 recv、send、accept 返回上述事件,而不是直接完成系统调用。就绪只意味着应尝试操作;实际完成、部分收发、EOF 和错误必须按系统调用结果继续处理。

就绪队列连接事件与协程保存独立卡片。

原书依据 · 1 处

事件循环必须管理失败边界

教学调度器按文件描述符保存一个读等待者和一个写等待者;同方向第二次登记会覆盖第一个任务。若要支持多个等待者,必须定义排队、合并或拒绝规则。它仅在就绪队列为空时轮询 I/O,持续产生就绪任务可能使 I/O 饥饿。

示例没有统一处理 I/O 异常、任务取消和超时;异常也可能绕过任务计数递减与连接关闭。底层套接字并未配置非阻塞,不能据此承诺任何调用都不会阻塞。行读取没有长度上限,发送返回零又可能令循环不前进。完整实现需要显式任务状态、清理路径、缓冲上限及错误传播,不能直接把这个回显演示用作服务框架。

事件循环必须管理失败边界保存独立卡片。

原书依据 · 1 处

12.13 轮询多个线程队列

普通队列不提供可供 select 等待的文件描述符,轮询多个队列容易引入周期性扫描。示例给队列增加套接字对:真正的数据仍在 Queue,套接字上的通知字节只表示有数据可取,因此队列与网络事件能纳入同一等待集合。

通知描述符桥接线程队列

把线程队列接入 I/O 事件循环,可为队列配一对相连套接字。put 先入队再写一个通知字节;fileno 暴露另一端,select 报告可读后 get 消耗一个字节并取出一项。数据和通知分离,事件循环无需定时扫描队列。

结构图:

classDiagram
class Queue {
 +put(item)
 +get()
}
class PollableQueue {
 +fileno()
 +put(item)
 +get()
}
Queue <|-- PollableQueue
PollableQueue *--> socket : 两端分别发送和接收通知

原例在 POSIX 用 socketpair,在其他系统演示回环连接。这里画出的是原例重写的方法;它省略了 Queue 的 block、timeout 参数,不能直接承诺完整的 Queue 接口兼容性。

通知描述符桥接线程队列保存独立卡片。

原书依据 · 1 处

队列通知必须保持一致

一项数据对应一个通知字节的协议要求两次动作一致完成。示例先入队再发送;发送失败会留下没有通知的数据,发送端缓冲填满又会使 put 阻塞。消费端若读到 EOF 或遭遇异常,也不能继续假定已经消耗一个有效通知。

多消费者下,select 的可读性可能被另一消费者先消耗,随后 get 仍会阻塞;empty 检查也不能提供原子保证。可靠设计要说明单一消费约束或并发仲裁、通知合并与排空、关闭唤醒和资源释放。统一等待集合能够减少轮询延迟,但原文“其他方式只有扫描”过于绝对,转发到公共队列等设计也可改变问题结构。

队列通知必须保持一致保存独立卡片。

原书依据 · 1 处

12.14 在UNIX上加载守护进程

传统 UNIX 守护化先让子进程脱离启动父进程,再建立新会话并通过第二次 fork 放弃会话首领身份;最后处理工作目录、权限掩码、标准流与退出清理。脱离终端不等于免受所有信号,PID 文件也不天然提供单实例保证。

双重派生解除终端关联

第一次 fork 后父进程退出,子进程可调用 setsid 建立新会话并脱离原控制终端。第二次 fork 让最终子进程不再是会话首领,降低以后通过打开终端重新取得控制终端的机会。这是原例传统 UNIX 守护化的目的。

进程还需选择工作目录、文件权限掩码和标准流去向。chdir 避免持续占用启动目录;umask(0) 取消默认权限屏蔽,不能被当作安全默认值,具体文件权限必须另有约束。守护化不会隔离文件、网络权限,也不会屏蔽所有信号。是否需要自行双重派生,应由实际进程启动和监管方式决定。

双重派生解除终端关联保存独立卡片。

原书依据 · 1 处

替换描述符保留流对象

Python 可能有多个对象引用同一标准流,只给 sys.stdout 重新赋值不能更新所有旧引用。dup2 直接把原标准流文件描述符对应的目标替换为新文件,已有流对象于是继续通过同一个描述符号码写到新目标。

替换之前先 flush,避免旧缓冲内容意外落到新目标。底层目标变了,现有文本包装器的编码与缓冲规则不会自动重建;原例依赖标准流具有有效 fileno,在被自定义对象替换的环境中不一定成立。描述符重定向与 Python 对象替换属于两个不同层次。

替换描述符保留流对象保存独立卡片。

原书依据 · 1 处

进程号文件不是实例锁

先检查 PID 文件存在,再以普通写入模式创建,存在检查与写入之间的竞争,两个进程可能同时通过。残留文件、PID 被复用以及可被他人替换的路径,还会令 stop 误判或把信号发给错误对象。PID 文件只是标识线索,单实例和进程身份校验需要额外协议。

示例通过 SIGTERM 处理器抛出 SystemExit,让解释器执行 atexit 删除文件;这只覆盖正常退出链,SIGKILL、崩溃等路径不能保证清理。清理应只删除本实例拥有的文件,并处理文件已消失等错误。原例放在 /tmp 的路径与启动停止代码是机制示范,不能直接作为可靠监管实现。

进程号文件不是实例锁保存独立卡片。

原书依据 · 1 处

第13章 实用脚本和系统管理

脚本的用户接口包括输入来源、命令行声明、错误退出和日志策略。文件与子进程操作又连接外部环境,因此需要路径、权限、编码和部分失败的契约。秒表与资源限额回答不同问题:经过时间、CPU时间和地址空间应分别说明。

13.1 通过重定向、管道或输入文件来作为脚本的输入

脚本输入可以来自标准输入,也可以来自命令行指定的一组文件。fileinput 把这些来源统一成逐行迭代接口,并保留当前文件名和行号,处理逻辑就不必按管道、重定向和普通文件各写一套。

脚本输入要宽容

命令行文本工具可同时支持管道、重定向和文件参数。fileinput.input 在默认方式下解释命令行文件列表,没有文件时使用标准输入,向处理代码提供连续的逐行迭代接口;因此来源变化不必改变核心处理逻辑。

FileInput 上下文管理器负责结束时的文件处理生命周期,filename 提供当前文件名,lineno 是跨输入文件累计行号,单文件行号应另用 filelineno。行通常已带换行,打印时用 end=” 避免再加一个。若脚本还有自定义命令行选项,应先解析选项,再把明确的文件列表交给 fileinput,避免把选项误当文件名。

脚本输入要宽容保存独立卡片。

原书依据 · 1 处

13.2 终止程序并显示错误信息

退出状态面向调用脚本的进程,错误消息面向使用者。未被捕获的 SystemExit 可以同时表达二者;字符串参数表示向标准错误输出该消息并以失败状态退出。

退出状态与错误消息分开

未被捕获的 SystemExit 若携带字符串,解释器把该字符串打印到标准错误,并以状态码 1 退出;整数参数则指定状态码,不自动提供解释消息。需要自定义失败码时,可先输出消息再抛出携带该整数的 SystemExit。

SystemExit 是异常式控制流,可以被外层捕获,也会经过正常的 finally 清理;它不是立即强杀整个进程的通用接口。在工作线程中抛出通常只终止该线程,进程退出决策仍应交给主程序的生命周期管理。

退出状态与错误消息分开保存独立卡片。

原书依据 · 1 处

13.3 解析命令行选项

argparse 用声明描述位置参数和选项,把解析结果放进 Namespace 属性。dest 决定程序访问名称,metavar 决定帮助显示,action 决定保存方式;参数结构和业务验证应分开。

参数声明形成命令行契约

ArgumentParser 通过 add_argument 声明输入结构,再以 parse_args 解析命令行并返回结果对象。位置参数的 nargs=‘*’ 接收零个或多个值;store 保存一个值,append 累积重复选项,store_true 在提供标记时设为真,choices 限制允许的值,required=True 要求选项出现。

dest 控制结果属性名,metavar 控制帮助中的占位文字;二者不应混淆。短选项与长选项可以指向同一输入。解析器负责结构、基本类型和帮助信息,文件是否可读、多个选项是否业务冲突等仍需后续验证。原文末尾写的 parser.parse() 是笔误,实际示例调用的是 parse_args();示例帮助把必选 -p 放在方括号中也不应据此解释为可省略。

参数声明形成命令行契约保存独立卡片。

原书依据 · 1 处

13.4 在运行时提供密码输入提示

getpass 隐藏交互式密码输入的终端回显,getuser 则查询默认用户名,二者承担不同责任。隐藏回显并不完成身份校验,实际登录仍由应用实现。

密码回显与认证各有边界

getpass.getpass 提供交互式秘密输入提示,尽可能关闭终端回显,减少密码在屏幕上暴露。它返回输入字符串,认证、传输和后续保存仍由应用负责;关闭回显不等于内存或传输加密。

getpass.getuser 不提示输入用户名,而是从环境变量等来源确定一个默认名字,必要时查询支持平台的系统用户信息。这不能充当可信身份认证;需要用户明确选择名字时可另外提示输入。某些终端无法隐藏输入,getpass 会发出警告并回退,脚本应按实际交互环境处理,不能宣称密码一定不显示。

密码回显与认证各有边界保存独立卡片。

原书依据 · 1 处

13.5 获取终端大小

终端尺寸以列和行为单位,可用于换行及表格布局。os.get_terminal_size 查询终端描述符,不能把其示例输出当作固定环境值。

终端布局依赖实际尺寸

os.get_terminal_size 返回含 columns 和 lines 的终端尺寸对象,程序可以据此决定文本换行、列宽或分页。80列24行只是示例,不是终端保证。

查询依赖有效终端描述符,输出被重定向到普通文件等情形可能失败;终端尺寸也会在运行中改变。程序应为无终端和查询失败设计可用的布局回退,不把一次取得的尺寸当作永久事实。

终端布局依赖实际尺寸保存独立卡片。

原书依据 · 1 处

13.6 执行外部命令并获取输出

子进程调用需要分别处理参数、标准流、退出状态与等待时间。check_output 适合取得结果,Popen 和 communicate 暴露更完整的输入输出交互。是否经过 shell 会改变字符串的解释方式。

子进程结果包含状态与输出

check_output 成功时返回捕获的标准输出,默认是字节串,解释为文本须匹配实际编码。非零退出状态引发 CalledProcessError,可从异常取得状态和已捕获输出;超时引发 TimeoutExpired。标准错误默认不包含在结果中,合并到 STDOUT 后又会丢失两条流的独立边界。

Popen.communicate 可同时送入输入并读回配置为 PIPE 的输出,减少手工顺序读写管道造成的死锁。未捕获的 stderr 返回 None,原例直接 stderr.decode 会失败。捕获结果还需考虑内存上限;命令退出成功也不自动证明业务结果完整。

子进程结果包含状态与输出保存独立卡片。

原书依据 · 1 处

参数列表避开壳层解释

直接把程序及各参数作为列表交给 subprocess,参数中的空格和特殊字符通常作为参数内容传递,不由 shell 执行管道或重定向。显式使用 shell=True 后,字符串按相应壳层语言解释,拼入的外部输入可能变成命令。

shlex.quote 针对兼容的 Unix shell 参数引用,不能当作所有平台和所有语法位置的安全通用模板。需要管道时可显式连接子进程,或在确实需要 shell 时限定并验证解释边界。普通 PIPE 也不是终端设备;依赖交互TTY的程序需要终端适配,不应把书中“subprocess完全不能”理解为所有底层组合都不可能。

参数列表避开壳层解释保存独立卡片。

原书依据 · 1 处

13.7 拷贝或移动文件和目录

shutil 为文件内容、元数据、目录树与移动提供不同层次的接口。复制什么、如何处理符号链接、遇到部分失败如何交代,必须由调用者明确。

复制内容不等于完整备份

copy 复制内容并尽量保留权限,copy2 再尽力复制更多元数据;copytree 递归复制目录树,move 的行为则涉及重命名或跨文件系统复制后删除。它们不保证保存所有属主、ACL、资源分支或平台扩展信息,因此不能只凭成功返回认定得到完整系统备份。

符号链接要区分复制链接指向的内容与复制链接本身:文件复制使用 follow_symlinks,目录树复制使用 symlinks。源中的“创建时间总能保存”不成立,应按具体平台和元数据能力核对;现代接口也可接受相应路径对象,不局限于字符串。

复制内容不等于完整备份保存独立卡片。

原书依据 · 1 处

目录复制需报告部分失败

copytree 可通过 ignore 回调按当前目录及名称列表选择忽略项,ignore_patterns 提供常见通配规则。回调返回的是待忽略名称;原例列表推导式缺少 for,不能直接执行。

目录树复制可能已经写出部分内容才报告错误。shutil.Error 可归集源、目标和错误信息,恢复流程需要说明哪些已完成、如何重试以及是否覆盖已有目标,不能把它当作事务回滚。悬垂链接选项名应为 ignore_dangling_symlinks,原文 sumlinks 是笔误;是否忽略此类链接也不是所有链接策略都同义。

目录复制需报告部分失败保存独立卡片。

原书依据 · 1 处

13.8 创建和解包归档文件

归档高层接口把格式选择与单个成员的底层处理分开。make_archive 选择输出格式,unpack_archive 解包;但创建和解包都涉及真实文件路径及资源限制。

归档接口仍需路径边界

shutil.make_archive 根据格式名创建归档,get_archive_formats 查询运行环境支持的创建格式;unpack_archive 提供高层解包接口。只有需要逐成员控制、流式处理等细节时才进一步使用 tarfile 或 zipfile。

格式列表受解释器与依赖支持影响,书中列举不代表永久全集。解包不可信归档时须限定目标、成员路径与资源消耗,并核对所用格式和版本的过滤行为;高层接口本身不能消除覆盖、越界路径或解压资源耗尽的风险。当前文档还记录了 tar 过滤默认值的版本变化,不能将历史示例作为跨版本的默认安全保证。

归档接口仍需路径边界保存独立卡片。

原书依据 · 1 处

13.9 通过名称来查找文件

目录遍历提供目录路径、子目录名及文件名,查找程序应基于返回的当前目录拼接目标。路径正规化只整理表示,不证明文件身份、权限或查询期间不变化。

遍历结果自带当前目录

os.walk 每次返回当前目录路径、子目录名称列表和文件名称列表。匹配文件名后,应以返回的当前目录路径拼接名称,再按输出需要转成绝对路径。返回路径随起点而定,不应一概称作相对于起点的路径;原例再次 join(start, relpath, name) 在相对起点下可能重复前缀。

按修改时间筛选需要读取实际文件元数据。exists 后文件仍可能被删除或替换,因此后续 stat 还须处理失败。abspath、normpath 整理路径表示,不等于解析符号链接或证明路径指向预期对象;对遍历范围和链接策略应另行约定。

遍历结果自带当前目录保存独立卡片。

原书依据 · 1 处

13.10 读取配置文件

INI配置把区段和字符串值组织为数据,类型解释由读取接口完成。插值在取值时解析,因此后读配置覆盖某个基础值后,引用它的派生值也能随之改变。

配置插值在取值时展开

ConfigParser 把配置分成区段和选项,原始值主要是字符串,getint、getboolean 等接口再按明确规则转换。默认选项名不区分大小写,但区段名区分大小写,不能把“配置名称都不敏感”泛化到两者。

默认百分号插值允许 library 引用同区段的 prefix;整个文件读取后,get 才解析引用,所以声明先后不必像程序语句一样排列。多次 read 会合并配置,后读的同名选项覆盖旧值,其余保留;之后改变 prefix 能影响下一次 library 取值。缺失引用和循环插值仍可能报错,并非任意变量或Python表达式都可执行。

配置插值在取值时展开保存独立卡片。

原书依据 · 1 处

配置读写还需验证契约

读取配置成功不等于配置有效:缺失区段、无效布尔或数值、越界端口以及不允许的路径仍需应用验证。read 返回成功读取的文件列表,不应据此假设每个请求文件都存在。

set 修改内存配置,write 向指定文本流输出;原例写到 sys.stdout,并未自动更新原文件。重写也不承诺保留原注释和版式。INI实现存在语法差异,跨程序共享配置应验证具体支持的插值、分隔符和多行规则。

配置读写还需验证契约保存独立卡片。

原书依据 · 1 处

13.11 给脚本添加日志记录

应用在入口配置日志去向、级别与格式,业务调用只提交诊断记录。日志级别过滤与消息格式化是不同步骤,后续库章节再补充命名记录器与处理器传播。

日志记录分离筛选与格式

critical、error、warning、info、debug 表达不同严重程度,级别阈值筛掉低于要求的记录。消息模板与参数分开传给日志接口,可以把字符串插值推迟到实际需要格式化时;这不意味着计算参数的函数调用也会自动延迟。

basicConfig 为简单应用配置根记录器的处理器、输出位置和格式;不指定文件时默认输出标准错误。已有处理器时再次调用通常不改变配置,所以应由程序入口统一建立策略。原文“只能调用一次”不精确,现代接口可用 force 显式重配;级别修改宜使用 setLevel,而不是直接改属性。配置文件可把运行策略从代码分离,但须是可信配置。

日志记录分离筛选与格式保存独立卡片。

原书依据 · 1 处

13.12 给库添加日志记录

库不知道宿主应用希望把日志写到哪里,因此提供命名记录器和诊断信息,由应用选择处理器与输出策略。NullHandler 提供无输出的默认处理,而命名层级仍允许消息向上传播。

日志边界在调用方

库以 getLogger(name) 获取模块命名记录器,用它提交日志,避免在导入时配置整个应用的根日志。库可加 NullHandler,在没有应用处理器时保持安静;应用随后统一配置去向和格式,或对某一命名记录器调整级别以定位问题。

命名记录器是层级体系的一部分,并非完全隔离。NullHandler 也不会自动停止向父记录器传播。记录通过本记录器有效级别后,会交给祖先的处理器,祖先记录器自身的级别不重新过滤该记录,处理器级别仍会过滤。因此书中子记录器DEBUG越过根ERROR的示例,依赖根处理器允许DEBUG,不能解释成子配置无条件覆盖所有全局过滤。

日志边界在调用方保存独立卡片。

原书依据 · 1 处

13.13 创建一个秒表计时器

秒表需要选对时钟,也需要管理启动和停止状态。示例用状态字段防止重复开始或未开始就停止,并把多个区间累计起来;上下文协议把区间结束放到退出路径。

计时时钟决定测量含义

测量耗时使用同一种时钟的两次读数之差。perf_counter 适合经过时间,包含睡眠和等待;process_time 计进程CPU时间,不把睡眠等待当成CPU消耗。因此它们回答的问题不同,结果不能直接互换。

这些计时值的参考起点不是可展示的日历时间,不能用单个读数解释日期。原文把 perf_counter 称为“系统时钟时间”容易混淆,它用于高分辨率经过时间测量,不应等同于可能被校正的 time.time 日历时钟。历史 time.clock 接口也不作为现代代码推荐。

计时时钟决定测量含义保存独立卡片。

原书依据 · 1 处

秒表用状态约束测量区间

Timer 保存累计 elapsed 和当前区间起点 _start。start 只允许从停止态进入运行态;stop 只允许运行态,计算差值后累加并清空起点。上下文入口调用 start,出口调用 stop,因此异常退出也能结束该次计时。

结构图:

classDiagram
class Timer {
 +start()
 +stop()
 +reset()
 +running
 +__enter__()
 +__exit__(*args)
}

示例 reset 只清累计值,并不重置正在运行的起点;运行中调用后 stop 仍会计入自原起点开始的完整区间。若需要另一种重置语义,应明确修改状态契约。elapsed 在运行中也不包含尚未 stop 的区间;该对象没有并发或嵌套计时保证。

秒表用状态约束测量区间保存独立卡片。

原书依据 · 1 处

13.14 给内存和CPU使用量设定限制

UNIX资源限制以软限额和硬限额表达;资源种类决定限制的是CPU时间、地址空间还是其他数量,不能笼统解释为统一的运行时长和内存占用。

资源软限额受硬限额约束

getrlimit 取得某一资源的软、硬限额,setrlimit 修改它们。软限额是当前生效约束,不能超过硬限额;普通进程可在硬限额内调整软限额,也可降低自己的硬限额,通常不能再把硬限额升回去。原文说用户进程连降低自身硬限额也不允许,是错误表述。

RLIMIT_CPU 限制CPU消耗时间,达到软限额可能发送 SIGXCPU,它不是墙钟超时;RLIMIT_AS 限制虚拟地址空间,也不是常驻物理内存。分配失败可能表现为 MemoryError,但不能保证所有底层库和进程失败都转成同一种Python异常。资源可用性和执行行为依赖系统,须在目标平台验证。

资源软限额受硬限额约束保存独立卡片。

原书依据 · 1 处

13.15 加载Web浏览器

webbrowser 把打开URL的请求交给可用浏览器控制器。新窗口、新标签页是尽力请求,返回成功不能代替页面可达和业务结果验证。

打开浏览器只证明请求发出

webbrowser.open 请求默认浏览器打开URL,open_new 和 open_new_tab 分别请求新窗口或标签页;是否采用该形式取决于浏览器支持。get 可选择已支持并可用的控制器,不代表任何名称都已安装或可启动。

接口的成功返回描述浏览器请求能否发出,不证明网页已加载、HTTP状态正确或部署成功。脚本若要验证服务,应另行检查对应结果;若只需展示本地产出,则把展示动作与产出校验分别记录。

打开浏览器只证明请求发出保存独立卡片。

原书依据 · 1 处

第14章 测试、调试以及异常

测试把预期行为转化为可观察结果,替身隔离外部波动,异常断言验证失败契约。测试加载、运行和报告各有职责;诊断通过回溯与调试器定位现场,剖析则决定优化重点。正确性、观测口径和性能收益需要分别给出证据。

14.1 测试发送到stdout上的输出

输出测试应观察程序实际写入的流。将 sys.stdout 暂时替换为 StringIO,可对纯Python打印的完整文本断言,同时把替换范围限制在测试上下文。

捕获输出要匹配写入层

暂时把 sys.stdout 换成 StringIO,再执行被测函数并比较 getvalue,可以验证 print 产生的文本,包括结尾换行。patch 上下文在退出时恢复原属性,因此异常路径也能结束这次替换。

替换只影响实际查询该 Python 对象的代码;提前缓存了原流的引用、直接写文件描述符的C代码或子进程输出,不一定被捕获。这些情况需要相应层次的重定向。sys.stdout 也可能原本指向文件而不是屏幕;测试应声明观察的是文本流契约。

捕获输出要匹配写入层保存独立卡片。

原书依据 · 1 处

14.2 在单元测试中为对象打补丁

patch 替换的是某个名称当前绑定的对象,因此目标必须选在被测代码查找它的位置。MagicMock 记录调用并提供可控返回,使测试摆脱真实网络等外部波动,但并不自动证明替身符合真实依赖。

patch隔离状态

patch 在限定范围内替换名称绑定,退出上下文或装饰的调用后恢复;手动 start 则须确保 stop 在清理路径运行。被测模块用 from urllib.request import urlopen 时,应替换 example.urlopen,因为函数从该模块名字查找依赖,替换来源模块的同名属性不一定影响已经绑定的引用。

MagicMock 可配置返回值、记录调用,并用参数断言检查交互。assert_called_with 只检查最近一次调用,不能单独证明只调用了一次。可预测数据能隔离外部网络,仍应验证被测函数的输出;公共流式样本被消耗后不能无条件跨测试复用。堆叠装饰器按从下往上应用的顺序传入替身,原例 mock1、mock3 名字不能代替对应关系。

patch隔离状态保存独立卡片。

原书依据 · 1 处

14.3 在单元测试中检测异常情况

异常测试必须同时覆盖“抛出正确异常”和“本该抛却没抛”。assertRaises 自动把未抛出视为失败,避免手写 try/except 只验证进入异常分支时才做断言。

异常断言也要验证未抛分支

assertRaises 接受预期异常类型及可调用对象,错误类型或没有异常都会使测试失败。上下文形式把待测操作放在 with 范围内,assertRaisesRegex 还可检查异常消息,但应避免依赖不稳定的完整措辞。

上下文形式的 as cm 可以通过 cm.exception 检查 errno 等异常属性,因此原文“不能检查异常对象值”过于绝对。手工 try/except 也能实现,但必须给无异常路径添加失败断言。with 中只放与预期异常直接相关的最小操作,避免其他步骤抛出同类型异常而造成误通过。

异常断言也要验证未抛分支保存独立卡片。

原书依据 · 1 处

14.4 将测试结果作为日志记录到文件中

unittest 将测试收集和运行分开。TestLoader 组织套件,TextTestRunner 执行它并把诊断写入指定流;报告去向和测试是否成功属于不同结果。

测试装配与执行相分离

TestLoader 从模块或 TestCase 类收集测试,组成测试套件;TextTestRunner 运行套件并产生结果对象,还可配置报告流与详细程度。这让选择测试和展示报告能够分别定制。

默认文本测试报告通常写到标准错误,原文把它称为标准输出不准确。示例把报告流指向文件,但自定义 main 没有依据 run 返回结果设置失败退出码,所以报告中有失败也可能以状态0结束。自动化调用还应检查结果的 wasSuccessful 并明确退出状态;捕获测试本身打印的内容又是另一项需求。

测试装配与执行相分离保存独立卡片。

原书依据 · 1 处

14.5 跳过测试,或者预计测试结果为失败

跳过表示当前条件下不执行测试,预期失败表示仍执行并把已知失败作为特殊结果。两者记录的证据不同,不能把缺运行条件和已知缺陷合并。

跳过与预期失败保留区别

skip 无条件不执行测试,skipIf 和 skipUnless 根据平台、版本或依赖条件决定是否执行,并要求可理解的原因。它们适合表达“当前环境不适用”,不提供被测功能通过的证据。

expectedFailure 仍运行测试,已知失败会单独记录;若意外成功,也会产生不同结果,提醒移除过时的失败标记。它不是无条件吞掉所有测试问题的开关。应关联明确原因和后续处理,避免把永久跳过或预期失败计为正常通过。

跳过与预期失败保留区别保存独立卡片。

原书依据 · 1 处

14.6 处理多个异常

多个异常可以共享恢复路径,也可以按更具体的类别分别处理。匹配顺序决定进入哪个处理器,继承关系决定基类捕获会覆盖哪些子类。

异常处理按语义分组

多个异常确实采用同一种恢复策略时,可在 except 的元组中列出它们;若超时应重试、输入错误应反馈,就应分开。用基类捕获会同时包含更多子类型,只有这些错误都能由当前策略处理时才适用。

except 从上到下选择第一个匹配项,宽泛的基类放在前面会遮住后续子类分支。可通过异常类型的 mro 理解继承层级,并检查 errno 等业务相关属性。原文说MRO中只有BaseException之前的类型能用于except不准确:BaseException 本身也能匹配,但范围更宽,是否捕获须由退出和恢复语义决定。

异常处理按语义分组保存独立卡片。

原书依据 · 1 处

14.7 捕获所有的异常

宽泛捕获会把输入错误和程序错误放进同一路径,因此诊断和传播策略必须清楚。Exception 通常覆盖应用错误,BaseException 还包含退出、中断等控制异常。

宽泛捕获不能抹平失败原因

except Exception 会捕获普通应用异常,包括可能暴露程序缺陷的 NameError;它通常不包含 SystemExit、KeyboardInterrupt 和 GeneratorExit。若无差别输出“解析失败”,变量名写错也会被伪装成坏输入,正常输入同样无法成功。

能够恢复的错误应精确捕获;服务边界确需接住较宽的错误时,应保留异常类型、上下文或回溯并报告,不能悄悄返回貌似成功的结果。捕获 BaseException 会扩大到退出与中断路径,若用于清理,通常应重新抛出以保留控制语义。

宽泛捕获不能抹平失败原因保存独立卡片。

原书依据 · 1 处

14.8 创建自定义的异常

自定义异常用领域类型表达失败类别,继承结构让调用者选择精细或宽泛的处理范围。初始化还要保留标准异常约定,便于打印、传递与诊断。

异常类型表达领域失败

应用异常通常继承 Exception 或已有的适当子类。NetworkError 作为领域基类,再用 HostnameError、TimeoutError、ProtocolError 区分失败,使调用者既能按具体问题恢复,也能在边界统一捕获网络领域错误。

结构图:

classDiagram
Exception <|-- NetworkError
NetworkError <|-- HostnameError
NetworkError <|-- TimeoutError
NetworkError <|-- ProtocolError

图中 TimeoutError 是原例自定义类型,不能误当内建同名异常。直接继承 BaseException 的类型仍能被显式捕获,原文所谓“无法捕获”不成立;问题在于它会绕过惯常的 except Exception,破坏普通应用错误处理约定。

异常类型表达领域失败保存独立卡片。

原书依据 · 1 处

异常参数保留标准表示

自定义异常若添加 message、status 等属性,可以在 init 中调用 super().init(message, status),使标准 args 元组与这些构造参数一致。调用者和工具于是能按惯常方式打印、检查或重建错误。

应保留的是清楚的构造和序列化契约,并非“只要没调用基类初始化就必然没有args”:标准异常自身的创建机制也参与保存参数。若改造参数、定制重建或新增状态,应显式验证这些行为,避免诊断信息与领域属性互相矛盾。

异常参数保留标准表示保存独立卡片。

原书依据 · 1 处

14.9 通过引发异常来响应另一个异常

跨抽象层转换异常时,raise 新异常 from 原异常明确说明因果;在处理过程中意外再出错则表现为上下文链。保留二者的区别有助于分辨有意转换与新的程序缺陷。

异常链保留因果

把底层失败转换为领域失败时,raise NewError(…) from e 将原异常设置为 cause,在回溯中明确标出直接原因。在处理异常时自然发生另一个异常,则原异常保存在 context,描述处理期间的上下文,而不自动表示有意的业务因果。

from None 抑制默认展示上下文,不等于从对象中删除所有原异常信息;应按面向用户的诊断边界选择,并在适当位置保留可定位信息。若只是继续传播同一失败,裸 raise 即可。访问 except … as e 绑定的对象须在有效作用域内,原文把使用e的代码放在except外会受到块结束时清理绑定的影响。

在 except 中完成日志或清理后使用裸 raise,可重新抛出当前异常,不必为了继续传播而新建一个错误。它和 raise NewError from e 的职责不同:前者保留失败身份,后者转换抽象层并声明原因。没有活动异常可重新抛出时,裸 raise 本身会失败。

异常链保留因果保存独立卡片。

原书依据 · 2 处

14.10 重新抛出上一个异常

异常处理可以增加诊断或清理,而不改变原失败。裸 raise 重新传播当前处理的异常;转换为不同异常时才需要另外选择显式因果链。

异常链保留因果关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

14.11 发出告警信息

告警用于在继续兼容的同时传达迁移或使用风险。告警类别和过滤规则共同决定它被展示、忽略还是转换为异常,因此发出告警不意味着每次都会被用户看到。

warning适合迁移

warnings.warn 用消息和类别表达弃用、未来行为变化或资源使用问题,让调用者在兼容期内获得迁移线索。类别不是严重程度的简单排序,而是供过滤和处理的语义标签。

过滤规则可忽略、显示或把告警转成异常,命令行 -W 与 warnings.simplefilter 均能调整。默认并非显示所有类别;库不能依赖一条告警必定可见来保证安全或正确性。需要定位调用者时应设置恰当的 stacklevel,使告警指出使用位置;资源告警也不能代替确定性的关闭和清理。

warning适合迁移保存独立卡片。

原书依据 · 1 处

14.12 对基本的程序崩溃问题进行调试

先从异常回溯辨认失败位置,再在适当作用域检查变量。交互入口、事后调试、主动断点和当前栈打印提供不同时间点的证据。

调试先区分栈与回溯

异常回溯保留失败沿途的调用路径,可据此检查哪一步及什么输入不符预期。python -i 在脚本结束后进入交互环境,能查看仍可访问的状态;pdb.pm 可进入最近异常的事后调试,检查失败栈帧中的局部变量。

traceback.print_exc 输出正在处理的异常回溯,print_stack 输出调用当下的栈,二者回答不同问题。pdb.set_trace 在指定位置暂停运行,适合观察未崩溃却结果错误的控制流。诊断输出应保留必要上下文并避免泄露秘密;调试会执行表达式并暂停程序,不应无意留在运行服务中。

调试先区分栈与回溯保存独立卡片。

原书依据 · 1 处

14.13 对程序做性能分析以及计时统计

整体计时定位规模,剖析定位时间分布,微基准比较受控片段。应先明确测量问题,再选择时钟与工具,避免拿不同测量口径直接比较。

先剖析再优化

先对有代表性的负载测量,再决定优化哪里。整体 real、user、sys 时间描述不同耗时;cProfile 按调用统计帮助定位热点,tottime 是函数自身时间,cumtime 包括被调函数。高累计时间不一定意味着该函数自身需要改写。

已知范围可用装饰器或上下文管理器计时,短片段可用 timeit 反复运行并把环境准备与测量分开。经过时间包含等待,CPU时间强调处理器消耗;负载、缓存、预热和测量开销都会改变结果。原书数字只说明当时样例,不构成当前环境的性能承诺。

局部的dict构造、属性访问等微基准差异,不代表程序总耗时会同幅改善。应把修改限制在已测出的热点,并重新确认行为和整体指标。原书对PyPy、Numba的Python3支持判断属于写作时代背景,不作为今天的可用性判断。

先剖析再优化保存独立卡片。

原书依据 · 2 处

计时范围必须包含失败策略

上下文计时器把结束读数放在 finally,能在代码块异常退出时也记录经过时间。普通装饰器若在被调函数返回后才取结束时间,异常会绕过记录;两种写法测得的事件集合因此不同。

比较时还须明确重复次数、准备开销和输出开销是否计入。timeit 的返回通常是整批运行的总耗时,要换算单次成本需使用相应次数。测量代码不能吞掉原异常或改变被测结果;耗时记录和业务成功应分别表达。

计时范围必须包含失败策略保存独立卡片。

原书依据 · 1 处

14.14 让你的程序运行得更快

优化应先验证正确性、量出热点,再考虑算法、数据移动和频繁查找的成本。局部缓存和减少包装是有条件的手段,不能为了历史微基准牺牲语义和必要约束。

先剖析再优化关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

热点优化先看算法与数据

先确认算法和工作量,再减少热路径中不必要的构造与复制。内建容器常有高效实现;删除仅用于中转的列表,可以降低分配和遍历开销。但容器选择仍要满足所需操作复杂度,不能认为任意内建类型都优于一切专用结构。

减少 deepcopy 前要确认共享可变数据的所有权和隔离需求,不能仅凭复制看起来多余就删除。复杂度改进也受数据规模、常数和最坏情况影响;先正确工作,再用有代表性的测量确定收益。

热点优化先看算法与数据保存独立卡片。

原书依据 · 1 处

缓存查找须保持原有语义

在热循环中把重复查找的函数、绑定方法或属性移到局部变量,可能减少动态查找成本;把脚本逻辑组织成函数也让局部状态更明确。只有这些成本实际占据热点时,改写才值得。

缓存会固定取得时的对象或值,循环中原属性变化、动态替换或描述符副作用可能不再被观察,因此必须先确认语义不变。property、装饰器和描述符也可能维护必要不变量,不能只为减少一次调用就拆掉。解释器优化会改变收益,书中15%~30%、4.5倍等数字均是历史测试,不应直接推广。

缓存查找须保持原有语义保存独立卡片。

原书依据 · 1 处

第15章 C语言扩展

C互操作把Python通常代管的责任显露出来:ABI和类型匹配决定如何解释存储,引用与缓冲决定地址能活多久,错误标志决定失败如何传回。ctypes、手写API、SWIG和Cython只是不同包装路径,都会遇到这些共同约束;释放GIL也不能免除原生数据同步。

跨语言边界先明确有效输入

C函数签名描述内存表示和调用方式,却不完整表达有效输入。divide 的除数必须非零,还需处理有符号整数除法溢出;avg 需要有效数组指针和正长度,gcd 的示例循环也没有覆盖一般负数输入。

Python包装器应先定义输入范围、结果和失败契约,再进入C调用;不能假设非法输入都会自动变成Python异常。in_mandel 在有限迭代内未逃逸只表示这次数值试验的结果,并非对任意点属于集合的无限过程证明。

跨语言边界先明确有效输入保存独立卡片。

原书依据 · 1 处

15.1 利用ctypes来访问C代码

ctypes 把已存在的共享库函数绑定到Python,argtypes 与 restype 声明C边界,包装函数再把指针输出和数组输入转成适合Python的接口。声明类型不能替代对真实缓冲布局和生命周期的验证。

ctypes连接现成库

ctypes 可在Python中加载共享库并取得导出函数,argtypes 声明参数的C类型,restype 声明返回类型。路径、体系结构、字长与调用约定必须兼容;仅找到库文件不代表符号或ABI匹配,也不要求所有情形机械使用完全相同编译器。

没有正确签名时,指针或返回值可能被错误解释,导致内存损坏而非普通类型异常。Python包装层还应检查取值范围、底层错误和资源所有权;ctypes并不自动把C接口变成安全的Python接口。find_library 的结果依系统而变,不能硬编码书中的路径作为安装事实。

ctypes连接现成库保存独立卡片。

原书依据 · 1 处

输出参数封装为业务结果

C的divide把商作为返回值,把余数写入 int* 指向的存储。包装器创建可变的 ctypes.c_int,将它传给声明为相应指针的参数,调用后读取 value,再返回(商,余数)元组。

普通Python整数不是可供C改写的int存储。声明 POINTER(c_int) 后,相应ctypes实例可由接口进行隐式按引用转换;也可按契约显式传递地址。包装层仍要防止除零和溢出,并记住C有符号整数除法与Python的向下取整在负数上可能不同。

输出参数封装为业务结果保存独立卡片。

原书依据 · 1 处

数组指针必须匹配内存布局

from_param 适配器把多种Python输入转换为C参数。列表或元组需要新建连续的c_double数组;array(’d’)或合适NumPy数组可暴露既有缓冲。因此接受多种容器不等于每次都零复制。

结构图:

classDiagram
class DoubleArrayType {
 +from_param(param)
 +from_array(param)
 +from_list(param)
 +from_ndarray(param)
}
DoubleArrayType --> ctypesArray : 列表转换的新存储
DoubleArrayType --> arrayArray : 读取原缓冲地址
DoubleArrayType --> ndarray : 取得数据指针

原例按类型名分派,并对任意ctypes.Array宽松放行;NumPy分支也没检查dtype、连续性、维度和本机字节序。len对多维数组也不等于元素总数。必须核验这些条件及长度范围,并保持原对象存活且不改变缓冲布局,才能把double*和长度交给C。

数组指针必须匹配内存布局保存独立卡片。

原书依据 · 1 处

结构体布局也是调用契约

ctypes.Structure 子类用 fields 声明字段名和C类型,Point的两个c_double字段对应C结构中的x与y。把 POINTER(Point) 用在函数签名中,才能按相应布局向距离计算函数传递结构体地址。

字段顺序、对齐和打包规则必须与真实库一致,不能只因名字相同就认为结构兼容。若C保存指针供调用结束后使用,Python对象生命周期还必须延长;结构体包装本身不解决所有权和异步保留问题。

结构体布局也是调用契约保存独立卡片。

原书依据 · 1 处

15.2 编写简单的C语言扩展模块

手写扩展函数把Python对象解析为C值,调用库,再构造Python结果;每个阶段都需要检查失败。方法表和模块初始化把包装函数接到Python可导入的模块上。

扩展函数成对报告错误

METH_VARARGS形式的包装函数接收PyObject参数元组,用PyArg_ParseTuple按格式代码解析到C变量;该函数失败返回0并设置Python异常,包装函数应返回NULL。原文把解析器返回写成NULL,混淆了整数成功标志和包装函数的对象指针。

成功路径用Py_BuildValue等构造Python对象,可将商和余数组成元组。构造也可能因分配失败返回NULL。底层业务错误若不能安全执行,包装器应先设置适当异常再返回错误标志;返回NULL却未设置异常,或成功返回对象却遗留异常,都会破坏C API契约。

扩展函数成对报告错误保存独立卡片。

原书依据 · 1 处

方法表连接模块与包装函数

PyMethodDef把Python可见名称、C函数指针、调用标志与文档连接起来,调用标志必须符合C函数原型。PyModuleDef再引用方法表,PyInit_sample在示例单阶段初始化中创建并返回模块对象,由导入机制完成后续工作。

模块级函数中的self通常指向模块,不只是在类方法时才有意义。-1状态大小是原例的模块状态选择,不应推广为所有解释器和并发环境的安全默认。编译与动态链接还需匹配解释器ABI、平台及依赖库;书中distutils构建属于历史方式,不能直接当作现代发布流程。

方法表连接模块与包装函数保存独立卡片。

原书依据 · 1 处

15.3 编写一个可操作数组的扩展函数

缓冲协议让扩展依赖内存契约,而非某个数组库。先取得视图并核对维度、格式和连续性,再调用C;最后必须在每条已取得视图的退出路径释放它。

缓冲协议解耦数组来源

PyObject_GetBuffer向支持缓冲协议的对象请求视图,Py_buffer描述地址、字节长度、元素大小、维度、形状与步长等。原例要求连续且带格式的一维double数组,因此array与合适NumPy数组都可使用,普通list不能直接提供同样的存储。

能够取得指针不代表任意读取都合法;须检查本机double格式、维度、连续性、长度和对齐等实际要求。原例将shape[0]传给int长度,还需处理溢出及空数组,不能让avg除以零。协议格式比简单struct格式更丰富,原文“任意格式都与struct兼容”不宜泛化。

缓冲协议解耦数组来源保存独立卡片。

原书依据 · 1 处

缓冲视图的取得必须配对释放

成功取得Py_buffer后,调用者承担释放视图的责任。无论后续校验失败还是计算成功,都应调用PyBuffer_Release;取得失败时则不能释放未初始化的视图。它结束导出约定并管理关联引用,不表示直接free底层数组。

视图持有期间不能擅自释放、重新分配或越界访问缓冲。只读请求也不保证其他参与者不会修改内容,因此释放GIL或并发处理时仍需数据同步和所有权约束。原文讨论写作PyBuffer_GetBuffer,真实API是PyObject_GetBuffer。

缓冲视图的取得必须配对释放保存独立卡片。

原书依据 · 1 处

15.4 在C扩展模块中管理不透明指针

Capsule把不透明C指针装进Python对象,用名称核验取出协议,并可挂接析构器。它隐藏结构细节,但底层资源究竟由谁释放仍必须明确。

Capsule封装指针

PyCapsule保存不透明指针及可选名称,PyCapsule_GetPointer以预期名称提取它;名称或对象不符会设置异常并返回NULL。统一的FromPoint、AsPoint适配函数把包装机制集中起来,其他扩展函数无需依赖具体封装方式。

析构器可在Capsule销毁时回收底层分配,must_free表达此包装是否拥有资源。借用指针若指向更大结构,必须保持真正所有者存活,不能因没有析构器就认为不会悬空;同一指针的多个拥有者又可能重复释放。名称校验是协议检查,不是对任意内存的安全证明。

Capsule封装指针保存独立卡片。

原书依据 · 1 处

原生分配失败也要清理

malloc失败需要先检查再写字段,并向Python报告内存错误。分配成功后,如果创建Capsule失败,指针尚未转交给可运行析构器的对象,包装器必须自行释放,避免泄漏。

析构器取指针也要尊重错误契约,释放函数必须匹配分配来源,不能把借用或栈上地址交给free。资源转交应有明确成功点:此前由创建者清理,此后由约定所有者清理。Python自动管理包装对象,不会替扩展推断所有原生资源的归属。

原生分配失败也要清理保存独立卡片。

原书依据 · 1 处

15.5 在扩展模块中定义并导出C API

扩展模块可以把函数指针表封装进Capsule,以模块属性公开。使用方通过Python导入取得表,再经间接调用访问API,从而避免直接链接到另一个扩展的导出符号。

函数指针表发布扩展接口

提供方建立包含aspoint、frompoint函数指针的表,把表地址放入命名Capsule并发布为sample._point_api。使用方通过PyCapsule_Import取得表,在调用前完成初始化,头文件宏再把普通函数形式展开为表中的间接调用。

表的布局、函数签名、生命周期和版本必须兼容。Capsule名称校验不验证整个ABI,也不会替模块解决线程或子解释器状态。原例FromPoint宏只有一个参数,而表中frompoint需要指针和所有权标志,这是应修正的接口笔误。

函数指针表发布扩展接口保存独立卡片。

原书依据 · 1 处

导出接口失败必须阻止发布

模块初始化中,创建模块、创建Capsule以及把对象加入模块都可能失败。任何一步失败都应释放本阶段拥有的引用并返回NULL,不能带着已设置的异常返回貌似成功的模块。

原例未完整检查Capsule和AddObject结果,使用方导入接口失败也没有释放已创建模块。使用PyModule_AddObject等API时还要核对引用转移的成功条件,避免泄漏或重复释放。函数表消除了直接链接这一层依赖,提供方模块和原生依赖仍须能够正确加载,不是完全无依赖。

导出接口失败必须阻止发布保存独立卡片。

原书依据 · 1 处

15.6 从C中调用Python

C调用Python时必须显式构造参数、调用对象、检查失败、转换结果和释放拥有的引用。线程进入解释器的状态约束也必须满足,但示例中的abort只是演示失败策略,不能视作不可避免。

原生回调必须保留失败通道

PyCallable_Check只能确认对象可调用,不能保证给定参数能成功执行。PyObject_Call接收位置参数元组和可选关键字字典,成功返回新引用,失败返回NULL并设置Python异常。应先检查参数构造和调用结果,再提取结果,最后释放本层拥有的引用。

C没有Python式自动栈展开,但可以以状态码和输出参数传递失败,并让返回Python的包装函数继续传播异常。原例abort会终止整个进程,并非唯一选择。打印并清除异常还会改变后续传播条件,应由边界协议明确决定,不要同时返回成功值和隐藏失败。

原生回调必须保留失败通道保存独立卡片。

原书依据 · 1 处

新引用与借用引用分开清理

C API结果要区分新引用与借用引用。构造参数、取得属性和调用结果通常带来本层应释放的新引用;参数中借来的对象则不能无故减引用。Py_XDECREF容许NULL,Py_DECREF要求有效对象,不能用前者掩盖遗漏的错误检查。

原例import_name没有检查名称创建、模块导入和属性获取,也遗漏了模块引用释放。公共失败出口可以集中清理,但指针须先初始化,且每次所有权转移后更新状态。资源清理和错误报告必须同时覆盖所有中途失败。

新引用与借用引用分开清理保存独立卡片。

原书依据 · 1 处

进入解释器须匹配线程状态

传统启用GIL的CPython中,外部线程访问普通Python C API前需要有效线程状态并取得GIL。PyGILState_Ensure与Release按返回的状态配对,错误路径也必须恢复,以免留下错误的持有状态。

这组便捷API有主解释器等使用前提,不能据此声称任意子解释器都能安全调用;解释器初始化、销毁与线程存活次序也需要管理。在自由线程构建中仍存在附着线程状态要求,不能把“取得状态”简单等同于永远独占解释器。

原生线程调用Ensure不会抢占正在持锁执行的代码,而要等待可获得执行条件;若其他原生调用长期持锁,不能承诺马上获得运行机会。原书PyEval_InitThreads等显式线程初始化接口属于历史版本,现代解释器初始化会管理线程支持,移植时应按目标版本核对API,不能照搬旧条件分支。

进入解释器须匹配线程状态保存独立卡片。

原书依据 · 2 处

15.7 在C扩展模块中释放GIL

耗时的原生计算或阻塞调用可在安全区间暂时离开解释器执行约束,让其他线程继续。但需要把Python对象操作与纯原生工作分开,并确保区间结束时恢复。

释放GIL换并行

传统启用GIL的CPython扩展可用Py_BEGIN_ALLOW_THREADS和Py_END_ALLOW_THREADS包围不需要普通Python C API的原生工作,暂时释放GIL,让其他线程执行;结束时重新获取。适用例子包括对已取得缓冲的计算或阻塞式原生I/O。

区间内不能随意操作Python对象、引用计数或回调Python;原生库自身若非线程安全,仍需要自己的同步。缓冲必须在整个区间有效,内容并发修改也要有约定。控制流必须保证恢复步骤不会被直接return或跳转绕过,再于恢复后翻译错误。自由线程构建中线程状态的分离和重新附着仍有意义,不能把这组宏只理解为所有版本都存在同一把GIL。

释放GIL换并行保存独立卡片。

原书依据 · 1 处

15.8 混合使用C和Python环境中的线程

原生线程调用解释器需要正确的解释器生命周期和线程状态。原书显式初始化线程支持属于Python3.3时代方式;现代版本不能机械照搬这些已变化的入口。

进入解释器须匹配线程状态关联本项背景,实质主要讲解在对应位置。

原书依据 · 2 处

15.9 用Swig来包装C代码

SWIG读取接口声明生成包装代码,定制规则决定哪些C参数组合对应Python输入和输出。生成器减少机械工作,但类型、资源和失败协议仍由接口作者负责。

声明生成器仍需接口策略

SWIG接口的模块声明、编译时包含内容与待包装C声明各有职责。工具生成C包装代码及Python入口,再由编译链生成支撑扩展;公开声明列表可以按需要筛选,不能把整份C库无条件暴露当作唯一做法。

%extend可增加结构体的构造等包装行为,%apply可将int*输出参数映射为Python结果。声明文本并不表达所有内存所有权、长度或错误条件,生成后的接口仍需验证。原书py_modules应使用模块名而不是带.py文件名,历史构建与-py3参数也不作为当前直接运行命令。

声明生成器仍需接口策略保存独立卡片。

原书依据 · 1 处

类型映射绑定转换与释放

typemap把特定C参数模式映射成Python边界转换。例如一个数组对象可同时生成double*与长度;输入规则取得缓冲,freearg规则在完成或失败退出时释放相应视图。$1、$2指匹配的C参数,$input表示Python输入,不应把占位符和真实C类型混淆。

原例检查连续缓冲和double格式,但仍须检查长度转换溢出、空数组、实际维度策略及并发修改。%extend中的malloc也需失败检查及匹配析构。自动化包装不会免除资源转交与异常路径的设计责任。

类型映射绑定转换与释放保存独立卡片。

原书依据 · 1 处

15.10 用Cython来包装C代码

Cython将静态C声明与包装实现分开:pxd描述外部接口,pyx定义Python可见包装和类型化实现。它能减少机械C API代码,但仍须守住底层布局、所有权和类型范围。

Cython折中成本

Cython的pxd保存C声明,pyx保存包装实现,cimport在编译期引入声明,普通import则遵循Python运行期模块语义。包装函数可混合Python对象与C变量,工具生成转换与调用代码,减少手工解析和结果构造。

bint可把C真假结果映射为Python布尔,输出参数可由C局部变量接收后组成Python元组。类型声明不是零成本的全能校验:unsigned包装传给int库函数仍有范围边界,除数也须防零。大型接口应在手工API、自动声明生成与类型化包装之间按维护负担选择。

Cython折中成本保存独立卡片。

原书依据 · 1 处

连续指针不能代替步长视图

double[:]可接受带步长的一维类型化内存视图;取得&a[0]后把它当作普通double*顺序数组,会丢失步长。原例avg因此必须要求连续布局,例如采用恰当的[::1]契约,或复制到连续存储,或改为按视图步长遍历。

还需先检查非空、大小能否放入底层int,以及调用期间缓冲的存活和同步。外部函数声明nogil表示允许在该上下文调用,并不会自动释放GIL;with nogil才建立相应区间,且区间内不能随意执行普通Python对象操作。

连续指针不能代替步长视图保存独立卡片。

原书依据 · 1 处

扩展类型管理原生对象生命周期

不透明Capsule隐藏C结构,扩展类型则能把底层指针保存为字段,并以属性公开x、y。cinit建立原生资源,dealloc回收,distance从类型化实例取得指针进行计算。

结构图:

classDiagram
class Point {
 +__cinit__(double x, double y)
 +__dealloc__()
 +x
 +y
}
class CPoint {
 double x
 double y
}
Point *--> CPoint : 拥有指针指向的分配

CPoint在此只是csample.Point结构的图示别名。示例扩展类缺少malloc失败检查;Capsule版本还需处理创建失败后的释放。析构回调签名及异常规格须与目标Cython版本匹配,不能靠强制函数指针转换掩盖不兼容。

扩展类型管理原生对象生命周期保存独立卡片。

原书依据 · 1 处

15.11 用Cython来高效操作数组

类型化内存视图让数值循环不依赖特定数组库,输出缓冲由调用者提供。优化检查和循环结构之前,先确认形状、别名及浮点特殊值的行为。

数组输出契约包含形状与别名

类型化clip按一维double视图读取输入、写入调用者提供的输出,先验证上下界及长度;二维版本还要逐维验证形状。cpdef提供Python可调用入口和Cython使用的C级入口,数组分配可以留给调用者。

同一数组逐位置读写的演示可以成立,但错位重叠视图可能覆盖尚未读取的元素,不能把任意别名都视为安全原地运算。未初始化输出只有在所有目标元素确实写入后才能使用;nogil并行时还需防止其他线程同时修改同一数据。

数组输出契约包含形状与别名保存独立卡片。

原书依据 · 1 处

关闭检查前证明索引有效

boundscheck(False)去掉索引边界检查,wraparound(False)取消负索引绕回处理;它们并不让越界变得合法。调用者必须证明迭代范围和视图形状满足条件,否则可能从可诊断异常变成内存错误。

示例比较用的手写C循环是n>=0,若n表示元素数就会多处理一次,应为只处理n个元素的范围。因此不能据该不正确基准断言Cython普遍胜过手写C。性能数字还依赖版本、编译器和负载,应结合正确性重新测量。

关闭检查前证明索引有效保存独立卡片。

原书依据 · 1 处

条件改写要保留特殊值行为

把分支改成条件表达式,必须确认全部输入上的结果一致。原clip在NaN输入时两个比较均为假,于是原样写入NaN;改写版本的外层a[i]>min为假,会写入min,行为已经改变。

上下界本身为NaN、正负零和重叠缓冲也可能带来额外差异。不能只看普通有限数值样例就用更快的结果替换原算法;应先定义浮点语义,再做性能比较。

条件改写要保留特殊值行为保存独立卡片。

原书依据 · 1 处

15.12 把函数指针转换为可调用对象

地址变成可调用对象需要完整的函数原型和有效机器码生命周期。CFUNCTYPE提供调用包装,不验证地址真的指向兼容函数。

函数地址需要真实原型与寿命

CFUNCTYPE先以返回类型和参数类型建立C函数原型,再用有效函数地址构造Python可调用对象。声明必须匹配真实ABI、调用约定和类型;错误地址或错误原型可能破坏进程,不能依赖Python类型检查兜底。

从动态库或JIT取得地址后,要保证库句柄、执行引擎及生成代码在所有调用完成前保持有效。加载当前进程后能否找到sin是平台和链接环境的条件,不是普遍保证。原文llvmpy示例只用于说明动态机器码到调用包装的桥梁,不作为当前可安装工具推荐。

函数地址需要真实原型与寿命保存独立卡片。

原书依据 · 1 处

15.13 把以NULL结尾的字符串传给C库

C字符串需要同时约定编码、终止方式、可写性和生命周期。Python文本和任意字节都可能含零字符,而传统C字符串会在第一个零处结束。

字符串边界包含编码和长度

PyArg_ParseTuple的s把Python文本转换成UTF-8的NUL结尾表示,y面向相应只读字节输入;这两种无长度格式会拒绝嵌入零值,防止传统C字符串静默截断。长度感知接口则应显式传递字节数,并与字符数区分。

直接PyBytes_AsString取得的存储虽有结尾零,却仍可能包含中间零。ctypes.c_char_p同样不会自动拒绝这种截断风险。字符编码由C库契约决定,不能因为s采用UTF-8就假定目标库也接受UTF-8。

字符串边界包含编码和长度保存独立卡片。

原书依据 · 1 处

字符串指针须受所有者约束

从Python对象借出的字符指针受对象生命周期约束,不能在原对象销毁后继续保存或擅自写入。UTF-8缓存转换与创建独立bytes结果的分配策略不同,后者用完应释放本层引用;具体内存数字是原书环境结果。

每次编码和取指针都必须检查失败,再调用原生函数。原例漏掉编码失败检查,目标函数的char*也不意味着可以改写Python不可变存储;若库需要可写缓冲,应单独分配。结束后立即减引用只适用于C调用不继续保留地址的情形。

字符串指针须受所有者约束保存独立卡片。

原书依据 · 1 处

15.14 把Unicode字符串传递给C库

向C传文本须按库的契约选择编码字节或宽字符,长度的单位随表示而不同。Python内部按字符范围选择存储宽度,不能把内部地址直接当作任意平台wchar_t数组。

宽字符不等于统一码点数组

UTF-8以字节表达文本,wchar_t则使用平台原生宽字符表示,其宽度和补充平面字符的表示依平台而变。传入C函数的长度必须说明是字节数、宽字符单元数还是Python字符数,不能机械互换;Py_ssize_t转为int前还需范围检查。

PyUnicode_AsWideCharString可创建临时宽字符缓冲,用后按契约PyMem_Free。原例u#和旧Py_UNICODE相关方式已经历版本移除,移植时不能继续照抄;y#也不接受任意可变字节对象,必须满足借用缓冲的条件。旧版使用带#格式还需遵守PY_SSIZE_T_CLEAN等目标版本要求。

宽字符不等于统一码点数组保存独立卡片。

原书依据 · 1 处

编码缓冲与直接字符访问分层

UTF-8编码转换适合库要求char*的情况,显式其他编码可按库约定创建临时存储;独立分配的缓冲必须匹配释放函数。应检查转换失败,不能把临时地址交给会在调用结束后继续保留它的库。

若扩展只是逐字符计算,可通过Python Unicode API读取逻辑码点,而不是先猜测内部存储能否强转成wchar_t。原例kind、data与READ宏依赖CPython具体API和版本,不能当作跨实现的内存布局保证;PyUnicode_READY等历史调用也需要按目标版本核对。书中大小增长属于特定缓存实现的观察。

编码缓冲与直接字符访问分层保存独立卡片。

原书依据 · 1 处

15.15 把C字符串转换到Python中

C返回数据时,首先决定它是原始字节还是已知编码文本,再选构造接口。Python对象复制数据不等于替调用者回收原生来源。

原生字节先确认编码再转文本

未知编码或本质二进制的数据应保留为bytes;已知UTF-8或其他编码时,再用明确的解码接口构造str。errors策略决定无效序列被拒绝、忽略或替换,ignore会丢失信息,不能当作无损转换。

使用指针和准确长度能保留嵌入零值,避免依赖NUL终止。由相应API创建的Python字节或字符串对象取得自身内容,原C缓冲仍按原所有权协议释放,且构造失败同样要清理。宽字符输入应通过适配平台表示的Unicode接口转换;历史u#示例不作为当前通用方案。

原生字节先确认编码再转文本保存独立卡片。

原书依据 · 1 处

15.16 同编码方式不确定的C字符串打交道

surrogateescape把不能按指定编码解码的高位字节暂存为特定低代理码点,再按相同编码和错误策略恢复字节。它是往返保真机制,不是识别真实编码或生成标准Unicode交换文本。

代理转义保留未知字节

surrogateescape把解码失败的0x80到0xFF字节映射到U+DC80到U+DCFF,之后以相同编码和surrogateescape编码可恢复原字节。因此可以在无法控制编码却不能丢数据的边界上,实现C字节与Python字符串往返。

这些独立代理码点不是正常的Unicode标量值,外部系统未必接受;严格编码可能失败,输出是否报错还取决于流的错误策略。它不会推断正确编码,若中途做了丢失信息的转换也不能保证往返。strict会拒绝无效数据,原文把它和ignore、replace都归为破坏内容不准确;replace对解码通常产生替换字符,也不是固定问号。

代理转义保留未知字节保存独立卡片。

原书依据 · 1 处

15.17 把文件名传给C扩展模块

文件名转换应与解释器使用的文件系统编码和错误策略一致。通用UTF-8文本转换未必等于系统路径契约,尤其涉及不可解码字节时。

文件名使用系统转换协议

PyUnicode_FSConverter可在参数解析的O&转换中取得文件系统编码的bytes,使用后释放所得对象;EncodeFSDefault与DecodeFSDefaultAndSize用于相应方向的转换。这样可与解释器的系统路径编码及错误处理保持一致,而非随意以普通文本编码替代。

取得字节后仍需检查失败、准确长度和嵌入NUL等目标库约束。系统路径是否接受bytes、是否应使用宽字符接口依平台及具体C库而定,不能把一种char*包装当作所有平台唯一形式。转换解决表示问题,不证明路径存在、可信或被允许访问。

文件名使用系统转换协议保存独立卡片。

原书依据 · 1 处

15.18 把打开的文件传给C扩展模块

文件描述符把Python流接到系统I/O,但两个层次可能各有缓冲和关闭动作。传递描述符前要明确共享偏移、缓冲一致性和谁拥有关闭权。

描述符共享需要明确关闭权

PyObject_AsFileDescriptor接受合适对象并取得其文件描述符,失败返回负值;有fileno的方法对象不一定都提供可用、适合目标操作的描述符。Python流包装与C系统调用共享同一个底层打开状态时,需要协调缓冲与位置,单纯刷新输出并不能消除所有读缓冲问题。

PyFile_FromFd可把已有描述符包装成Python流,closefd参数决定关闭包装时是否关闭描述符;它不自动复制出完全独立的文件位置。若C再用fdopen建立FILE*,就增加一层缓冲和关闭责任。借用的一方不能擅自关闭,拥有的一方要保证只关闭一次。

描述符共享需要明确关闭权保存独立卡片。

原书依据 · 1 处

15.19 在C中读取文件型对象

一般文件型对象不一定拥有文件描述符,扩展可通过Python C API调用read或write协议。调用结果的文本/字节契约、EOF和失败清理须逐步核对。

文件型协议不依赖真实文件

扩展取得对象read方法,反复通过PyObject_Call请求一块内容,就能处理StringIO等没有系统文件描述符的对象。文本read返回str,需要编码后才交给面向字节的C接口;二进制read返回bytes,不能再套用Unicode编码函数。

空结果表示这个阻塞读取协议的EOF,异常则通过NULL传播。应先检查返回类型及长度查询是否失败,再处理数据;非阻塞对象的None等结果不能当普通EOF。写入文件型对象同理,应按目标接口传递文本或字节,而非强求底层系统文件。

文件型协议不依赖真实文件保存独立卡片。

原书依据 · 1 处

原生循环清理覆盖每条失败路径

read方法、参数元组、每块数据及编码结果都有引用生命周期。构造参数失败后不能继续调用;调用或转换失败时要释放已拥有资源并保留异常。PySequence_Length返回-1也需要处理,不能把它当作非空结果继续走。

原例write直接写描述符1,没有处理短写和系统调用失败,也可能与Python输出缓冲交错;取得内容成功不等于已完整输出。应按实际返回值推进写入并处理错误,资源清理与业务完成状态分别保证。

原生循环清理覆盖每条失败路径保存独立卡片。

原书依据 · 1 处

15.20 从C中访问可迭代对象

C侧通过迭代协议获取对象和元素,避免依赖具体容器。迭代结束与迭代失败都可能返回NULL,因此循环结束后还要检查异常状态。

迭代结束与失败共享空指针

PyObject_GetIter取得迭代器,PyIter_Next逐个返回新引用,使用后逐一减引用,最后释放迭代器。这样列表、文件和生成器可共用同一消费逻辑。

PyIter_Next返回NULL既可能是正常耗尽,也可能是迭代中抛出异常,必须再检查PyErr_Occurred并相应返回失败。原例直接构造None结果,漏掉这个区分,会留下错误状态与成功返回不一致。元素处理本身失败也应走资源清理路径,不能继续消费而掩盖原错误。

迭代结束与失败共享空指针保存独立卡片。

原书依据 · 1 处

15.21 排查段错误

原生扩展损坏进程时,普通Python异常处理未必有机会运行。faulthandler提供尽可能保留下来的调用栈线索,帮助把崩溃与Python调用入口对应起来。

致命崩溃也需调用现场

faulthandler可预先启用致命故障诊断,在段错误等情况下尽力输出调用栈,帮助找到进入有问题扩展的Python路径;也可通过解释器选项或环境配置开启。它提供排查线索,不修复已经损坏的内存,也不能保证每次崩溃都有完整输出。

原书仅讨论Python栈,并把C栈说成完全不可获得;现代Python已增加有平台和构建条件的C栈转储能力,因此旧限制必须按版本理解。定位原生内存错误仍可能需要C调试器等工具。诊断输出目标须在使用期保持有效,不能关闭后让描述符被其他文件复用。

致命崩溃也需调用现场保存独立卡片。

原书依据 · 1 处

附录A 补充阅读

附录提供查证路线:版本文档回答接口语义,设计提案解释动机,案例和书目补充场景。历史数量与推荐版次应作为出版背景,不当作当前资源排名或可用性证明。

A.1 在线资源

语言文档适合查接口和语义,PEP适合追踪设计动机与变化,讲座和问答适合寻找案例。不同资源的责任和证据强度不同,应带着版本与具体问题使用。

语言文档与设计提案各有用途

核对语言或库的具体语义,应查对应版本的文档;追问某项特性为什么这样设计,则可进一步读PEP中的动机、取舍和演变。设计提案的状态与最终实现可能不同,因此不能只凭提案段落断言当前行为。

讲座、配方和问答能提供使用场景与排错线索,但质量、版本和运行前提各异,应回到接口文档与可验证的代码。原附录的问题数、视频时新程度和配方数量是出版时描述,不作为今天的资源规模或优劣排名。

语言文档与设计提案各有用途保存独立卡片。

原书依据 · 1 处

A.2 学习Python的图书

这一节列出Python入门读物及出版版本,供读者补充语言基础。它没有展开这些书的知识内容,因此保留引用清单,不据标题重建书中观点。

A.3 高级图书

高级书目覆盖应用编程、语言参考、标准库、面向对象和版本迁移,作用是标记可进一步查找的阅读方向。这里未展开具体方案,也未验证这些版本的当前适用性。

封面说明

封面说明是一段独立自然史材料。跳兔的运动与洞居生活可以结合形态理解,但其俗名不决定生物分类,原文关于唯一成员与地理范围的旧概括也需要校正。它不承担全书软件设计论证的作用。

跳兔形态服务跳跃与洞居

跳兔属于啮齿类,外观近似兔或袋鼠并不意味着属于兔类或有袋类。强壮后肢用于跳跃,长尾参与平衡;夜间在地面觅食,白天主要利用自行挖掘的洞穴。前肢、耳部及身体结构与挖掘和活动方式相联系,说明形态应结合行为理解。

封面文字还描述繁殖、体型和食性,属于该书附带的自然史材料,不用于推导软件设计。原文称跳兔科只有唯一成员,并把东非、南非描述合并;现行分类区分南非与东非跳兔,故不把这些范围或数值推广到所有跳兔。核验资料:ASM分类资料、2016南非保育评估。

跳兔形态服务跳跃与洞居保存独立卡片。

原书依据 · 1 处

跨章综合

生成器、上下文管理器和消息队列都涉及“工作什么时候继续”,但分别管理执行位置、资源范围和任务交接。惰性管道若依赖已关闭的文件,会把迭代协议和资源生命周期的错误组合暴露出来;完成队列任务也不能代替关闭线程。

文本、序列化、网络和C扩展共同要求说明数据表示。长度是字节、字符还是元素,边界由分隔符、显式长度还是EOF确定,这些约定若不一致,会从解析错误升级成截断或越界。编码转换只解决表示,无法替代业务校验、身份认证和所有权设计。

描述符、装饰器和元类分别让规则集中在属性、调用与类创建时点。集中规则有助复用,也可能隐藏副作用;测试应在规则实际被查找和执行的位置观察结果。剖析则帮助判断这种抽象成本是否值得处理,不能用历史微基准推翻必要契约。

从容器快照到C指针,所有权一直贯穿全书:谁可以修改、谁必须保活、谁负责释放、失败后谁还能继续。明确这些责任,比记住某个API名字更能把配方迁移到现实程序。

发散与实践

读者延伸采用两条路径:先以固定版本CPython队列实现及官方测试深读“取出、完成、退出”的区别,再把本书已经定位的版本差异整理成有限的迁移清单。前者已完成首轮公开源码阅读和机制映射,后者已有原文与官方核验材料;后续都不代表已经执行测试或完成程序迁移。

  • ideas/idea-001-追踪队列完成协议.md:实现深读,含90分钟快速路线、详细单元、首轮映射及完成判据。
  • ideas/idea-002-建立旧配方迁移清单.md:真实任务计划,只整理本书四组差异,避免批量迁移无关历史资料。

筛选已结束:网络服务、原生扩展编译、性能跑分都需具体运行对象与环境,本轮没有足够必要性另做实验;纯提名项目和封面自然史不硬凑实践。优先从队列完成协议阅读开始,如未来确有旧配方使用需求,再执行迁移清单任务。

生成进度与管理记录

Python Cookbook(第3版)中文版

整体评级

四象限结论:工程实践(高浓度 + 低稳定性)

理由:本书每个主题都按“问题、解决方案、讨论”组织,不只是罗列 API,还会解释方案为什么能工作,例如数据结构章节会比较 heapq 与全量排序的适用条件,迭代器章节围绕迭代协议、生成器和管道组织数据流,并发章节讨论线程通信、死锁、GIL 与 Actor 模式。这些内容信息浓度较高,能迁移到日常工程判断中。稳定性方面,它又强绑定 Python 3.3 时代的标准库、语法和第三方库用法,部分建议会随语言版本演进而变化,因此整体落在“工程实践”,不是纯经典原理。

历史章节筛选

  • 第1章 数据结构和算法:精读。内置容器、堆、队列、排序、分组等主题可迁移到日常数据处理与算法建模。
  • 第2章 字符串和文本:精读。正则、Unicode、清洗、解析器都是文本处理的长期核心问题。
  • 第3章 数字、日期和时间:精读。精确数值、NaN、时区等问题背后有稳定工程约束。
  • 第4章 迭代器和生成器:精读。迭代协议和生成器管道体现 Python 数据流抽象的底层思想。
  • 第5章 文件和I/O:精读。编码、二进制缓冲、内存映射和路径处理直接影响系统边界设计。
  • 第6章 数据编码与处理:精读。CSV/JSON/XML/二进制记录涉及外部数据契约与流式处理。
  • 第7章 函数:精读。参数、闭包、回调和注解构成 Python 抽象能力的关键基础。
  • 第8章 类与对象:精读。特殊方法、属性、描述符、继承和内存布局是对象模型核心。
  • 第9章 元编程:精读。装饰器、签名、元类和代码生成体现“用代码组织代码”的设计取舍。
  • 第10章 模块和包:精读。包结构、导入边界和 import hook 关系到大型项目组织方式。
  • 第11章 网络和Web编程:精读。客户端、服务端、RPC 和事件驱动 I/O 都是分布式程序的基础模式。
  • 第12章 并发:精读。线程通信、锁、GIL、Actor 和生成器任务体现并发可靠性的关键权衡。
  • 第13章 实用脚本和系统管理:精读。命令行、管道、配置和日志支撑自动化脚本的工程边界。
  • 第14章 测试、调试以及异常:精读。测试隔离、异常因果、告警与性能分析是长期稳定的工程实践。
  • 第15章 C语言扩展:精读。Python/C 边界、GIL、C API 与 Cython 适合沉淀跨语言集成经验。
  • 附录A 补充阅读:略读。主要是延伸资源列表,不适合生成独立卡片。

历史章节进度追踪

章节号 章节标题 精读/略读 状态 卡片数
01 第1章 数据结构和算法 精读 done 3
02 第2章 字符串和文本 精读 done 3
03 第3章 数字、日期和时间 精读 done 2
04 第4章 迭代器和生成器 精读 done 3
05 第5章 文件和I/O 精读 done 3
06 第6章 数据编码与处理 精读 done 3
07 第7章 函数 精读 done 3
08 第8章 类与对象 精读 done 4
09 第9章 元编程 精读 done 4
10 第10章 模块和包 精读 done 3
11 第11章 网络和Web编程 精读 done 3
12 第12章 并发 精读 done 5
13 第13章 实用脚本和系统管理 精读 done 2
14 第14章 测试、调试以及异常 精读 done 4
15 第15章 C语言扩展 精读 done 4
A 附录A 补充阅读 略读 done 0

2026-10-27 当前P3恢复

执行模式:light

本次实际使用规则:book-workflow v4 / book-notes v23;原概览未记录首次Skill版本,不回填。

内容形态:问题思考型。260条反复按问题、解决方案、讨论组织;操作性语法按实际用途保留,概念机制不能只用API列表替代。

建档进度:done

实践候选筛选:pending

章节进度追踪表

章节号 章节标题 状态 卡片数
0 前言 done 0
1 第1章 数据结构和算法 done 27
2 第2章 字符串和文本 done 41
3 第3章 数字、日期和时间 done 26
4 第4章 迭代器和生成器 done 20
5 第5章 文件和I/O done 31
6 第6章 数据编码与处理 done 30
7 第7章 函数 done 19
8 第8章 类与对象 done 53
9 第9章 元编程 done 44
10 第10章 模块和包 done 26
11 第11章 网络和Web编程 done 40
12 第12章 并发 done 44
13 第13章 实用脚本和系统管理 done 19
14 第14章 测试、调试以及异常 done 16
15 第15章 C语言扩展 done 38
16 附录A 补充阅读 done 1
17 封面说明 done 1
非正文排除
spine项 类型 排除理由
1 封面 已实际查看封面确认身份,SVG图片无正文论述
2 纯目录 仅层次与导航,不代替正文阅读
3 版权信息 完整读用于身份,无技术论述
4 版权声明 完整读取授权声明,无知识解释
5 内容提要 完整读取范围简介,实质在各章展开
6 出版社宣传 完整读取机构介绍及赞誉,无独立技术论述
7 作者介绍 完整读取身份与作品提名,用于出版信息和引用登记
26 社区营销 完整读取活动/购书/联络宣传并实际查看图,不作当前产品事实
待关联术语
术语名 出现章节 一句话语境
Stack Overflow 16 原附录问答案例入口,质量需按具体答案核对。
ActiveState Python Recipes 16 原附录配方案例入口,未核定当前规模。
PyVideo 16 原附录演讲资源入口,未核定当前内容。
PEP 16 语言增强提案,用于查设计动机与状态。
AMQP spine20/12.10 跨进程消息基础设施协议提名,未展开。
ThreadingMixIn spine16/8.18 socketserver为服务器添加线程行为的mixin,后续网络章展开。
contextmanager spine15/7.11 标准库用yield连接上下文入口与出口的机制指引,后章另展开。
placement new spine14/6.12 译注类比,不说明Python实际调用C++placement new。
RTS-CTS spine13/5.20 仅点名硬件握手选项,没有展开电气时序。
pack_into spine13/5.9 仅举向既有缓冲打包接口,格式细节未展开。
recv_into spine13/5.9 仅举直接填充既有缓冲的接口,未展开网络契约。
ssl.RAND_bytes spine11/3.11 原书密码随机方向的API提名,本轮未采用。
fpectl spine11/3.7 原书平台相关专家模块提名,当前可用性未核验,不作为依赖。
ast模块 spine10/2.19 Python语法树方向,仅进一步研究提示。
string.Template spine10/2.15 简易模板对象替代方向,原文只对照substitute用法,不扩写完整模板安全策略。
glob spine10/2.3 路径匹配工具方向,具体用法留5.13。
slots spine9/1.18 用于频繁修改属性的替代方向,仅引到8.4,未在此展开。
可哈希性(hashable) spine9/1.10 作为集合判定键的前提已在去重卡说明,未展开完整对象协议。
collections spine9 章前提及补充容器模块,deque能力在1.3实际展开。
引用文献
标题 类型 出现章节 一句话语境
Porting to Python 3 书 16 Lennart Regebro,CreateSpace,2011;附录迁移参考。
Python 3 Object Oriented Programming 书 16 Dusty Phillips,Packt,2010;附录面向对象参考。
The Python Standard Library by Example 书 16 Doug Hellmann,Addison-Wesley,2011;附录标准库参考。
Core Python Applications Programming, 3rd Edition 书 16 Wesley Chun,Prentice Hall,2012;附录应用编程参考。
Python Essential Reference, 4th Edition 书 16 David Beazley,Addison-Wesley,2009;附录语言参考。
Programming Python, 4th Edition 书 16 Mark Lutz,O’Reilly,2010;附录高级参考。
Programming in Python 3, 2nd Edition 书 16 Mark Summerfield,Addison-Wesley,2010;附录入门参考。
Beginning Python: From Novice to Professional, 2nd Edition 书 16 Magnus Lie Hetland,Apress,2008;附录入门参考。
Python Programming for the Absolute Beginner, 3rd Edition 书 16 Michael Dawson,Course Technology PTR,2010;附录入门参考。
The Quick Python Book, 2nd Edition 书 16 Vernon Ceder,Manning,2010;附录入门参考。
Learning Python, 4th Edition 书 16 Mark Lutz,O’Reilly,2009;附录入门参考。
PEP 383 论文 15 系统接口中不可解码字节的代理转义与无损往返。
PEP 393 论文 15 Python灵活字符串表示的背景,非任意C库通用布局。
llvmpy 源码项目 15 原书LLVM绑定演示,未核定其当前维护或可用性。
PEP 3118 论文 15 缓冲接口与多维、步长等数组布局的进一步阅读。
SWIG 源码项目 15 从声明生成包装并以typemap定制转换的工具。
CFFI 源码项目 15 ctypes之外的互操作参考,原书是否纳入标准库的猜测不作为事实。
LLVM 源码项目 14 原书编译工具链提名,未展开。
Numba 源码项目 14 选择性编译函数的延伸参考,未采用历史支持状态作当前结论。
PyPy 源码项目 14 原书JIT进一步阅读;Python3支持描述属于历史背景。
pexpect 源码项目 13 处理依赖终端交互程序的进一步参考,未实际使用。
Advanced Programming in the UNIX Environment, 2nd Edition 书 12 W. Richard Stevens、Stephen A. Rago,2005;本章守护进程的延伸参考。
Stackless Python 源码项目 12 本章进一步阅读,未展开其实现。
greenlet 源码项目 12 本章进一步阅读,未展开其实现。
gevent 源码项目 12 本章进一步阅读,未作为当前选型建议。
A Curious Course On Coroutines and Concurrency 论文 12 David Beazley 2009年协程教程,仅登记本章引用。
PEP 3156 论文 12 异步I/O框架设计的进一步阅读。
PEP 342 论文 12 生成器增强为协程的背景参考。
PEP 380 论文 12 yield from 的委派机制参考;本章以 readline 返回字节串说明。
Unix Network Programming 书 spine19/11.11 W. Richard Stevens高级UNIX网络与描述符传递阅读指引,未全文读取。
RFC 2104 论文 spine19/11.9 HMAC机制规范引用,未全文阅读。
Celery 源码项目 spine19/11.7 任务/消息框架提名,未展开实现。
ZeroMQ 源码项目 spine19/11.7 消息传递库提名,未展开其协议。
Paste 源码项目 spine19/11.5 WSGI支持库进一步阅读,未核验当前维护状态。
WebOb 源码项目 spine19/11.5 更高层请求响应封装进一步阅读,未完整阅读。
PEP 3333 论文 spine19/11.5 WSGI调用规范引用,未全文阅读。
httpbin 源码项目 spine19/11.1 HTTP请求回显测试服务引用,未向其发送本任务数据。
Requests 源码项目 spine19/11.1 HTTP客户端库,官方quickstart核验JSON调用和响应处理,未完整源码阅读。
PEP 405 论文 spine18/10.14 虚拟环境机制规范进一步阅读,未全文读取。
PEP 369 论文 spine18/10.12 本书记载撤回的导入后钩子提案背景,当前实现需依现代导入协议。
PEP 302 论文 spine18/10.11 旧导入钩子协议规范引用,现代API另查官方文档,未完整读取PEP。
PEP 420 论文 spine18/10.5 隐式命名空间包规范进一步阅读,未完整读取。
PEP 328 论文 spine18/10.3 显式相对导入规范进一步阅读,未全文读取。
Decorator for Binding Constants at Compile Time 论文 spine17/9.24 ActiveState原字节码改写示例灵感,未访问全文。
Five-Minute Multimethods in Python 论文 spine17/9.20 Guido van Rossum多分派讨论进一步阅读,未全文阅读。
PEP 422 论文 spine17/9.19 本书当时未采纳的类定制提案背景,未核验其最新状态,不据此推荐接口。
PEP 3115 论文 spine17/9.18 元类命名空间准备规范进一步阅读,未全文阅读。
PEP 362 论文 spine17/9.7 函数签名对象规范进一步阅读,未全文阅读。
Design Patterns: Elements of Reusable Object-Oriented Software 书 spine16/8.19 状态模式来源引用,未读取全书。
Python’s super() considered Super! 论文 spine16/8.7 Raymond Hettinger文章进一步阅读,未完整读取。
Twisted 源码项目 spine15/7.11 内联回调类比提名,未阅读其实现。
Python for Data Analysis 书 spine14/6.13 Wes McKinney著,进一步阅读Pandas分析,未读取全书。
ctypes 源码项目 spine14/6.12 数据结构/嵌套实现进一步阅读,后续C扩展章节另展开。
SQLAlchemy 源码项目 spine14/6.8 ORM更高层接口提名,未展开映射和会话机制。
PEP 249 论文 spine14/6.8 Python DB-API规范引用,未全文阅读。
lxml 源码项目 spine14/6.3 ElementTree相近API的XML库,原文展开XPath/XSLT/验证能力而留延伸卡。
Pandas 源码项目 spine14/6.1 DataFrame与read_csv分析指引,实质示例在6.13。
HDF5 源码项目 spine13/5.21 大型数组格式进一步阅读,当前条目未展开实现。
pySerial 源码项目 spine13/5.20 串口通信封装,官方API核验参数与二进制接口,未完整阅读实现。
Generator Tricks for Systems Programmers 论文 spine12/4.13 David Beazley生成器教程进一步阅读,未访问完整材料。
IEEE 754 论文 spine11/3.7 特殊浮点数进一步规范参考,未读标准全文。
PyParsing 框架 spine10/2.18 高级分词/解析方向,仅提名。
Python Format Specification Mini-Language 论文 spine10/2.13 进一步格式规格文档,当前只使用原书展开部分。
Unicode Normalization FAQ 论文 spine10/2.9 已为规范与兼容形式边界读取官方FAQ相关段落,不宣称读完全部标准。
Pragmatic Unicode(Ned Batchelder) 论文 spine10/2.9 原书Unicode进一步阅读入口,未读该文章全文。
PLY 源码项目 spine7 作者介绍纯提名,未展开。

| python-cookbook示例仓库 | 源码项目 | spine8 | 前言给出github.com/dabeaz/python-cookbook,后续研究须核验固定版本。 |

资金安全问题案例
问题标题 问题卡 解决方案卡(如有) 出现章节 一句话说明

整书笔记为本轮阅读正文真源,已完成。

本轮实践卡进度

序号 实践标题 实践方式 状态 关联章节 产出
1 追踪队列完成协议 实现深读 done 12.3、14章 ideas/idea-001-追踪队列完成协议.md;固定版本首轮源码与映射
2 建立旧配方迁移清单 真实任务 done 前言、10/11/15章 ideas/idea-002-建立旧配方迁移清单.md;计划及现有核验材料

实践候选筛选:done

两张卡均为生成交付;线程测试、原生代码编译、应用迁移与性能实验未执行。取舍及优先顺序见整书笔记实践节。

2026-10-27 本轮阶段2交接

本次执行book-workflow v4 / book-notes v23,light;历史首次版本缺失不回填。18项实质正文spine、281逻辑单元及332阅读片段完整读取,8项非正文按类型排除,11种图已查看。476知识卡(49历史文件保留、427新),476唯一primary、494位置引用与494核验来源;结构图64、问题卡372、普通读书笔记34、操作参考3、延伸参考3。两张实践计划交付:实现深读1、真实任务1,现实执行未开展。

整书导读、章节讲解、跨章综合和实践节已收束;附录书目已登记。生成后的笔记复核、独立审查及审查结果优化未执行。阶段2放行,阶段3 skipped;生产导入对账通过,476/476归档完成,pending软链0。

相关主题

从本书的主题进入跨书阅读,对照其他书籍的讲解。下方数量包含主题关联的全部卡片与书籍。

暂无公开主题。