此笔记位置已失效,请从目录继续阅读。
全书导读
本书面向已有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时返回的是一个三元组;调用方可接收整体,也可按预期结构解包。逗号构造元组,括号主要用于分组,空元组等语法仍另有规则。
解包是结构契约保存独立卡片。
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;它也会添加缺失键,且默认表达式每次调用都会先求值。
按字段收集所有记录时,可逐项追加到对应键的列表,不必先排序;这种方式便于以后按键随机访问,但会保存完整分组,需考虑输入规模。
多值字典用容器保存值保存独立卡片。
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使用,但不会替程序验证字段长度或内容格式。
本章脚注把平面文件用于描述没有关系结构的记录文件;命名切片适用于已知固定字段范围,不能由这一文件名就推定所有记录都等宽。
切片名称显露固定字段含义保存独立卡片。
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自己实现大小比较。
排序键显露记录的比较字段保存独立卡片。
1.14 对不原生支持比较操作的对象排序
对象不必定义所有实例的自然次序,也可在当前操作中用属性提取器提供排序键。attrgetter对应属性访问,itemgetter对应取项;二者以相同key接口服务不同记录形式。
排序键显露记录的比较字段关联本项背景,实质主要讲解在对应位置。
1.15 根据字段将记录分组
groupby分的是相邻且键相同的一段段记录;若要同一键的全部记录归在一起,先让它们连续,常见办法是按相同key排序。若需要随时按键随机访问全部组,则容器聚合更合适,但需要保存相应数据。
多值字典用容器保存值关联本项背景,实质主要讲解在对应位置。
连续分组须先对齐键顺序
要让同一键的全部记录在一组迭代,先使它们连续,例如按目标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还能用来进入或离开局部层次。章末脚注补充数据术语,其中可哈希性的解释需纠正。
切片名称显露固定字段含义关联本项背景,实质主要讲解在对应位置。
链式映射分离查找与写入层
要把多份映射逻辑上当成一个查找范围,可用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.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,把不能编码的字符写成数字字符引用,例如ñ可表达为ñ。输出先是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思路在文本对齐部分已有主要讲解。
对齐格式应显式指定方向宽度关联本项背景,实质主要讲解在对应位置。
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个下标继续到结束,不是只取前三项。
迭代切片会推进底层来源保存独立卡片。
4.8 跳过可迭代对象中的前一部分元素
按条件跳过开头,与在全流中过滤有不同语义。dropwhile第一次遇到假条件后就停止筛选,之后全部保留;已知数量则可用islice从某位置一直到结束。
迭代切片会推进底层来源关联本项背景,实质主要讲解在对应位置。
跳过前缀不同于全流过滤
要丢掉满足条件的开头一段,可用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序列化接口衔接。
打印分隔符不等于序列化格式保存独立卡片。
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保留属性协议比直接写字典更通用,但它不代替验证,也不保证每个中间状态可用。
对象重建须验证字段与不变量保存独立卡片。
数据展示与传输表示应分开
检查深层对象可用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后的逗号会把多个值组合为一个元组,调用方可以接收整体或按结构解包。这个结果契约与第一章的解包规则相衔接,而非函数真实返回多条独立通道。
解包是结构契约关联本项背景,实质主要讲解在对应位置。
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。这样能提供重置、清缓存等入口,同时把直接访问改为受控操作。函数属性不是自动绑定方法,参数与状态约定由这些函数自己定义;它也不把隐藏环境变成不可突破的安全隔离。
装饰器可把访问函数附到包装器,供运行时调整闭包配置;外层复制这个函数引用后仍操作原闭包,区别于复制普通配置值后修改外层属性。
闭包可通过访问函数暴露状态保存独立卡片。
闭包模拟实例仍须满足特殊协议
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可预置常用类型。它与共享描述符都能减少重复,选择取决于需要的复用与接口。
重复属性验证宜抽取机制保存独立卡片。
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。
属性代理须保留自身存储路径保存独立卡片。
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 委托属性的访问
委托用持有对象实现操作转交,选择性暴露能力而不建立继承关系。缺失属性的回退委托可减少样板,但已有属性及特殊操作走不同查找路径,透明代理需要逐项定义协议。
属性代理须保留自身存储路径关联本项背景,实质主要讲解在对应位置。
委托通过持有关系复用行为
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,调用者随即承担建立完整有效状态的责任。反序列化场景尤其要验证输入字段,不把对象存在等同于对象可用。
对象重建须验证字段与不变量关联本项背景,实质主要讲解在对应位置。
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 清理仍需独立设计。
生成器返回值须由驱动器接收保存独立卡片。
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在缓存命中时直接返回,可跳过整个普通创建与初始化路径;但示例只支持可哈希位置参数,弱值回收和并发竞态仍需按身份契约处理。
缓存命中应避免重复初始化保存独立卡片。
缓存管理器分离复用策略
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可复制入口引用,因此仍触及原来的共享状态;直接改外层同名普通属性则未必影响内层。
闭包可通过访问函数暴露状态关联本项背景,实质主要讲解在对应位置。
包装器配置通过访问函数修改
把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控制。拦截这一步可以拒绝普通构造、返回已有单例或按键复用实例;缓存命中时不再进入普通创建链,但唯一性的范围需要定义。
缓存命中应避免重复初始化关联本项背景,实质主要讲解在对应位置。
元类调用控制普通实例创建
元类重写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转义和数据库类型映射分别处理。
打印分隔符不等于序列化格式关联本项背景,实质主要讲解在对应位置。
类命名空间可在执行前定制
元类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阶段创建。字段名冲突、重复和额外实例字典等限制并未因此自动消除。
元组工厂仍须验证字段定义保存独立卡片。
9.19 在定义的时候初始化类成员
类定义时安装字段访问器只需对每个新类型做一次,实例分配则在之后每次调用时发生。元组等不可变内容要在new阶段构造,init已经无法重写这些元素。
元组工厂仍须验证字段定义关联本项背景,实质主要讲解在对应位置。
类初始化与实例初始化分时发生
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,每次保存自己的字段名和预期类型。这样抽取重复代码而仍保留属性接口,和可复用描述符是两种相关表达方式。
重复属性验证宜抽取机制关联本项背景,实质主要讲解在对应位置。
属性工厂用闭包保存字段配置
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并行关联本项背景,实质主要讲解在对应位置。
线程停止需协作
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并行保存独立卡片。
并行方案先评估计算与传输成本
性能瓶颈先定位,再比较算法改进、适合的原生库、独立进程或其他解释器;线程数增加不是唯一途径。进程池能让独立解释器利用多核,但任务过小、序列化过大或状态耦合会抵消收益。原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 调度则把任务挂到文件描述符的等待表,就绪后恢复。三者共享暂停和恢复机制,但需要分别管理任务生存期、异常和资源。
生成器返回值须由驱动器接收关联本项背景,实质主要讲解在对应位置。
协作任务只在让出时切换
协作调度器从双端队列取出一个生成器,以 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 本身会失败。
异常链保留因果保存独立卡片。
14.10 重新抛出上一个异常
异常处理可以增加诊断或清理,而不改变原失败。裸 raise 重新传播当前处理的异常;转换为不同异常时才需要另外选择显式因果链。
异常链保留因果关联本项背景,实质主要讲解在对应位置。
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支持判断属于写作时代背景,不作为今天的可用性判断。
先剖析再优化保存独立卡片。
计时范围必须包含失败策略
上下文计时器把结束读数放在 finally,能在代码块异常退出时也记录经过时间。普通装饰器若在被调函数返回后才取结束时间,异常会绕过记录;两种写法测得的事件集合因此不同。
比较时还须明确重复次数、准备开销和输出开销是否计入。timeit 的返回通常是整批运行的总耗时,要换算单次成本需使用相应次数。测量代码不能吞掉原异常或改变被测结果;耗时记录和业务成功应分别表达。
计时范围必须包含失败策略保存独立卡片。
原书依据 · 1 处
14.14 让你的程序运行得更快
优化应先验证正确性、量出热点,再考虑算法、数据移动和频繁查找的成本。局部缓存和减少包装是有条件的手段,不能为了历史微基准牺牲语义和必要约束。
先剖析再优化关联本项背景,实质主要讲解在对应位置。
热点优化先看算法与数据
先确认算法和工作量,再减少热路径中不必要的构造与复制。内建容器常有高效实现;删除仅用于中转的列表,可以降低分配和遍历开销。但容器选择仍要满足所需操作复杂度,不能认为任意内建类型都优于一切专用结构。
减少 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,不能照搬旧条件分支。
进入解释器须匹配线程状态保存独立卡片。
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时代方式;现代版本不能机械照搬这些已变化的入口。
进入解释器须匹配线程状态关联本项背景,实质主要讲解在对应位置。
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:真实任务计划,只整理本书四组差异,避免批量迁移无关历史资料。
筛选已结束:网络服务、原生扩展编译、性能跑分都需具体运行对象与环境,本轮没有足够必要性另做实验;纯提名项目和封面自然史不硬凑实践。优先从队列完成协议阅读开始,如未来确有旧配方使用需求,再执行迁移清单任务。