├── LICENSE ├── README.md └── zh_CN ├── 1-using-variables-well.md ├── 10-a-good-player-know-the-rules.md ├── 11-three-tips-on-writing-file-related-codes.md ├── 12-write-solid-python-codes-part-1.md ├── 13-write-solid-python-codes-part-2.md ├── 14-write-solid-python-codes-part-3.md ├── 15-thinking-in-edge-cases.md ├── 16-stmt-expr-and-walrus-operator.md ├── 2-if-else-block-secrets.md ├── 3-tips-on-numbers-and-strings.md ├── 4-mastering-container-types.md ├── 5-function-returning-tips.md ├── 6-three-rituals-of-exceptions-handling.md ├── 7-two-tips-on-loop-writing.md ├── 8-tips-on-decorators.md └── 9-a-story-on-cyclic-imports.md /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 《Python 工匠》图书首页上线啦！共有 3 章在线内容，欢迎阅读。 2 | 3 | - [图书首页](https://www.piglei.com/book/) 4 | - [第 1 章 变量与注释](https://www.piglei.com/book/ch01_variables.html) 5 | - [第 6 章 循环与可迭代对象](https://www.piglei.com/book/ch06_loop.html) 6 | - [第 10 章 面向对象设计原则](https://www.piglei.com/book/ch10_solid_p1.html) 7 | 8 | 图书《Python 工匠：案例、技巧与工程实践》现已正式上市。同开源文章相比，图书的知识结构更为流畅，增加了“函数”“面向对象编程”等核心章节，**总内容量几乎翻倍**，欢迎购买。 9 | 10 | 11 | 12 | [点击购买](https://item.jd.com/13068111.html) | [豆瓣书评](https://book.douban.com/subject/35723705/) | [图灵社区](https://www.ituring.com.cn/book/3007) 13 | 14 | --- 15 | 16 | ## 『Python 工匠』是什么？ 17 | 18 | 我一直觉得编程某种意义上是一门『手艺』，因为优雅而高效的代码，就如同完美的手工艺品一样让人赏心悦目。 19 | 20 | 在雕琢代码的过程中，有大工程：比如应该用什么架构、哪种设计模式。也有更多的小细节，比如何时使用异常（Exceptions）、或怎么给变量起名。那些真正优秀的代码，正是由无数优秀的细节造就的。 21 | 22 | 『Python 工匠』这个系列文章，是我的一次小小尝试。它专注于分享 Python 编程中的一些偏 **『小』** 的东西。希望能够帮到每一位编程路上的匠人。 23 | 24 | ## 文章列表 25 | 26 | - 1\. 善用变量改善代码质量 [[图书版：变量与注释](https://www.piglei.com/book/ch01_variables.html)] 27 | - [2. 编写条件分支代码的技巧](zh_CN/2-if-else-block-secrets.md) 28 | - [3. 使用数字与字符串的技巧](zh_CN/3-tips-on-numbers-and-strings.md) 29 | - [4. 容器的门道](zh_CN/4-mastering-container-types.md) 30 | - [5. 让函数返回结果的技巧](zh_CN/5-function-returning-tips.md) 31 | - [6. 异常处理的三个好习惯](zh_CN/6-three-rituals-of-exceptions-handling.md) 32 | - 7\. 编写地道循环的两个建议 [[图书版：循环与可迭代对象](https://www.piglei.com/book/ch06_loop.html)] 33 | - [8. 使用装饰器的技巧](zh_CN/8-tips-on-decorators.md) 34 | - [9. 一个关于模块的小故事](zh_CN/9-a-story-on-cyclic-imports.md) 35 | - [10. 做一个精通规则的玩家](zh_CN/10-a-good-player-know-the-rules.md) 36 | - [11. 高效操作文件的三个建议](zh_CN/11-three-tips-on-writing-file-related-codes.md) 37 | - 12\. 写好面向对象代码的原则（上） [[图书版：面向对象设计原则（上）](https://www.piglei.com/book/ch10_solid_p1.html)] 38 | - [13. 写好面向对象代码的原则（中）](zh_CN/13-write-solid-python-codes-part-2.md) 39 | - [14. 写好面向对象代码的原则（下）](zh_CN/14-write-solid-python-codes-part-3.md) 40 | - [15. 在边界处思考](zh_CN/15-thinking-in-edge-cases.md) 41 | - [16. 语句、表达式和海象操作符](zh_CN/16-stmt-expr-and-walrus-operator.md) 42 | 43 | 如果你觉得读 GitHub 文件不太方便，也可以访问[这个镜像站点](https://pengzhangzhi.github.io/one-python-craftsman/)阅读所有文章（由 [@pengzhangzhi](https://github.com/pengzhangzhi) 搭建）。 44 | 45 | 也欢迎你关注我的微信公众号：piglei，在第一时间阅读最新文章： 46 | 47 | 48 | 49 | 所有文章禁止转载，如需转载请通过微信公众号联系我。 50 | 51 | ## 详细内容 52 | 53 | ### 1. [善用变量改善代码质量](zh_CN/1-using-variables-well.md) 54 | 55 | - 如何为变量起名 56 | - 1 - 变量名要有描述性，不能太宽泛 57 | - 2 - 变量名最好让人能猜出类型 58 | - 『什么样的名字会被当成 bool 类型？』 59 | - 『什么样的名字会被当成 int/float 类型？』 60 | - 其他类型 61 | - 3 - 适当使用『匈牙利命名法』 62 | - 4 - 变量名尽量短，但是绝对不要太短 63 | - 使用短名字的例外情况 64 | - 5 - 其他注意事项 65 | - 更好的使用变量 66 | - 1 - 保持一致性 67 | - 2 - 尽量不要用 globals()/locals() 68 | - 3 - 变量定义尽量靠近使用 69 | - 4 - 合理使用 namedtuple/dict 来让函数返回多个值 70 | - 5 - 控制单个函数内的变量数量 71 | - 6 - 及时删掉那些没用的变量 72 | - 7 - 能不定义变量就不定义 73 | - 结语 74 | 75 | ### 2. [编写条件分支代码的技巧](zh_CN/2-if-else-block-secrets.md) 76 | 77 | - 最佳实践 78 | - 1 - 避免多层分支嵌套 79 | - 2 - 封装那些过于复杂的逻辑判断 80 | - 3 - 留意不同分支下的重复代码 81 | - 4 - 谨慎使用三元表达式 82 | - 常见技巧 83 | - 1 - 使用“德摩根定律” 84 | - 2 - 自定义对象的“布尔真假” 85 | - 3 - 在条件判断中使用 all() / any() 86 | - 4 - 使用 try/while/for 中 else 分支 87 | - 常见陷阱 88 | - 1 - 与 None 值的比较 89 | - 2 - 留意 and 和 or 的运算优先级 90 | - 结语 91 | - 注解 92 | 93 | ### 3. [使用数字与字符串的技巧](zh_CN/3-tips-on-numbers-and-strings.md) 94 | 95 | - 最佳实践 96 | - 1 - 少写数字字面量 97 | - 使用 enum 枚举类型改善代码 98 | - 2 - 别在裸字符串处理上走太远 99 | - 3 - 不必预计算字面量表达式 100 | - 实用技巧 101 | - 1 - 布尔值其实也是“数字” 102 | - 2 - 改善超长字符串的可读性 103 | - 当多级缩进里出现多行字符串时 104 | - 3 - 别忘了那些 “r” 开头的内建字符串函数 105 | - 4 - 使用“无穷大” float("inf") 106 | - 常见误区 107 | - 1 - “value += 1” 并非线程安全 108 | - 2 - 字符串拼接并不慢 109 | - 结语 110 | 111 | ### 4. [容器的门道](zh_CN/4-mastering-container-types.md) 112 | 113 | - 底层看容器 114 | - 写更快的代码 115 | - 1 - 避免频繁扩充列表/创建新列表 116 | - 2 - 在列表头部操作多的场景使用 deque 模块 117 | - 3 - 使用集合/字典来判断成员是否存在 118 | - 高层看容器 119 | - 写扩展性更好的代码 120 | - 面向容器接口编程 121 | - 常用技巧 122 | - 1 - 使用元组改善分支代码 123 | - 2 - 在更多地方使用动态解包 124 | - 3 - 使用 next() 函数 125 | - 4 - 使用有序字典来去重 126 | - 常见误区 127 | - 1 - 当心那些已经枯竭的迭代器 128 | - 2 - 别在循环体内修改被迭代对象 129 | - 总结 130 | - 系列其他文章 131 | - 注解 132 | 133 | ### 5. [让函数返回结果的技巧](zh_CN/5-function-returning-tips.md) 134 | 135 | - 编程建议 136 | - 1 - 单个函数不要返回多种类型 137 | - 2 - 使用 partial 构造新函数 138 | - 3 - 抛出异常，而不是返回结果与错误 139 | - 4 - 谨慎使用 None 返回值 140 | - 1 - 作为操作类函数的默认返回值 141 | - 2 - 作为某些“意料之中”的可能没有的值 142 | - 3 - 作为调用失败时代表“错误结果”的值 143 | - 5 - 合理使用“空对象模式” 144 | - 6 - 使用生成器函数代替返回列表 145 | - 7 - 限制递归的使用 146 | - 总结 147 | - 附录 148 | 149 | ### 6. [异常处理的三个好习惯](zh_CN/6-three-rituals-of-exceptions-handling.md) 150 | 151 | - 前言 152 | - 三个好习惯 153 | - 1 - 只做最精确的异常捕获 154 | - 2 - 别让异常破坏抽象一致性 155 | - 3 - 异常处理不应该喧宾夺主 156 | - 总结 157 | - 附录 158 | 159 | ### 7. [编写地道循环的两个建议](zh_CN/7-two-tips-on-loop-writing.md) 160 | 161 | - 前言 162 | - 什么是“地道”的循环？ 163 | - enumerate() 所代表的编程思路 164 | - 建议1：使用函数修饰被迭代对象来优化循环 165 | - 1 - 使用 product 扁平化多层嵌套循环 166 | - 2 - 使用 islice 实现循环内隔行处理 167 | - 3 - 使用 takewhile 替代 break 语句 168 | - 4 - 使用生成器编写自己的修饰函数 169 | - 建议2：按职责拆解循环体内复杂代码块 170 | - 复杂循环体如何应对新需求 171 | - 使用生成器函数解耦循环体 172 | - 总结 173 | - 附录 174 | 175 | ### 8. [使用装饰器的技巧](zh_CN/8-tips-on-decorators.md) 176 | 177 | - 前言 178 | - 最佳实践 179 | - 1 - 尝试用类来实现装饰器 180 | - 2 - 使用 wrapt 模块编写更扁平的装饰器 181 | - 常见错误 182 | - 1 - “装饰器”并不是“装饰器模式” 183 | - 2 - 记得用 functools.wraps() 装饰内层函数 184 | - 3 - 修改外层变量时记得使用 nonlocal 185 | - 总结 186 | - 附录 187 | 188 | ### 9. [一个关于模块的小故事](zh_CN/9-a-story-on-cyclic-imports.md) 189 | 190 | - 前言 191 | - 一个关于模块的小故事 192 | - 需求变更 193 | - 解决环形依赖问题 194 | - 小 C 的疑问 195 | - 总结 196 | - 附录 197 | 198 | ### 10. [做一个精通规则的玩家](zh_CN/10-a-good-player-know-the-rules.md) 199 | 200 | - 前言 201 | - Python 里的规则 202 | - 案例：从两份旅游数据中获取人员名单 203 | - 第一次蛮力尝试 204 | - 尝试使用集合优化函数 205 | - 对问题的重新思考 206 | - 利用集合的游戏规则 207 | - 使用 dataclass 简化代码 208 | - 案例总结 209 | - 其他规则如何影响我们 210 | - 使用 `__format__` 做对象字符串格式化 211 | - 使用 `__getitem__` 定义对象切片操作 212 | - 总结 213 | - 附录 214 | 215 | ### 11. [高效操作文件的三个建议](zh_CN/11-three-tips-on-writing-file-related-codes.md) 216 | 217 | - 前言 218 | - 建议一：使用 pathlib 模块 219 | - 使用 pathlib 模块改写代码 220 | - 其他用法 221 | - 建议二：掌握如何流式读取大文件 222 | - 标准做法的缺点 223 | - 使用 read 方法分块读取 224 | - 利用生成器解耦代码 225 | - 建议三：设计接受文件对象的函数 226 | - 如何编写兼容二者的函数 227 | - 总结 228 | - 附录 229 | - 注解 230 | 231 | ### 12. [写好面向对象代码的原则（上）](zh_CN/12-write-solid-python-codes-part-1.md) 232 | 233 | - 前言 234 | - Python 对 OOP 的支持 235 | - SOLID 设计原则 236 | - SOLID 原则与 Python 237 | - S：单一职责原则 238 | - 违反“单一职责原则”的坏处 239 | - 拆分大类为多个小类 240 | - 另一种方案：使用函数 241 | - O：开放-关闭原则 242 | - 如何违反“开放-关闭原则” 243 | - 使用类继承来改造代码 244 | - 使用组合与依赖注入来改造代码 245 | - 使用数据驱动思想来改造代码 246 | - 总结 247 | - 附录 248 | 249 | ### 13. [写好面向对象代码的原则（中）](zh_CN/13-write-solid-python-codes-part-2.md) 250 | 251 | - 前言 252 | - 里氏替换原则与继承 253 | - L：里氏替换原则 254 | - 一个违反 L 原则的样例 255 | - 不当继承关系如何违反 L 原则 256 | - 一个简单但错误的解决办法 257 | - 正确的修改办法 258 | - 另一种违反方式：子类修改方法返回值法返回值) 259 | - 分析类方法返回结果 260 | - 如何修改代码 261 | - 方法参数与 L 原则 262 | - 总结 263 | - 附录 264 | 265 | ### 14. [写好面向对象代码的原则（下）](zh_CN/14-write-solid-python-codes-part-3.md) 266 | 267 | - 前言 268 | - D：依赖倒置原则 269 | - 需求：按域名分组统计 HN 新闻数量 270 | - 为 SiteSourceGrouper 编写单元测试 271 | - 使用 mock 模块 272 | - 实现依赖倒置原则 273 | - 依赖倒置后的单元测试 274 | - 问题：一定要使用抽象类 abc 吗？ 275 | - 问题：抽象一定是好东西吗？ 276 | - I：接口隔离原则 277 | - 例子：开发页面归档功能 278 | - 问题：实体类不符合 HNWebPage 接口规范 279 | - 成功违反 I 协议 280 | - 如何分拆接口 281 | - 一些不容易发现的违反情况 282 | - 现实世界中的接口隔离 283 | - 总结 284 | - 附录 285 | 286 | ### 15. [在边界处思考](zh_CN/15-thinking-in-edge-cases.md) 287 | 288 | - 前言 289 | - 第一课：使用分支还是异常？ 290 | - 获取原谅比许可简单(EAFP) 291 | - 当容器内容不存在时 292 | - 使用 defaultdict 改写示例 293 | - 使用 setdefault 取值并修改 294 | - 使用 dict.pop 删除不存在的键 295 | - 当列表切片越界时 296 | - 好用又危险的 “or” 操作符 297 | - 不要手动去做数据校验 298 | - 不要忘记做数学计算 299 | - 总结 300 | - 附录 301 | 302 | ### 16. [语句、表达式和海象操作符](zh_CN/16-stmt-expr-and-walrus-operator.md) 303 | 304 | - 表达式的特点 305 | - 海象操作符 306 | - 1. 用于分支语句 307 | - 2. 消除推导式中的重复 308 | - 3. 捕获推导式的中间结果 309 | - 4. 赋值表达式的限制 310 | - 其他建议 311 | - 1. “更紧凑”不等于“更好” 312 | - 2. 宜少不宜多 313 | -------------------------------------------------------------------------------- /zh_CN/1-using-variables-well.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：善用变量来改善代码质量 2 | 3 | ## 『Python 工匠』是什么？ 4 | 5 | 我一直觉得编程某种意义上是一门『手艺』，因为优雅而高效的代码，就如同完美的手工艺品一样让人赏心悦目。 6 | 7 | 在雕琢代码的过程中，有大工程：比如应该用什么架构、哪种设计模式。也有更多的小细节，比如何时使用异常（Exceptions）、或怎么给变量起名。那些真正优秀的代码，正是由无数优秀的细节造就的。 8 | 9 | 『Python 工匠』这个系列文章，是我的一次小小尝试。它专注于分享 Python 编程中的一些偏 **『小』** 的东西。希望能够帮到每一位编程路上的匠人。 10 | 11 | > 这是 “Python 工匠”系列的第 1 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 12 | 13 | ## 变量和代码质量 14 | 15 | 作为『Python 工匠』系列文章的第一篇，我想先谈谈 『变量（Variables）』。因为如何定义和使用变量，一直都是学习任何一门编程语言最先要掌握的技能之一。 16 | 17 | 变量用的好或不好，和代码质量有着非常重要的联系。在关于变量的诸多问题中，为变量起一个好名字尤其重要。 18 | 19 | ### 内容目录 20 | 21 | - [Python 工匠：善用变量来改善代码质量](#python-工匠善用变量来改善代码质量) 22 | - [『Python 工匠』是什么？](#python-工匠是什么) 23 | - [变量和代码质量](#变量和代码质量) 24 | - [内容目录](#内容目录) 25 | - [如何为变量起名](#如何为变量起名) 26 | - [1. 变量名要有描述性，不能太宽泛](#1-变量名要有描述性不能太宽泛) 27 | - [2. 变量名最好让人能猜出类型](#2-变量名最好让人能猜出类型) 28 | - [『什么样的名字会被当成 bool 类型？』](#什么样的名字会被当成-bool-类型) 29 | - [『什么样的名字会被当成 int/float 类型？』](#什么样的名字会被当成-intfloat-类型) 30 | - [其他类型](#其他类型) 31 | - [3. 适当使用『匈牙利命名法』](#3-适当使用匈牙利命名法) 32 | - [4. 变量名尽量短，但是绝对不要太短](#4-变量名尽量短但是绝对不要太短) 33 | - [使用短名字的例外情况](#使用短名字的例外情况) 34 | - [5. 其他注意事项](#5-其他注意事项) 35 | - [更好的使用变量](#更好的使用变量) 36 | - [1. 保持一致性](#1-保持一致性) 37 | - [2. 尽量不要用 globals()/locals()](#2-尽量不要用-globalslocals) 38 | - [3. 变量定义尽量靠近使用](#3-变量定义尽量靠近使用) 39 | - [4. 合理使用 namedtuple/dict 来让函数返回多个值](#4-合理使用-namedtupledict-来让函数返回多个值) 40 | - [5. 控制单个函数内的变量数量](#5-控制单个函数内的变量数量) 41 | - [6. 及时删掉那些没用的变量](#6-及时删掉那些没用的变量) 42 | - [7. 定义临时变量提升可读性](#7-定义临时变量提升可读性) 43 | - [结语](#结语) 44 | 45 | ## 如何为变量起名 46 | 47 | 在计算机科学领域，有一句著名的格言（俏皮话）： 48 | 49 | > There are only two hard things in Computer Science: cache invalidation and naming things. 50 | > 在计算机科学领域只有两件难事：缓存失效 和 给东西起名字 51 | > 52 | > -- Phil Karlton 53 | 54 | 第一个『缓存过期问题』的难度不用多说，任何用过缓存的人都会懂。至于第二个『给东西起名字』这事的难度，我也是深有体会。在我的职业生涯里，度过的最为黑暗的下午之一，就是坐在显示器前抓耳挠腮为一个新项目起一个合适的名字。 55 | 56 | 编程时起的最多的名字，还数各种变量。给变量起一个好名字很重要，**因为好的变量命名可以极大提高代码的整体可读性。** 57 | 58 | 下面几点，是我总结的为变量起名时，最好遵守的基本原则。 59 | 60 | ### 1. 变量名要有描述性，不能太宽泛 61 | 62 | 在**可接受的长度范围内**，变量名能把它所指向的内容描述的越精确越好。所以，尽量不要用那些过于宽泛的词来作为你的变量名： 63 | 64 | - **BAD**: `day`, `host`, `cards`, `temp` 65 | - **GOOD**: `day_of_week`, `hosts_to_reboot`, `expired_cards` 66 | 67 | ### 2. 变量名最好让人能猜出类型 68 | 69 | 所有学习 Python 的人都知道，Python 是一门动态类型语言，它（至少在 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 出现前）没有变量类型声明。所以当你看到一个变量时，除了通过上下文猜测，没法轻易知道它是什么类型。 70 | 71 | 不过，人们对于变量名和变量类型的关系，通常会有一些直觉上的约定，我把它们总结在了下面。 72 | 73 | #### 『什么样的名字会被当成 bool 类型？』 74 | 75 | 布尔类型变量的最大特点是：它只存在两个可能的值 **『是』** 或 **『不是』**。所以，用 `is`、`has` 等非黑即白的词修饰的变量名，会是个不错的选择。原则就是：**让读到变量名的人觉得这个变量只会有『是』或『不是』两种值**。 76 | 77 | 下面是几个不错的示例： 78 | 79 | - `is_superuser`：『是否超级用户』，只会有两种值：是/不是 80 | - `has_error`：『有没有错误』，只会有两种值：有/没有 81 | - `allow_vip`：『是否允许 VIP』，只会有两种值：允许/不允许 82 | - `use_msgpack`：『是否使用 msgpack』，只会有两种值：使用/不使用 83 | - `debug`：『是否开启调试模式』，被当做 bool 主要是因为约定俗成 84 | 85 | #### 『什么样的名字会被当成 int/float 类型？』 86 | 87 | 人们看到和数字相关的名字，都会默认他们是 int/float 类型，下面这些是比较常见的： 88 | 89 | - 释义为数字的所有单词，比如：`port（端口号）`、`age（年龄）`、`radius（半径）` 等等 90 | - 使用 _id 结尾的单词，比如：`user_id`、`host_id` 91 | - 使用 length/count 开头或者结尾的单词，比如： `length_of_username`、`max_length`、`users_count` 92 | 93 | **注意：** 不要使用普通的复数来表示一个 int 类型变量，比如 `apples`、`trips`，最好用 `number_of_apples`、`trips_count` 来替代。 94 | 95 | #### 其他类型 96 | 97 | 对于 str、list、tuple、dict 这些复杂类型，很难有一个统一的规则让我们可以通过名字去猜测变量类型。比如 `headers`，既可能是一个头信息列表，也可能是包含头信息的 dict。 98 | 99 | 对于这些类型的变量名，最推荐的方式，就是编写规范的文档，在函数和方法的 document string 中，使用 sphinx 格式（[Python 官方文档使用的文档工具](http://www.sphinx-doc.org/en/stable/)）来标注所有变量的类型。 100 | 101 | ### 3. 适当使用『匈牙利命名法』 102 | 103 | 第一次知道『[匈牙利命名法](https://en.wikipedia.org/wiki/Hungarian_notation)』，是在 [Joel on Software 的一篇博文](http://www.joelonsoftware.com/articles/Wrong.html)中。简而言之，匈牙利命名法就是把变量的『类型』缩写，放到变量名的最前面。 104 | 105 | 关键在于，这里说的变量『类型』，并非指传统意义上的 int/str/list 这种类型，而是指那些和你的代码业务逻辑相关的类型。 106 | 107 | 比如，在你的代码中有两个变量：`students` 和 `teachers`，他们指向的内容都是一个包含 Person 对象的 list 。使用『匈牙利命名法』后，可以把这两个名字改写成这样： 108 | 109 | students -> `pl_students` 110 | teachers -> `pl_teachers` 111 | 112 | 其中 pl 是 **person list** 的首字母缩写。当变量名被加上前缀后，如果你看到以 `pl_` 打头的变量，就能知道它所指向的值类型了。 113 | 114 | 很多情况下，使用『匈牙利命名法』是个不错的主意，因为它可以改善你的代码可读性，尤其在那些变量众多、同一类型多次出现时。注意不要滥用就好。 115 | 116 | ### 4. 变量名尽量短，但是绝对不要太短 117 | 118 | 在前面，我们提到要让变量名有描述性。如果不给这条原则加上任何限制，那么你很有可能写出这种描述性极强的变量名：`how_much_points_need_for_level2`。如果代码中充斥着这种过长的变量名，对于代码可读性来说是个灾难。 119 | 120 | 一个好的变量名，长度应该控制在 **两到三个单词左右**。比如上面的名字，可以缩写为 `points_level2`。 121 | 122 | **绝大多数情况下，都应该避免使用那些只有一两个字母的短名字**，比如数组索引三剑客 `i`、`j`、`k`，用有明确含义的名字，比如 person_index 来代替它们总是会更好一些。 123 | 124 | #### 使用短名字的例外情况 125 | 126 | 有时，上面的原则也存在一些例外。当一些意义明确但是较长的变量名重复出现时，为了让代码更简洁，使用短名字缩写是完全可以的。但是为了降低理解成本，同一段代码内最好不要使用太多这种短名字。 127 | 128 | 比如在 Python 中导入模块时，就会经常用到短名字作为别名，像 Django i18n 翻译时常用的 `gettext` 方法通常会被缩写成 `_` 来使用*（from django.utils.translation import ugettext as _）* 129 | 130 | ### 5. 其他注意事项 131 | 132 | 其他一些给变量命名的注意事项： 133 | 134 | - 同一段代码内不要使用过于相似的变量名，比如同时出现 `users`、`users1`、 `user3` 这种序列 135 | - 不要使用带否定含义的变量名，用 `is_special` 代替 `is_not_normal` 136 | 137 | ## 更好的使用变量 138 | 139 | 前面讲了如何为变量取一个好名字，下面我们谈谈在日常使用变量时，应该注意的一些小细节。 140 | 141 | ### 1. 保持一致性 142 | 143 | 如果你在一个方法内里面把图片变量叫做 `photo`，在其他的地方就不要把它改成 `image`，这样只会让代码的阅读者困惑：『`image` 和 `photo` 到底是不是同一个东西？』 144 | 145 | 另外，虽然 Python 是动态类型语言，但那也不意味着你可以用同一个变量名一会表示 str 类型，过会又换成 list。**同一个变量名指代的变量类型，也需要保持一致性。** 146 | 147 | ### 2. 尽量不要用 globals()/locals() 148 | 149 | 也许你第一次发现 globals()/locals() 这对内建函数时很兴奋，迫不及待的写下下面这种极端『简洁』的代码： 150 | 151 | ```python 152 | def render_trip_page(request, user_id, trip_id): 153 | user = User.objects.get(id=user_id) 154 | trip = get_object_or_404(Trip, pk=trip_id) 155 | is_suggested = is_suggested(user, trip) 156 | # 利用 locals() 节约了三行代码，我是个天才！ 157 | return render(request, 'trip.html', locals()) 158 | ``` 159 | 160 | 千万不要这么做，这样只会让读到这段代码的人（包括三个月后的你自己）痛恨你，因为他需要记住这个函数内定义的所有变量（想想这个函数增长到两百行会怎么样？），更别提 locals() 还会把一些不必要的变量传递出去。 161 | 162 | 更何况， [The Zen of Python（Python 之禅）](https://www.python.org/dev/peps/pep-0020/) 说的清清楚楚：**Explicit is better than implicit.（显式优于隐式）**。所以，还是老老实实把代码写成这样吧： 163 | 164 | ```python 165 | return render(request, 'trip.html', { 166 | 'user': user, 167 | 'trip': trip, 168 | 'is_suggested': is_suggested 169 | }) 170 | ``` 171 | 172 | ### 3. 变量定义尽量靠近使用 173 | 174 | 这个原则属于老生常谈了。很多人（包括我）在刚开始学习编程时，会有一个习惯。就是把所有的变量定义写在一起，放在函数或方法的最前面。 175 | 176 | ```python 177 | def generate_trip_png(trip): 178 | path = [] 179 | markers = [] 180 | photo_markers = [] 181 | text_markers = [] 182 | marker_count = 0 183 | point_count = 0 184 | ... ... 185 | ``` 186 | 187 | 这样做只会让你的代码『看上去很整洁』，但是对提高代码可读性没有任何帮助。 188 | 189 | 更好的做法是，**让变量定义尽量靠近使用**。那样当你阅读代码时，可以更好的理解代码的逻辑，而不是费劲的去想这个变量到底是什么、哪里定义的？ 190 | 191 | ### 4. 合理使用 namedtuple/dict 来让函数返回多个值 192 | 193 | Python 的函数可以返回多个值： 194 | 195 | ```python 196 | def latlon_to_address(lat, lon): 197 | return country, province, city 198 | 199 | # 利用多返回值一次解包定义多个变量 200 | country, province, city = latlon_to_address(lat, lon) 201 | ``` 202 | 203 | 但是，这样的用法会产生一个小问题：如果某一天， `latlon_to_address` 函数需要返回『城区（District）』时怎么办？ 204 | 205 | 如果是上面这种写法，你需要找到所有调用 `latlon_to_address` 的地方，补上多出来的这个变量，否则 *ValueError: too many values to unpack* 就会找上你： 206 | 207 | ```python 208 | country, province, city, district = latlon_to_address(lat, lon) 209 | # 或者使用 _ 忽略多出来的返回值 210 | country, province, city, _ = latlon_to_address(lat, lon) 211 | ``` 212 | 213 | 对于这种可能变动的多返回值函数，使用 namedtuple/dict 会更方便一些。当你新增返回值时，不会对之前的函数调用产生任何破坏性的影响： 214 | 215 | ```python 216 | # 1. 使用 dict 217 | def latlon_to_address(lat, lon): 218 | return { 219 | 'country': country, 220 | 'province': province, 221 | 'city': city 222 | } 223 | 224 | addr_dict = latlon_to_address(lat, lon) 225 | 226 | # 2. 使用 namedtuple 227 | from collections import namedtuple 228 | 229 | Address = namedtuple("Address", ['country', 'province', 'city']) 230 | 231 | def latlon_to_address(lat, lon): 232 | return Address( 233 | country=country, 234 | province=province, 235 | city=city 236 | ) 237 | 238 | addr = latlon_to_address(lat, lon) 239 | ``` 240 | 241 | 不过这样做也有坏处，因为代码对变更的兼容性虽然变好了，但是你不能继续用之前 `x, y = f()` 的方式一次解包定义多个变量了。取舍在于你自己。 242 | 243 | ### 5. 控制单个函数内的变量数量 244 | 245 | 人脑的能力是有限的，研究表明，人类的短期记忆只能同时记住不超过十个名字。所以，当你的某个函数过长（一般来说，超过一屏的的函数就会被认为有点过长了），包含了太多变量时。请及时把它拆分为多个小函数吧。 246 | 247 | ### 6. 及时删掉那些没用的变量 248 | 249 | 这条原则非常简单，也很容易做到。但是如果没有遵守，那它对你的代码质量的打击是毁灭级的。会让阅读你代码的人有一种被愚弄的感觉。 250 | 251 | ```python 252 | def fancy_func(): 253 | # 读者心理：嗯，这里定义了一个 fancy_vars 254 | fancy_vars = get_fancy() 255 | ... ...（一大堆代码过后） 256 | 257 | # 读者心理：这里就结束了？之前的 fancy_vars 去哪了？被猫吃了吗？ 258 | return result 259 | ``` 260 | 261 | 所以，请打开 IDE 的智能提示，及时清理掉那些定义了但是没有使用的变量吧。 262 | 263 | ### 7. 定义临时变量提升可读性 264 | 265 | 有时，我们的代码里会出现一些复杂的表达式，像下面这样： 266 | 267 | ```python 268 | # 为所有性别为女性，或者级别大于 3 的活跃用户发放 10000 个金币 269 | if user.is_active and (user.sex == 'female' or user.level > 3): 270 | user.add_coins(10000) 271 | return 272 | ``` 273 | 274 | 看见 `if` 后面那一长串了吗？有点难读对不对？但是如果我们把它赋值成一个临时变量， 275 | 就能给读者一个心理缓冲，提高可读性： 276 | 277 | ``` 278 | # 为所有性别为女性，或者级别大于 3 的活跃用户发放 10000 个金币 279 | user_is_eligible = user.is_active and (user.sex == 'female' or user.level > 3): 280 | 281 | if user_is_eligible: 282 | user.add_coins(10000) 283 | return 284 | ``` 285 | 286 | 定义临时变量可以提高可读性。但有时，把不必要的东西赋值成临时变量反而会让代码显得啰嗦： 287 | 288 | ```python 289 | def get_best_trip_by_user_id(user_id): 290 | 291 | # 心理活动：『嗯，这个值未来说不定会修改/二次使用』，让我们先把它定义成变量吧！ 292 | user = get_user(user_id) 293 | trip = get_best_trip(user_id) 294 | result = { 295 | 'user': user, 296 | 'trip': trip 297 | } 298 | return result 299 | ``` 300 | 301 | 其实，你所想的『未来』永远不会来，这段代码里的三个临时变量完全可以去掉，变成这样： 302 | 303 | ```python 304 | def get_best_trip_by_user_id(user_id): 305 | return { 306 | 'user': get_user(user_id), 307 | 'trip': get_best_trip(user_id) 308 | } 309 | ``` 310 | 311 | 没必要为了那些可能出现的变动，牺牲代码当前的可读性。如果以后有定义变量的需求，那就以后再加吧。 312 | 313 | ## 结语 314 | 315 | 碎碎念了一大堆，不知道有多少人能够坚持到最后。变量作为程序语言的重要组成部分，值得我们在定义和使用它时，多花一丁点时间思考一下，那样会让你的代码变得更优秀。 316 | 317 | 这是『Python 工匠』系列文章的第一篇，不知道看完文章的你，有没有什么想吐槽的？请留言告诉我吧。 318 | 319 | [>>>下一篇【2.编写条件分支代码的技巧】](2-if-else-block-secrets.md) 320 | 321 | > 文章更新记录： 322 | > 323 | > - 2018.04.09：根据 @onlyice 的建议，添加了 namedtuple 部分 324 | 325 | -------------------------------------------------------------------------------- /zh_CN/10-a-good-player-know-the-rules.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：做一个精通规则的玩家 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 10 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 编程，其实和玩电子游戏有一些相似之处。你在玩不同游戏前，需要先学习每个游戏的不同规则，只有熟悉和灵活运用游戏规则，才更有可能在游戏中获胜。 12 | 13 | 而编程也是一样，不同编程语言同样有着不一样的“规则”。大到是否支持面向对象，小到是否可以定义常量，编程语言的规则比绝大多数电子游戏要复杂的多。 14 | 15 | 当我们编程时，如果直接拿一种语言的经验套用到另外一种语言上，很多时候并不能取得最佳结果。这就好像一个 CS（反恐精英） 高手在不了解规则的情况下去玩 PUBG（绝地求生），虽然他的枪法可能万中无一，但是极有可能在发现第一个敌人前，他就会倒在某个窝在草丛里的敌人的伏击下。 16 | 17 | ### Python 里的规则 18 | 19 | Python 是一门初见简单、深入后愈觉复杂的语言。拿 Python 里最重要的“对象”概念来说，Python 为其定义了多到让你记不全的规则，比如： 20 | 21 | - 定义了 `__str__` 方法的对象，就可以使用 `str()` 函数来返回可读名称 22 | - 定义了 `__next__` 和 `__iter__` 方法的对象，就可以被循环迭代 23 | - 定义了 `__bool__` 方法的对象，在进行布尔判断时就会使用自定义的逻辑 24 | - ... ... 25 | 26 | **熟悉规则，并让自己的代码适应这些规则，可以帮助我们写出更地道的代码，事半功倍的完成工作。**下面，让我们来看一个有关适应规则的故事。 27 | 28 | ## 案例：从两份旅游数据中获取人员名单 29 | 30 | 某日，在一个主打新西兰出境游的旅游公司里，商务同事突然兴冲冲的跑过来找到我，说他从某合作伙伴那里，要到了两份重要的数据： 31 | 32 | 1. 所有去过“泰国普吉岛”的人员及联系方式 33 | 2. 所有去过“新西兰”的人员及联系方式 34 | 35 | 数据采用了 JSON 格式，如下所示： 36 | 37 | ```python 38 | # 去过普吉岛的人员数据 39 | users_visited_phuket = [ 40 | {"first_name": "Sirena", "last_name": "Gross", "phone_number": "650-568-0388", "date_visited": "2018-03-14"}, 41 | {"first_name": "James", "last_name": "Ashcraft", "phone_number": "412-334-4380", "date_visited": "2014-09-16"}, 42 | ... ... 43 | ] 44 | 45 | # 去过新西兰的人员数据 46 | users_visited_nz = [ 47 | {"first_name": "Justin", "last_name": "Malcom", "phone_number": "267-282-1964", "date_visited": "2011-03-13"}, 48 | {"first_name": "Albert", "last_name": "Potter", "phone_number": "702-249-3714", "date_visited": "2013-09-11"}, 49 | ... ... 50 | ] 51 | ``` 52 | 53 | 每份数据里面都有着`姓`、`名`、`手机号码`、`旅游时间` 四个字段。基于这份数据，商务同学提出了一个 *（听上去毫无道理）* 的假设：“去过普吉岛的人，应该对去新西兰旅游也很有兴趣。我们需要从这份数据里，找出那些**去过普吉岛但没有去过新西兰的人**，针对性的卖产品给他们。 54 | 55 | ### 第一次蛮力尝试 56 | 57 | 有了原始数据和明确的需求，接下来的问题就是如何写代码了。依靠蛮力，我很快就写出了第一个方案： 58 | 59 | ```python 60 | def find_potential_customers_v1(): 61 | """找到去过普吉岛但是没去过新西兰的人 62 | """ 63 | for phuket_record in users_visited_phuket: 64 | is_potential = True 65 | for nz_record in users_visited_nz: 66 | if phuket_record['first_name'] == nz_record['first_name'] and \ 67 | phuket_record['last_name'] == nz_record['last_name'] and \ 68 | phuket_record['phone_number'] == nz_record['phone_number']: 69 | is_potential = False 70 | break 71 | 72 | if is_potential: 73 | yield phuket_record 74 | ``` 75 | 76 | 因为原始数据里没有 *“用户 ID”* 之类的唯一标示，所以我们只能把“姓名和电话号码完全相同”作为判断是不是同一个人的标准。 77 | 78 | `find_potential_customers_v1` 函数通过循环的方式，先遍历所有去过普吉岛的人，然后再遍历新西兰的人，如果在新西兰的记录中找不到完全匹配的记录，就把它当做“潜在客户”返回。 79 | 80 | 这个函数虽然可以完成任务，但是相信不用我说你也能发现。**它有着非常严重的性能问题**。对于每一条去过普吉岛的记录，我们都需要遍历所有新西兰访问记录，尝试找到匹配。整个算法的时间复杂度是可怕的 `O(n*m)`，如果新西兰的访问条目数很多的话，那么执行它将耗费非常长的时间。 81 | 82 | 为了优化内层循环性能，我们需要减少线性查找匹配部分的开销。 83 | 84 | ### 尝试使用集合优化函数 85 | 86 | 如果你对 Python 有所了解的话，那么你肯定知道，Python 里的字典和集合对象都是基于 [哈希表（Hash Table）](https://en.wikipedia.org/wiki/Hash_table) 实现的。判断一个东西是不是在集合里的平均时间复杂度是 `O(1)`，非常快。 87 | 88 | 所以，对于上面的函数，我们可以先尝试针对新西兰访问记录初始化一个集合，之后的查找匹配部分就可以变得很快，函数整体时间复杂度就能变为 `O(n+m)`。 89 | 90 | 让我们看看新的函数： 91 | 92 | ```python 93 | def find_potential_customers_v2(): 94 | """找到去过普吉岛但是没去过新西兰的人，性能改进版 95 | """ 96 | # 首先，遍历所有新西兰访问记录，创建查找索引 97 | nz_records_idx = { 98 | (rec['first_name'], rec['last_name'], rec['phone_number']) 99 | for rec in users_visited_nz 100 | } 101 | 102 | for rec in users_visited_phuket: 103 | key = (rec['first_name'], rec['last_name'], rec['phone_number']) 104 | if key not in nz_records_idx: 105 | yield rec 106 | ``` 107 | 108 | 使用了集合对象后，新函数在速度上相比旧版本有了飞跃性的突破。但是，对这个问题的优化并不是到此为止，不然文章标题就应该改成：“如何使用集合提高程序性能” 了。 109 | 110 | ### 对问题的重新思考 111 | 112 | 让我们来尝试重新抽象思考一下问题的本质。首先，我们有一份装了很多东西的容器 A*（普吉岛访问记录）*，然后给我们另一个装了很多东西的容器 B*（新西兰访问记录）*，之后定义相等规则：“姓名与电话一致”。最后基于这个相等规则，求 A 和 B 之间的 **“差集”**。 113 | 114 | 如果你对 Python 里的集合不是特别熟悉，我就稍微多介绍一点。假如我们拥有两个集合 A 和 B，那么我们可以直接使用 `A - B` 这样的数学运算表达式来计算二者之间的 **差集**。 115 | 116 | ```python 117 | >>> a = {1, 3, 5, 7} 118 | >>> b = {3, 5, 8} 119 | # 产生新集合：所有在 a 但是不在 b 里的元素 120 | >>> a - b 121 | {1, 7} 122 | ``` 123 | 124 | 所以，计算“所有去过普吉岛但没去过新西兰的人”，其实就是一次集合的求差值操作。那么要怎么做，才能把我们的问题套入到集合的游戏规则里去呢? 125 | 126 | ### 利用集合的游戏规则 127 | 128 | 在 Python 中，如果要把某个东西装到集合或字典里，一定要满足一个基本条件：**“这个东西必须是可以被哈希（Hashable）的”** 。什么是 “Hashable”？ 129 | 130 | 举个例子，Python 里面的所有可变对象，比如字典，就 **不是** Hashable 的。当你尝试把字典放入集合中时，会发生这样的错误： 131 | 132 | ```python 133 | >>> s = set() 134 | >>> s.add({'foo': 'bar'}) 135 | Traceback (most recent call last): 136 | File "", line 1, in 137 | TypeError: unhashable type: 'dict' 138 | ``` 139 | 140 | 所以，如果要利用集合解决我们的问题，就首先得定义我们自己的 “Hashable” 对象：`VisitRecord`。而要让一个自定义对象变得 Hashable，唯一要做的事情就是定义对象的 `__hash__` 方法。 141 | 142 | ```python 143 | class VisitRecord: 144 | """旅游记录 145 | """ 146 | def __init__(self, first_name, last_name, phone_number, date_visited): 147 | self.first_name = first_name 148 | self.last_name = last_name 149 | self.phone_number = phone_number 150 | self.date_visited = date_visited 151 | ``` 152 | 153 | 一个好的哈希算法，应该让不同对象之间的值尽可能的唯一，这样可以最大程度减少[“哈希碰撞”](https://en.wikipedia.org/wiki/Collision_(computer_science))发生的概率，默认情况下，所有 Python 对象的哈希值来自它的内存地址。 154 | 155 | 在这个问题里，我们需要自定义对象的 `__hash__` 方法，让它利用 `（姓，名，电话）`元组作为 `VisitRecord` 类的哈希值来源。 156 | 157 | ```python 158 | def __hash__(self): 159 | return hash( 160 | (self.first_name, self.last_name, self.phone_number) 161 | ) 162 | ``` 163 | 164 | 自定义完 `__hash__` 方法后，`VisitRecord` 实例就可以正常的被放入集合中了。但这还不够，为了让前面提到的求差值算法正常工作，我们还需要实现 `__eq__` 特殊方法。 165 | 166 | `__eq__` 是 Python 在判断两个对象是否相等时调用的特殊方法。默认情况下，它只有在自己和另一个对象的内存地址完全一致时，才会返回 `True`。但是在这里，我们复用了 `VisitRecord` 对象的哈希值，当二者相等时，就认为它们一样。 167 | 168 | ```python 169 | def __eq__(self, other): 170 | # 当两条访问记录的名字与电话号相等时，判定二者相等。 171 | if isinstance(other, VisitRecord) and hash(other) == hash(self): 172 | return True 173 | return False 174 | ``` 175 | 176 | 完成了恰当的数据建模后，之后的求差值运算便算是水到渠成了。新版本的函数只需要一行代码就能完成操作： 177 | 178 | ```python 179 | def find_potential_customers_v3(): 180 | return set(VisitRecord(**r) for r in users_visited_phuket) - \ 181 | set(VisitRecord(**r) for r in users_visited_nz) 182 | ``` 183 | 184 | > Hint：如果你使用的是 Python 2，那么除了 `__eq__` 方法外，你还需要自定义类的 `__ne__`（判断不相等时使用） 方法。 185 | 186 | ### 使用 dataclass 简化代码 187 | 188 | 故事到这里并没有结束。在上面的代码里，我们手动定义了自己的 **数据类** `VisitRecord`，实现了 `__init__`、`__eq__` 等初始化方法。但其实还有更简单的做法。 189 | 190 | 因为定义数据类这种需求在 Python 中实在太常见了，所以在 3.7 版本中，标准库中新增了 [dataclasses](https://docs.python.org/3/library/dataclasses.html) 模块，专门帮你简化这类工作。 191 | 192 | 如果使用 dataclasses 提供的特性，我们的代码可以最终简化成下面这样： 193 | 194 | ```python 195 | @dataclass(unsafe_hash=True) 196 | class VisitRecordDC: 197 | first_name: str 198 | last_name: str 199 | phone_number: str 200 | # 跳过“访问时间”字段，不作为任何对比条件 201 | date_visited: str = field(hash=False, compare=False) 202 | 203 | 204 | def find_potential_customers_v4(): 205 | return set(VisitRecordDC(**r) for r in users_visited_phuket) - \ 206 | set(VisitRecordDC(**r) for r in users_visited_nz) 207 | ``` 208 | 209 | 不用干任何脏活累活，只要不到十行代码就完成了工作。 210 | 211 | ### 案例总结 212 | 213 | 问题解决以后，让我们再做一点小小的总结。在处理这个问题时，我们一共使用了三种方案： 214 | 215 | 1. 使用普通的两层循环筛选符合规则的结果集 216 | 2. 利用哈希表结构（set 对象）创建索引，提升处理效率 217 | 3. 将数据转换为自定义对象，利用规则，直接使用集合运算 218 | 219 | 为什么第三种方式会比前面两种好呢？ 220 | 221 | 首先，第一个方案的性能问题过于明显，所以很快就会被放弃。那么第二个方案呢？仔细想想看，方案二其实并没有什么明显的缺点。甚至和第三个方案相比，因为少了自定义对象的过程，它在性能与内存占用上，甚至有可能会微微强于后者。 222 | 223 | 但请再思考一下，如果你把方案二的代码换成另外一种语言，比如 Java，它是不是基本可以做到 1:1 的完全翻译？换句话说，**它虽然效率高、代码直接，但是它没有完全利用好 Python 世界提供的规则，最大化的从中受益。** 224 | 225 | 如果要具体化这个问题里的“规则”，那就是 **“Python 拥有内置结构集合，集合之间可以进行差值等四则运算”** 这个事实本身。匹配规则后编写的方案三代码拥有下面这些优势： 226 | 227 | - 为数据建模后，可以更方便的定义其他方法 228 | - 如果需求变更，做反向差值运算、求交集运算都很简单 229 | - 理解集合与 dataclasses 逻辑后，代码远比其他版本更简洁清晰 230 | - 如果要修改相等规则，比如“只拥有相同姓的记录就算作一样”，只需要继承`VisitRecord` 覆盖 `__eq__` 方法即可 231 | 232 | ## 其他规则如何影响我们 233 | 234 | 在前面，我们花了很大的篇幅讲了如何利用“集合的规则”来编写事半功倍的代码。除此之外，Python 世界中还有着很多其他规则。如果能熟练掌握这些规则，就可以设计出符合 Python 惯例的 API，让代码更简洁精炼。 235 | 236 | 下面是两个具体的例子。 237 | 238 | ### 使用 `__format__` 做对象字符串格式化 239 | 240 | 如果你的自定义对象需要定义多种字符串表示方式，就像下面这样： 241 | 242 | ```python 243 | class Student: 244 | def __init__(self, name, age): 245 | self.name = name 246 | self.age = age 247 | 248 | def get_simple_display(self): 249 | return f'{self.name}({self.age})' 250 | 251 | def get_long_display(self): 252 | return f'{self.name} is {self.age} years old.' 253 | 254 | 255 | piglei = Student('piglei', '18') 256 | # OUTPUT: piglei(18) 257 | print(piglei.get_simple_display()) 258 | # OUTPUT: piglei is 18 years old. 259 | print(piglei.get_long_display()) 260 | ``` 261 | 262 | 那么除了增加这种 `get_xxx_display()` 额外方法外，你还可以尝试自定义 `Student` 类的 `__format__` 方法，因为那才是将对象变为字符串的标准规则。 263 | 264 | ```python 265 | class Student: 266 | def __init__(self, name, age): 267 | self.name = name 268 | self.age = age 269 | 270 | def __format__(self, format_spec): 271 | if format_spec == 'long': 272 | return f'{self.name} is {self.age} years old.' 273 | elif format_spec == 'simple': 274 | return f'{self.name}({self.age})' 275 | raise ValueError('invalid format spec') 276 | 277 | 278 | piglei = Student('piglei', '18') 279 | print('{0:simple}'.format(piglei)) 280 | print('{0:long}'.format(piglei)) 281 | ``` 282 | 283 | ### 使用 `__getitem__` 定义对象切片操作 284 | 285 | 如果你要设计某个可以装东西的容器类型，那么你很可能会为它定义“是否为空”、“获取第 N 个对象”等方法： 286 | 287 | ```python 288 | class Events: 289 | def __init__(self, events): 290 | self.events = events 291 | 292 | def is_empty(self): 293 | return not bool(self.events) 294 | 295 | def list_events_by_range(self, start, end): 296 | return self.events[start:end] 297 | 298 | events = Events([ 299 | 'computer started', 300 | 'os launched', 301 | 'docker started', 302 | 'os stopped', 303 | ]) 304 | 305 | # 判断是否有内容，打印第二个和第三个对象 306 | if not events.is_empty(): 307 | print(events.list_events_by_range(1, 3)) 308 | ``` 309 | 310 | 但是，这样并非最好的做法。因为 Python 已经为我们提供了一套对象规则，所以我们不需要像写其他语言的 OO *（面向对象）* 代码那样去自己定义额外方法。我们有更好的选择： 311 | 312 | ```python 313 | 314 | class Events: 315 | def __init__(self, events): 316 | self.events = events 317 | 318 | def __len__(self): 319 | """自定义长度，将会被用来做布尔判断""" 320 | return len(self.events) 321 | 322 | def __getitem__(self, index): 323 | """自定义切片方法""" 324 | # 直接将 slice 切片对象透传给 events 处理 325 | return self.events[index] 326 | 327 | # 判断是否有内容，打印第二个和第三个对象 328 | if events: 329 | print(events[1:3]) 330 | ``` 331 | 332 | 新的写法相比旧代码，更能适配进 Python 世界的规则，API 也更为简洁。 333 | 334 | 关于如何适配规则、写出更好的 Python 代码。Raymond Hettinger 在 PyCon 2015 上有过一次非常精彩的演讲 [“Beyond PEP8 - Best practices for beautiful intelligible code”](https://www.youtube.com/watch?v=wf-BqAjZb8M)。这次演讲长期排在我个人的 *“PyCon 视频 TOP5”* 名单上，如果你还没有看过，我强烈建议你现在就去看一遍 :) 335 | 336 | > Hint：更全面的 Python 对象模型规则可以在 [官方文档](https://docs.python.org/3/reference/datamodel.html) 找到，有点难读，但值得一读。 337 | 338 | ## 总结 339 | 340 | Python 世界有着一套非常复杂的规则，这些规则的涵盖范围包括“对象与对象是否相等“、”对象与对象谁大谁小”等等。它们大部分都需要通过重新定义“双下划线方法 `__xxx__`” 去实现。 341 | 342 | 如果熟悉这些规则，并在日常编码中活用它们，有助于我们更高效的解决问题、设计出更符合 Python 哲学的 API。下面是本文的一些要点总结： 343 | 344 | - **永远记得对原始需求做抽象分析，比如问题是否能用集合求差集解决** 345 | - 如果要把对象放入集合，需要自定义对象的 `__hash__` 与 `__eq__` 方法 346 | - `__hash__` 方法决定性能（碰撞出现概率），`__eq__` 决定对象间相等逻辑 347 | - 使用 dataclasses 模块可以让你少写很多代码 348 | - 使用 `__format__` 方法替代自己定义的字符串格式化方法 349 | - 在容器类对象上使用 `__len__`、`__getitem__` 方法，而不是自己实现 350 | 351 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 352 | 353 | [>>>下一篇【11.高效操作文件的三个建议】](11-three-tips-on-writing-file-related-codes.md) 354 | 355 | [<<<上一篇【9.一个关于模块的小故事】](9-a-story-on-cyclic-imports.md) 356 | 357 | ## 附录 358 | 359 | - 题图来源: Photo by JESHOOTS.COM on Unsplash 360 | - 更多系列文章地址： 361 | 362 | 系列其他文章： 363 | 364 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 365 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 366 | - [Python 工匠：异常处理的三个好习惯](https://www.piglei.com/articles/three-rituals-of-exceptions-handling/) 367 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 368 | -------------------------------------------------------------------------------- /zh_CN/11-three-tips-on-writing-file-related-codes.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：高效操作文件的三个建议 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 11 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 在这个世界上，人们每天都在用 Python 完成着不同的工作。而文件操作，则是大家最常需要解决的任务之一。使用 Python，你可以轻松为他人生成精美的报表，也可以用短短几行代码快速解析、整理上万份数据文件。 12 | 13 | 当我们编写与文件相关的代码时，通常会关注这些事情：**我的代码是不是足够快？我的代码有没有事半功倍的完成任务？** 在这篇文章中，我会与你分享与之相关的几个编程建议。我会向你推荐一个被低估的 Python 标准库模块、演示一个读取大文件的最佳方式、最后再分享我对函数设计的一点思考。 14 | 15 | 下面，让我们进入第一个“模块安利”时间吧。 16 | 17 | > **注意：**因为不同操作系统的文件系统大不相同，本文的主要编写环境为 Mac OS/Linux 系统，其中一些代码可能并不适用于 Windows 系统。 18 | 19 | ## 建议一：使用 pathlib 模块 20 | 21 | 如果你需要在 Python 里进行文件处理，那么标准库中的 `os` 和 `os.path` 兄弟俩一定是你无法避开的两个模块。在这两个模块里，有着非常多与文件路径处理、文件读写、文件状态查看相关的工具函数。 22 | 23 | 让我用一个例子来展示一下它们的使用场景。有一个目录里装了很多数据文件，但是它们的后缀名并不统一，既有 `.txt`，又有 `.csv`。我们需要把其中以 `.txt` 结尾的文件都修改为 `.csv` 后缀名。 24 | 25 | 我们可以写出这样一个函数： 26 | 27 | ```python 28 | import os 29 | import os.path 30 | 31 | 32 | def unify_ext_with_os_path(path): 33 | """统一目录下的 .txt 文件名后缀为 .csv 34 | """ 35 | for filename in os.listdir(path): 36 | basename, ext = os.path.splitext(filename) 37 | if ext == '.txt': 38 | abs_filepath = os.path.join(path, filename) 39 | os.rename(abs_filepath, os.path.join(path, f'{basename}.csv')) 40 | ``` 41 | 42 | 让我们看看，上面的代码一共用到了哪些与文件处理相关的函数： 43 | 44 | - [`os.listdir(path)`](https://docs.python.org/3/library/os.html#os.listdir)：列出 path 目录下的所有文件*（含文件夹）* 45 | - [`os.path.splitext(filename)`](https://docs.python.org/3/library/os.path.html#os.path.splitext)：切分文件名里面的基础名称和后缀部分 46 | - [`os.path.join(path, filename)`](https://docs.python.org/3/library/os.path.html#os.path.join)：组合需要操作的文件名为绝对路径 47 | - [`os.rename(...)`](https://docs.python.org/3/library/os.html#os.rename)：重命名某个文件 48 | 49 | 上面的函数虽然可以完成需求，但说句实话，即使在写了很多年 Python 代码后，我依然觉得：**这些函数不光很难记，而且最终的成品代码也不怎么讨人喜欢。** 50 | 51 | ### 使用 pathlib 模块改写代码 52 | 53 | 为了让文件处理变得更简单，Python 在 3.4 版本引入了一个新的标准库模块：[pathlib](https://docs.python.org/3/library/pathlib.html)。它基于面向对象思想设计，封装了非常多与文件操作相关的功能。如果使用它来改写上面的代码，结果会大不相同。 54 | 55 | 使用 pathlib 模块后的代码： 56 | 57 | ```python 58 | from pathlib import Path 59 | 60 | def unify_ext_with_pathlib(path): 61 | for fpath in Path(path).glob('*.txt'): 62 | fpath.rename(fpath.with_suffix('.csv')) 63 | ``` 64 | 65 | 和旧代码相比，新函数只需要两行代码就完成了工作。而这两行代码主要做了这么几件事： 66 | 67 | 1. 首先使用 [Path(path)](https://docs.python.org/3/library/pathlib.html#pathlib.Path) 将字符串路径转换为 `Path` 对象 68 | 2. 调用 [.glob('*.txt')](https://docs.python.org/3/library/pathlib.html#pathlib.Path.glob) 对路径下所有内容进行模式匹配并以生成器方式返回，结果仍然是 `Path` 对象，所以我们可以接着做后面的操作 69 | 3. 使用 [.with_suffix('.csv')](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.with_suffix) 直接获取使用新后缀名的文件全路径 70 | 4. 调用 [.rename(target)](https://docs.python.org/3/library/pathlib.html#pathlib.Path.rename) 完成重命名 71 | 72 | 相比 `os` 和 `os.path`，引入 `pathlib` 模块后的代码明显更精简，也更有整体统一感。所有文件相关的操作都是一站式完成。 73 | 74 | ### 其他用法 75 | 76 | 除此之外，pathlib 模块还提供了很多有趣的用法。比如使用 `/` 运算符来组合文件路径： 77 | 78 | ```python 79 | # 😑 旧朋友：使用 os.path 模块 80 | >>> import os.path 81 | >>> os.path.join('/tmp', 'foo.txt') 82 | '/tmp/foo.txt' 83 | 84 | # ✨ 新潮流：使用 / 运算符 85 | >>> from pathlib import Path 86 | >>> Path('/tmp') / 'foo.txt' 87 | PosixPath('/tmp/foo.txt') 88 | ``` 89 | 90 | 或者使用 `.read_text()` 来快速读取文件内容： 91 | 92 | ```python 93 | # 标准做法，使用 with open(...) 打开文件 94 | >>> with open('foo.txt') as file: 95 | ... print(file.read()) 96 | ... 97 | foo 98 | 99 | # 使用 pathlib 可以让这件事情变得更简单 100 | >>> from pathlib import Path 101 | >>> print(Path('foo.txt').read_text()) 102 | foo 103 | 104 | ``` 105 | 106 | 除了我在文章里介绍的这些，pathlib 模块还提供了非常多有用的方法，强烈建议去 [官方文档]((https://docs.python.org/3/library/pathlib.html#module-pathlib)) 详细了解一下。 107 | 108 | 如果上面这些都不足以让你动心，那么我再多给你一个使用 pathlib 的理由：[PEP-519](https://www.python.org/dev/peps/pep-0519/) 里定义了一个专门用于“文件路径”的新对象协议，这意味着从该 PEP 生效后的 Python 3.6 版本起，pathlib 里的 Path 对象，可以和以前绝大多数只接受字符串路径的标准库函数兼容使用： 109 | 110 | ```python 111 | >>> p = Path('/tmp') 112 | # 可以直接对 Path 类型对象 p 进行 join 113 | >>> os.path.join(p, 'foo.txt') 114 | '/tmp/foo.txt' 115 | ``` 116 | 117 | 所以，无需犹豫，赶紧把 pathlib 模块用起来吧。 118 | 119 | > **Hint:** 如果你使用的是更早的 Python 版本，可以尝试安装 [pathlib2](https://pypi.org/project/pathlib2/) 模块 。 120 | 121 | ## 建议二：掌握如何流式读取大文件 122 | 123 | 几乎所有人都知道，在 Python 里读取文件有一种“标准做法”：首先使用 `with open(fine_name)` 上下文管理器的方式获得一个文件对象，然后使用 `for` 循环迭代它，逐行获取文件里的内容。 124 | 125 | 下面是一个使用这种“标准做法”的简单示例函数： 126 | 127 | ```python 128 | def count_nine(fname): 129 | """计算文件里包含多少个数字 '9' 130 | """ 131 | count = 0 132 | with open(fname) as file: 133 | for line in file: 134 | count += line.count('9') 135 | return count 136 | ``` 137 | 138 | 假如我们有一个文件 `small_file.txt`，那么使用这个函数可以轻松计算出 9 的数量。 139 | 140 | ```python 141 | # small_file.txt 142 | feiowe9322nasd9233rl 143 | aoeijfiowejf8322kaf9a 144 | 145 | # OUTPUT: 3 146 | print(count_nine('small_file.txt')) 147 | ``` 148 | 149 | 为什么这种文件读取方式会成为标准？这是因为它有两个好处： 150 | 151 | 1. `with` 上下文管理器会自动关闭打开的文件描述符 152 | 2. 在迭代文件对象时，内容是一行一行返回的，不会占用太多内存 153 | 154 | ### 标准做法的缺点 155 | 156 | 但这套标准做法并非没有缺点。如果被读取的文件里，根本就没有任何换行符，那么上面的第二个好处就不成立了。**当代码执行到 `for line in file` 时，line 将会变成一个非常巨大的字符串对象，消耗掉非常可观的内存。** 157 | 158 | 让我们来做个试验：有一个 **5GB** 大的文件 `big_file.txt`，它里面装满了和 `small_file.txt` 一样的随机字符串。只不过它存储内容的方式稍有不同，所有的文本都被放在了同一行里： 159 | 160 | ```raw 161 | # FILE: big_file.txt 162 | df2if283rkwefh... <剩余 5GB 大小> ... 163 | ``` 164 | 165 | 如果我们继续使用前面的 `count_nine` 函数去统计这个大文件里 `9` 的个数。那么在我的笔记本上，这个过程会足足花掉 **65** 秒，并在执行过程中吃掉机器 **2GB** 内存 [[注1]]((#annot1))。 166 | 167 | ### 使用 read 方法分块读取 168 | 169 | 为了解决这个问题，我们需要暂时把这个“标准做法”放到一边，使用更底层的 `file.read()` 方法。与直接循环迭代文件对象不同，每次调用 `file.read(chunk_size)` 会直接返回从当前位置往后读取 `chunk_size` 大小的文件内容，不必等待任何换行符出现。 170 | 171 | 所以，如果使用 `file.read()` 方法，我们的函数可以改写成这样: 172 | 173 | ```python 174 | def count_nine_v2(fname): 175 | """计算文件里包含多少个数字 '9'，每次读取 8kb 176 | """ 177 | count = 0 178 | block_size = 1024 * 8 179 | with open(fname) as fp: 180 | while True: 181 | chunk = fp.read(block_size) 182 | # 当文件没有更多内容时，read 调用将会返回空字符串 '' 183 | if not chunk: 184 | break 185 | count += chunk.count('9') 186 | return count 187 | ``` 188 | 189 | 在新函数中，我们使用了一个 `while` 循环来读取文件内容，每次最多读取 8kb 大小，这样可以避免之前需要拼接一个巨大字符串的过程，把内存占用降低非常多。 190 | 191 | ### 利用生成器解耦代码 192 | 193 | 假如我们在讨论的不是 Python，而是其他编程语言。那么可以说上面的代码已经很好了。但是如果你认真分析一下 `count_nine_v2` 函数，你会发现在循环体内部，存在着两个独立的逻辑：**数据生成（read 调用与 chunk 判断）** 与 **数据消费**。而这两个独立逻辑被耦合在了一起。 194 | 195 | 正如我在[《编写地道循环》](https://www.piglei.com/articles/two-tips-on-loop-writing/)里所提到的，为了提升复用能力，我们可以定义一个新的 `chunked_file_reader` 生成器函数，由它来负责所有与“数据生成”相关的逻辑。这样 `count_nine_v3` 里面的主循环就只需要负责计数即可。 196 | 197 | ```python 198 | def chunked_file_reader(fp, block_size=1024 * 8): 199 | """生成器函数：分块读取文件内容 200 | """ 201 | while True: 202 | chunk = fp.read(block_size) 203 | # 当文件没有更多内容时，read 调用将会返回空字符串 '' 204 | if not chunk: 205 | break 206 | yield chunk 207 | 208 | 209 | def count_nine_v3(fname): 210 | count = 0 211 | with open(fname) as fp: 212 | for chunk in chunked_file_reader(fp): 213 | count += chunk.count('9') 214 | return count 215 | ``` 216 | 217 | 进行到这一步，代码似乎已经没有优化的空间了，但其实不然。[iter(iterable)](https://docs.python.org/3/library/functions.html#iter) 是一个用来构造迭代器的内建函数，但它还有一个更少人知道的用法。当我们使用 `iter(callable, sentinel)` 的方式调用它时，会返回一个特殊的对象，迭代它将不断产生可调用对象 callable 的调用结果，直到结果为 sentinel 时，迭代终止。 218 | 219 | ```python 220 | def chunked_file_reader(file, block_size=1024 * 8): 221 | """生成器函数：分块读取文件内容，使用 iter 函数 222 | """ 223 | # 首先使用 partial(fp.read, block_size) 构造一个新的无需参数的函数 224 | # 循环将不断返回 fp.read(block_size) 调用结果，直到其为 '' 时终止 225 | for chunk in iter(partial(file.read, block_size), ''): 226 | yield chunk 227 | ``` 228 | 229 | 最终，只需要两行代码，我们就完成了一个可复用的分块文件读取函数。那么，这个函数在性能方面的表现如何呢？ 230 | 231 | 和一开始的 **2GB 内存/耗时 65 秒** 相比，使用生成器的版本只需要 **7MB 内存 / 12 秒** 就能完成计算。效率提升了接近 4 倍，内存占用更是不到原来的 1%。 232 | 233 | ## 建议三：设计接受文件对象的函数 234 | 235 | 统计完文件里的 “9” 之后，让我们换一个需求。现在，我想要统计每个文件里出现了多少个英文元音字母*（aeiou）*。只要对之前的代码稍作调整，很快就可以写出新函数 `count_vowels`。 236 | 237 | ```python 238 | def count_vowels(filename): 239 | """统计某个文件中，包含元音字母(aeiou)的数量 240 | """ 241 | VOWELS_LETTERS = {'a', 'e', 'i', 'o', 'u'} 242 | count = 0 243 | with open(filename, 'r') as fp: 244 | for line in fp: 245 | for char in line: 246 | if char.lower() in VOWELS_LETTERS: 247 | count += 1 248 | return count 249 | 250 | 251 | # OUTPUT: 16 252 | print(count_vowels('small_file.txt')) 253 | ``` 254 | 255 | 和之前“统计 9”的函数相比，新函数变得稍微复杂了一些。为了保证程序的正确性，我需要为它写一些单元测试。但当我准备写测试时，却发现这件事情非常麻烦，主要问题点如下： 256 | 257 | 1. 函数接收文件路径作为参数，所以我们需要传递一个实际存在的文件 258 | 2. 为了准备测试用例，我要么提供几个样板文件，要么写一些临时文件 259 | 3. 而文件是否能被正常打开、读取，也成了我们需要测试的边界情况 260 | 261 | **如果，你发现你的函数难以编写单元测试，那通常意味着你应该改进它的设计**。上面的函数应该如何改进呢？答案是：*让函数依赖“文件对象”而不是文件路径*。 262 | 263 | 修改后的函数代码如下： 264 | 265 | ```python 266 | def count_vowels_v2(fp): 267 | """统计某个文件中，包含元音字母(aeiou)的数量 268 | """ 269 | VOWELS_LETTERS = {'a', 'e', 'i', 'o', 'u'} 270 | count = 0 271 | for line in fp: 272 | for char in line: 273 | if char.lower() in VOWELS_LETTERS: 274 | count += 1 275 | return count 276 | 277 | 278 | # 修改函数后，打开文件的职责被移交给了上层函数调用者 279 | with open('small_file.txt') as fp: 280 | print(count_vowels_v2(fp)) 281 | ``` 282 | 283 | **这个改动带来的主要变化，在于它提升了函数的适用面**。因为 Python 是“鸭子类型”的，虽然函数需要接受文件对象，但其实我们可以把任何实现了文件协议的 “类文件对象（file-like object）” 传入 `count_vowels_v2` 函数中。 284 | 285 | 而 Python 中有着非常多“类文件对象”。比如 io 模块内的 [StringIO](https://docs.python.org/3/library/io.html#io.StringIO) 对象就是其中之一。它是一种基于内存的特殊对象，拥有和文件对象几乎一致的接口设计。 286 | 287 | 利用 StringIO，我们可以非常方便的为函数编写单元测试。 288 | 289 | ```python 290 | # 注意：以下测试函数需要使用 pytest 执行 291 | import pytest 292 | from io import StringIO 293 | 294 | 295 | @pytest.mark.parametrize( 296 | "content,vowels_count", [ 297 | # 使用 pytest 提供的参数化测试工具，定义测试参数列表 298 | # (文件内容, 期待结果) 299 | ('', 0), 300 | ('Hello World!', 3), 301 | ('HELLO WORLD!', 3), 302 | ('你好，世界', 0), 303 | ] 304 | ) 305 | def test_count_vowels_v2(content, vowels_count): 306 | # 利用 StringIO 构造类文件对象 "file" 307 | file = StringIO(content) 308 | assert count_vowels_v2(file) == vowels_count 309 | ``` 310 | 311 | 使用 pytest 运行测试可以发现，函数可以通过所有的用例： 312 | 313 | ```raw 314 | ❯ pytest vowels_counter.py 315 | ====== test session starts ====== 316 | collected 4 items 317 | 318 | vowels_counter.py ... [100%] 319 | 320 | ====== 4 passed in 0.06 seconds ====== 321 | ``` 322 | 323 | 而让编写单元测试变得更简单，并非修改函数依赖后的唯一好处。除了 StringIO 外，subprocess 模块调用系统命令时用来存储标准输出的 [PIPE](https://docs.python.org/3/library/subprocess.html#subprocess.PIPE) 对象，也是一种“类文件对象”。这意味着我们可以直接把某个命令的输出传递给 `count_vowels_v2` 函数来计算元音字母数： 324 | 325 | ```python 326 | import subprocess 327 | 328 | # 统计 /tmp 下面所有一级子文件名（目录名）有多少元音字母 329 | p = subprocess.Popen(['ls', '/tmp'], stdout=subprocess.PIPE, encoding='utf-8') 330 | 331 | # p.stdout 是一个流式类文件对象，可以直接传入函数 332 | # OUTPUT: 42 333 | print(count_vowels_v2(p.stdout)) 334 | ``` 335 | 336 | 正如之前所说，将函数参数修改为“文件对象”，最大的好处是提高了函数的 **适用面** 和 **可组合性**。通过依赖更为抽象的“类文件对象”而非文件路径，给函数的使用方式开启了更多可能，StringIO、PIPE 以及任何其他满足协议的对象都可以成为函数的客户。 337 | 338 | 不过，这样的改造并非毫无缺点，它也会给调用方带来一些不便。假如调用方就是想要使用文件路径，那么就必须得自行处理文件的打开操作。 339 | 340 | ### 如何编写兼容二者的函数 341 | 342 | 有没有办法即拥有“接受文件对象”的灵活性，又能让传递文件路径的调用方更方便？答案是：*有，而且标准库中就有这样的例子。* 343 | 344 | 打开标准库里的 `xml.etree.ElementTree` 模块，翻开里面的 `ElementTree.parse` 方法。你会发现这个方法即可以使用文件对象调用，也接受字符串的文件路径。而它实现这一点的手法也非常简单易懂： 345 | 346 | ``` 347 | def parse(self, source, parser=None): 348 | """*source* is a file name or file object, *parser* is an optional parser 349 | """ 350 | close_source = False 351 | # 通过判断 source 是否有 "read" 属性来判定它是不是“类文件对象” 352 | # 如果不是，那么调用 open 函数打开它并负担起在函数末尾关闭它的责任 353 | if not hasattr(source, "read"): 354 | source = open(source, "rb") 355 | close_source = True 356 | ``` 357 | 358 | 使用这种基于“鸭子类型”的灵活检测方式，`count_vowels_v2` 函数也同样可以被改造得更方便，我在这里就不再重复啦。 359 | 360 | ## 总结 361 | 362 | 文件操作我们在日常工作中经常需要接触的领域，使用更方便的模块、利用生成器节约内存以及编写适用面更广的函数，可以让我们编写出更高效的代码。 363 | 364 | 让我们最后再总结一下吧： 365 | 366 | - 使用 pathlib 模块可以简化文件和目录相关的操作，并让代码更直观 367 | - [PEP-519](https://www.python.org/dev/peps/pep-0519/) 定义了表示“文件路径”的标准协议，Path 对象实现了这个协议 368 | - 通过定义生成器函数来分块读取大文件可以节约内存 369 | - 使用 `iter(callable, sentinel)` 可以在一些特定场景简化代码 370 | - 难以编写测试的代码，通常也是需要改进的代码 371 | - 让函数依赖“类文件对象”可以提升函数的适用面和可组合性 372 | 373 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 374 | 375 | [>>>下一篇【12.写好面向对象代码的原则（上）】](12-write-solid-python-codes-part-1.md) 376 | 377 | [<<<上一篇【10.做一个精通规则的玩家】](10-a-good-player-know-the-rules.md) 378 | 379 | ## 附录 380 | 381 | - 题图来源: Photo by Devon Divine on Unsplash 382 | - 更多系列文章地址： 383 | 384 | 系列其他文章： 385 | 386 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 387 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 388 | - [Python 工匠：异常处理的三个好习惯](https://www.piglei.com/articles/three-rituals-of-exceptions-handling/) 389 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 390 | 391 | ## 注解 392 | 393 | 1. 视机器空闲内存的多少，这个过程可能会消耗比 2GB 更多的内存。 394 | -------------------------------------------------------------------------------- /zh_CN/12-write-solid-python-codes-part-1.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：写好面向对象代码的原则（上） 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 12 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | Python 是一门支持多种编程风格的语言，面对相同的需求，拥有不同背景的程序员可能会写出风格迥异的 Python 代码。比如一位习惯编写 C 语言的程序员，通常会定义一大堆函数来搞定所有事情，这是[“过程式编程”](https://en.wikipedia.org/wiki/Procedural_programming)的思想。而一位有 Java 背景的程序员则更倾向于设计许多个相互关联的类*（class）*，这是 [“面向对象编程（后简称 OOP）”](https://en.wikipedia.org/wiki/Object-oriented_programming)。 12 | 13 | 虽然不同的编程风格各有特点，无法直接比较。但是 OOP 思想在现代软件开发中起到的重要作用应该是毋庸置疑的。 14 | 15 | 很多人在学习如何写好 OOP 代码时，会选择从那 [23 种经典的“设计模式”](https://zh.wikipedia.org/wiki/%E8%AE%BE%E8%AE%A1%E6%A8%A1%E5%BC%8F_(%E8%AE%A1%E7%AE%97%E6%9C%BA))开始。不过对于 Python 程序员来说，我认为这并非是一个最佳选择。 16 | 17 | ### Python 对 OOP 的支持 18 | 19 | Python 语言虽然拥有类、继承、多态等核心 OOP 特性，但和那些完全基于 OOP 思想设计的编程语言*（比如 Java）*相比，它在 OOP 支持方面做了很多简化工作。比如它 **没有严格的类私有成员，没有接口（Interface）对象** 等。 20 | 21 | 而与此同时，Python 灵活的函数对象、鸭子类型等许多动态特性又让一些在其他语言中很难做到的事情变得非常简单。这些语言间的差异共同导致了一个结果：*很多经典的设计模式到了 Python 里，就丢失了那个“味道”，实用性也大打折扣。* 22 | 23 | 拿大家最熟悉的单例模式来说。你可以花上一大把时间，来学习如何在 Python 中利用 `__new__` 方法或元类*（metaclass）*来实现单例设计模式，但最后你会发现，自己 95% 的需求都可以通过直接定义一个模块级全局变量来搞定。 24 | 25 | 所以，与具体化的 **设计模式** 相比，我觉得一些更为抽象的 **设计原则** 适用性更广、更适合运用到 Python 开发工作中。而谈到关于 OOP 的设计原则，“SOLID” 是众多原则中最有名的一个。 26 | 27 | ### SOLID 设计原则 28 | 29 | 著名的设计模式书籍[《设计模式：可复用面向对象软件的基础》](https://book.douban.com/subject/1052241/)出版于 1994 年，距今已有超过 25 年的历史。而这篇文章的主角： “SOLID 设计原则”同样也并不年轻。 30 | 31 | 早在 2000 年，[Robert C. Martin](https://en.wikipedia.org/wiki/Robert_C._Martin) 就在他的文章 "Design Principles and Design Patterns" 中整理并提出了 “SOLID” 设计原则的雏型，之后又在他的经典著作[《敏捷软件开发 : 原则、模式与实践》](https://book.douban.com/subject/1140457/)中将其发扬光大。“SOLID” 由 5 个单词组合的首字母缩写组成，分别代表 5 条不同的面向对象领域的设计原则。 32 | 33 | 在编写 OOP 代码时，如果遵循这 5 条设计原则，就更可能写出可扩展、易于修改的代码。相反，如果不断违反其中的一条或多条原则，那么很快你的代码就会变得不可扩展、难以维护。 34 | 35 | 接下来，让我用一个真实的 Python 代码样例来分别向你诠释这 5 条设计原则。 36 | 37 | > 写在最前面的注意事项： 38 | > 39 | > 0. “原则”不是“法律”，它只起到指导作用，并非不可以违反 40 | > 1. “原则”的后两条与接口（Interface）有关，而 Python 没有接口，所以对这部分的诠释是我的个人理解，与原版可能略有出入 41 | > 2. 文章后面的内容含有大量代码，请做好心理准备 ☕️ 42 | > 3. 为了增强代码的说明性，本文中的代码使用了 Python3 中的 [类型注解特性](https://docs.python.org/3/library/typing.html) 43 | 44 | ## SOLID 原则与 Python 45 | 46 | [Hacker News](https://news.ycombinator.com/)*(后简称 HN)* 是一个在程序员圈子里很受欢迎的站点。在它的首页，有很多由用户提交后基于推荐算法排序的科技相关内容。 47 | 48 | 我经常会去上面看一些热门文章，但我觉得每次打开浏览器访问有点麻烦。所以，我准备编写一个脚本，自动抓取 HN 首页 Top5 的新闻标题与链接，并用纯文本的方式写入到文件。方便自己用其他工具阅读。 49 | 50 |
51 | 52 | 图：Hacker News 首页截图 53 |
54 | 55 | 编写爬虫几乎是 Python 天生的拿手好戏。利用 requests、lxml 等模块提供的好用功能，我可以轻松实现上面的需求。下面是我第一次编写好的代码： 56 | 57 | ```python 58 | import io 59 | import sys 60 | from typing import Generator 61 | 62 | import requests 63 | from lxml import etree 64 | 65 | 66 | class Post: 67 | """HN(https://news.ycombinator.com/) 上的条目 68 | 69 | :param title: 标题 70 | :param link: 链接 71 | :param points: 当前得分 72 | :param comments_cnt: 评论数 73 | """ 74 | def __init__(self, title: str, link: str, points: str, comments_cnt: str): 75 | self.title = title 76 | self.link = link 77 | self.points = int(points) 78 | self.comments_cnt = int(comments_cnt) 79 | 80 | 81 | class HNTopPostsSpider: 82 | """抓取 HackerNews Top 内容条目 83 | 84 | :param fp: 存储抓取结果的目标文件对象 85 | :param limit: 限制条目数，默认为 5 86 | """ 87 | ITEMS_URL = 'https://news.ycombinator.com/' 88 | FILE_TITLE = 'Top news on HN' 89 | 90 | def __init__(self, fp: io.TextIOBase, limit: int = 5): 91 | self.fp = fp 92 | self.limit = limit 93 | 94 | def fetch(self) -> Generator[Post, None, None]: 95 | """从 HN 抓取 Top 内容 96 | """ 97 | resp = requests.get(self.ITEMS_URL) 98 | 99 | # 使用 XPath 可以方便的从页面解析出你需要的内容，以下均为页面解析代码 100 | # 如果你对 xpath 不熟悉，可以忽略这些代码，直接跳到 yield Post() 部分 101 | html = etree.HTML(resp.text) 102 | items = html.xpath('//table[@class="itemlist"]/tr[@class="athing"]') 103 | for item in items[:self.limit]: 104 | node_title = item.xpath('./td[@class="title"]/a')[0] 105 | node_detail = item.getnext() 106 | points_text = node_detail.xpath('.//span[@class="score"]/text()') 107 | comments_text = node_detail.xpath('.//td/a[last()]/text()')[0] 108 | 109 | yield Post( 110 | title=node_title.text, 111 | link=node_title.get('href'), 112 | # 条目可能会没有评分 113 | points=points_text[0].split()[0] if points_text else '0', 114 | comments_cnt=comments_text.split()[0] 115 | ) 116 | 117 | def write_to_file(self): 118 | """以纯文本格式将 Top 内容写入文件 119 | """ 120 | self.fp.write(f'# {self.FILE_TITLE}\n\n') 121 | # enumerate 接收第二个参数，表示从这个数开始计数（默认为 0） 122 | for i, post in enumerate(self.fetch(), 1): 123 | self.fp.write(f'> TOP {i}: {post.title}\n') 124 | self.fp.write(f'> 分数：{post.points} 评论数：{post.comments_cnt}\n') 125 | self.fp.write(f'> 地址：{post.link}\n') 126 | self.fp.write('------\n') 127 | 128 | 129 | def main(): 130 | 131 | # with open('/tmp/hn_top5.txt') as fp: 132 | # crawler = HNTopPostsSpider(fp) 133 | # crawler.write_to_file() 134 | 135 | # 因为 HNTopPostsSpider 接收任何 file-like 的对象，所以我们可以把 sys.stdout 传进去 136 | # 实现往控制台标准输出打印的功能 137 | crawler = HNTopPostsSpider(sys.stdout) 138 | crawler.write_to_file() 139 | 140 | 141 | if __name__ == '__main__': 142 | main() 143 | ``` 144 | 145 | 你可以把上面的代码称之为符合 OOP 风格的，因为在上面的代码里，我定义了两个类： 146 | 147 | 1. `Post`：表示单个 HN 内容条目，其中定义了标题、链接等字段，是用来衔接“抓取”和“写入文件”两件事情的数据类 148 | 2. `HNTopPostsSpider`：抓取 HN 内容的爬虫类，其中定义了抓取页面、解析、写入结果的方法，是完成主要工作的类 149 | 150 | 如果你本地的 Python 环境配置正常，那么可以尝试执行一下上面这段代码，它会输出下面这样的内容： 151 | 152 | ```text 153 | ❯ python news_digester.py 154 | > TOP 1: Show HN: NoAgeismInTech – Job board for companies fighting ageism in tech 155 | > 分数：104 评论数：26 156 | > 地址：https://noageismintech.com/ 157 | ------ 158 | > TOP 2: Magic Leap sues former employee who founded the China-based Nreal for IP theft 159 | > 分数：17 评论数：2 160 | > 地址：https://www.bloomberg.com/news/articles/2019-06-18/secretive-magic-leap-says-ex-engineer-copied-headset-for-china 161 | ------ 162 | ... ... 163 | ``` 164 | 165 | 这个脚本基于面向对象的方式编写*（换句话说，就是定义了一些 class 😒）*，可以满足我的需求。但是从设计的角度来看，它却违反了 SOLID 原则的第一条：“Single responsibility principle（单一职责原则）”，让我们来看看是为什么。 166 | 167 | ## S：单一职责原则 168 | 169 | SOLID 设计原则里的第一个字母 S 来自于 “Single responsibility principle（单一职责原则）” 的首字母。这个原则认为：**“一个类应该仅仅只有一个被修改的理由。”** 换句话说，每个类都应该只有一种职责。 170 | 171 | 而在上面的代码中，`HNTopPostsSpider` 这个类违反了这个原则。因为我们可以很容易的找到两个不同的修改它的理由： 172 | 173 | - **理由 1**: HN 网站的程序员突然更新了页面样式，旧的 xpath 解析算法从新页面上解析不到内容，需要修改 `fetch` 方法内的解析逻辑。 174 | - **理由 2**: 用户*（也就是我）*突然觉得纯文本格式的输出不好看，想要改成 Markdown 样式。需要修改 `write_to_file` 方法内的输出逻辑。 175 | 176 | 所以，`HNTopPostsSpider` 类违反了“单一职责原则”，因为它有着多个被修改的理由。而这背后的根本原因是因为它承担着 “抓取帖子列表” 和 "将帖子列表写入文件" 这两种完全不同的职责。 177 | 178 | ### 违反“单一职责原则”的坏处 179 | 180 | 如果某个类违反了“单一职责原则”，那意味着我们经常会因为不同的原因去修改它。这可能会导致不同功能之间相互影响。比如，可能我在某天调整了页面解析逻辑，却发现输出的文件格式也全部乱掉了。 181 | 182 | 另外，单个类承担的职责越多，意味着这个类的复杂度也就越高，它的维护成本也同样会水涨船高。违反“单一职责原则”的类同样也难以被复用，假如我有其他代码想复用 `HNTopPostsSpider` 类的抓取和解析逻辑，会发现我必须要提供一个莫名其妙的文件对象给它才行。 183 | 184 | 那么，要如何修改代码才能让它遵循“单一职责原则”呢？办法有很多，最传统的是：**把大类拆分为小类**。 185 | 186 | ### 拆分大类为多个小类 187 | 188 | 为了让 `HNTopPostsSpider` 类的职责更纯粹，我们可以把其中与“写入文件”相关的内容拆分出去作为一个新的类： 189 | 190 | ```python 191 | class PostsWriter: 192 | """负责将帖子列表写入到文件 193 | """ 194 | def __init__(self, fp: io.TextIOBase, title: str): 195 | self.fp = fp 196 | self.title = title 197 | 198 | def write(self, posts: List[Post]): 199 | self.fp.write(f'# {self.title}\n\n') 200 | # enumerate 接收第二个参数，表示从这个数开始计数（默认为 0） 201 | for i, post in enumerate(posts, 1): 202 | self.fp.write(f'> TOP {i}: {post.title}\n') 203 | self.fp.write(f'> 分数：{post.points} 评论数：{post.comments_cnt}\n') 204 | self.fp.write(f'> 地址：{post.link}\n') 205 | self.fp.write('------\n') 206 | ``` 207 | 208 | 而在 `HNTopPostsSpider` 类里，可以通过调用 `PostsWriter` 的方式来完成之前的工作： 209 | 210 | ```python 211 | class HNTopPostsSpider: 212 | FILE_TITLE = 'Top news on HN' 213 | 214 | <... 已省略 ...> 215 | 216 | def write_to_file(self, fp: io.TextIOBase): 217 | """以纯文本格式将 Top 内容写入文件 218 | 219 | 实例化参数文件对象 fp 被挪到了 write_to_file 方法中 220 | """ 221 | # 将文件写入逻辑托管给 PostsWriter 类处理 222 | writer = PostsWriter(fp, title=self.FILE_TITLE) 223 | writer.write(list(self.fetch())) 224 | ``` 225 | 226 | 通过这种方式，我们让 `HNTopPostsSpider` 和 `PostsWriter` 类都各自满足了“单一职责原则”。我只会因为解析逻辑变动才去修改 `HNTopPostsSpider` 类，同样，修改 `PostsWriter` 类的原因也只有调整输出格式一种。这两个类各自的修改可以单独进行而不会相互影响。 227 | 228 | ### 另一种方案：使用函数 229 | 230 | “单一职责原则”虽然是针对类说的，但其实它的适用范围可以超出类本身。比如在 Python 中，通过定义函数，同样也可以让上面的代码符合单一职责原则。 231 | 232 | 我们可以把“写入文件”的逻辑拆分为一个新的函数，由它来专门承担起将帖子列表写入文件的职责： 233 | 234 | ```python 235 | def write_posts_to_file(posts: List[Post], fp: io.TextIOBase, title: str): 236 | """负责将帖子列表写入文件 237 | """ 238 | fp.write(f'# {title}\n\n') 239 | for i, post in enumerate(posts, 1): 240 | fp.write(f'> TOP {i}: {post.title}\n') 241 | fp.write(f'> 分数：{post.points} 评论数：{post.comments_cnt}\n') 242 | fp.write(f'> 地址：{post.link}\n') 243 | fp.write('------\n') 244 | ``` 245 | 246 | 而对于 `HNTopPostsSpider` 类来说，改动可以更进一步。这次我们可以直接删除其中和文件写入相关的所有代码。让它只负责一件事情：“获取帖子列表”。 247 | 248 | ```python 249 | class HNTopPostsSpider: 250 | """抓取 HackerNews Top 内容条目 251 | 252 | :param limit: 限制条目数，默认为 5 253 | """ 254 | ITEMS_URL = 'https://news.ycombinator.com/' 255 | 256 | def __init__(self, limit: int = 5): 257 | self.limit = limit 258 | 259 | def fetch(self) -> Generator[Post, None, None]: 260 | # <... 已省略 ...> 261 | ``` 262 | 263 | 相应的，类和函数的调用方 `main` 函数就需要稍作调整，它需要负责把 `write_posts_to_file` 函数和 `HNTopPostsSpider` 类之间协调起来，共同完成工作： 264 | 265 | ```python 266 | def main(): 267 | crawler = HNTopPostsSpider() 268 | 269 | posts = list(crawler.fetch()) 270 | file_title = 'Top news on HN' 271 | write_posts_to_file(posts, sys.stdout, file_title) 272 | ``` 273 | 274 | 将“文件写入”职责拆分为新函数是一个 Python 特色的解决方案，它虽然没有那么 OO *（面向对象）*，但是同样满足“单一职责原则”，而且在很多场景下更灵活与高效。 275 | 276 | ## O：开放-关闭原则 277 | 278 | O 来自于 “Open–closed principle（开放-关闭原则）” 的首字母，它认为：**“类应该对扩展开放，对修改封闭。”**这是一个从字面上很难理解的原则，它同样有着另外一种说法：**“你应该可以在不修改某个类的前提下，扩展它的行为。”** 279 | 280 | 这原则听上去有点让人犯迷糊，如何能做到不修改代码又改变行为呢？让我来举一个例子：你知道 Python 里的内置排序函数 `sorted` 吗？ 281 | 282 | 如果我们想对某个列表排序，可以直接调用 `sorted` 函数： 283 | 284 | ```python 285 | >>> l = [5, 3, 2, 4, 1] 286 | >>> sorted(l) 287 | [1, 2, 3, 4, 5] 288 | ``` 289 | 290 | 现在，假如我们想改变 `sorted` 函数的排序逻辑。比如，让它使用所有元素对 3 取余后的结果来排序。我们是不是需要去修改 `sorted` 函数的源码？当然不用，只需要在调用 `sort` 函数时，传入自定义的排序函数 `key` 参数就行了： 291 | 292 | ```python 293 | >>> l = [8, 1, 9] 294 | # 按照元素对 3 的余数排序，能被 3 整除的 9 排在了最前面，随后是 1 和 8 295 | >>> sorted(l, key=lambda i: i % 3) 296 | [9, 1, 8] 297 | ``` 298 | 299 | 通过上面的例子，我们可以认为：`sorted` 函数是一个符合“开放-关闭原则”的绝佳例子，因为它： 300 | 301 | - **对扩展开放**：你可以通过传入自定义 `key` 函数来扩展它的行为 302 | - **对修改关闭**：你无需修改 sort 函数本身 303 | 304 | ### 如何违反“开放-关闭原则” 305 | 306 | 现在，让我们回到爬虫小程序。在使用了一段时间之后，用户*（还是我）*觉得每次抓取到的内容有点不合口味。我其实只关注那些来自特定网站，比如 github 上的内容。所以我需要修改 `HNTopPostsSpider` 类的代码来对结果进行过滤： 307 | 308 | ```python 309 | class HNTopPostsSpider: 310 | # <... 已省略 ...> 311 | 312 | def fetch(self) -> Generator[Post, None, None]: 313 | # <... 已省略 ...> 314 | counter = 0 315 | for item in items: 316 | if counter >= self.limit: 317 | break 318 | 319 | # <... 已省略 ...> 320 | link = node_title.get('href') 321 | 322 | # 只关注来自 github.com 的内容 323 | if 'github' in link.lower(): 324 | counter += 1 325 | yield Post(... ...) 326 | ``` 327 | 328 | 完成修改后，让我们来简单测试一下效果： 329 | 330 | ```text 331 | ❯ python news_digester_O_before.py 332 | # Top news on HN 333 | 334 | > TOP 1: Mimalloc – A compact general-purpose allocator 335 | > 分数：291 评论数：40 336 | > 地址：https://github.com/microsoft/mimalloc 337 | ------ 338 | > TOP 2: Olivia: An open source chatbot build with a neural network in Go 339 | > 分数：53 评论数：19 340 | > 地址：https://github.com/olivia-ai/olivia 341 | ------ 342 | <... 已省略 ...> 343 | ``` 344 | 345 | 看上去新加的过滤代码起到了作用，现在只有链接中含有 `github` 的内容才会被写入到结果中。 346 | 347 | 但是，正如某位哲学家的名言所说：*“这世间唯一不变的，只有变化本身。”*某天，用户*（永远是我）*突然觉得，来自 `bloomberg` 的内容也都很有意思，所以我想要把 `bloomberg` 也加入筛选关键字逻辑里。 348 | 349 | 这时我们就会发现：现在的代码违反了"开放-关闭原则"。因为我必须要修改现有的 `HNTopPostsSpider` 类代码，调整那个 `if 'github' in link.lower()` 判断语句才能完成我的需求。 350 | 351 | “开放-关闭原则”告诉我们，类应该通过扩展而不是修改的方式改变自己的行为。那么我应该如何调整代码，让它可以遵循原则呢？ 352 | 353 | ### 使用类继承来改造代码 354 | 355 | 继承是面向对象理论中最重要的概念之一。它允许我们在父类中定义好数据和方法，然后通过继承的方式让子类获得这些内容，并可以选择性的对其中一些进行重写，修改它的行为。 356 | 357 | 使用继承的方式来让类遵守“开放-关闭原则”的关键点在于：**找到父类中会变动的部分，将其抽象成新的方法（或属性），最终允许新的子类来重写它以改变类的行为。** 358 | 359 | 对于 `HNTopPostsSpider` 类来说。首先，我们需要找到其中会变动的那部分逻辑，也就是*“判断是否对条目感兴趣”*，然后将其抽象出来，定义为新的方法： 360 | 361 | ```python 362 | class HNTopPostsSpider: 363 | # <... 已省略 ...> 364 | 365 | def fetch(self) -> Generator[Post, None, None]: 366 | # <... 已省略 ...> 367 | for item in items: 368 | # <... 已省略 ...> 369 | 370 | post = Post( ... ... ) 371 | # 使用测试方法来判断是否返回该帖子 372 | if self.interested_in_post(post): 373 | counter += 1 374 | yield post 375 | 376 | def interested_in_post(self, post: Post) -> bool: 377 | """判断是否应该将帖子加入结果中 378 | """ 379 | return True 380 | ``` 381 | 382 | 如果我们只关心来自 `github` 的帖子，那么只需要定义一个继承于 `HNTopPostsSpider` 子类，然后重写父类的 `interested_in_post` 方法即可。 383 | 384 | ```python 385 | class GithubOnlyHNTopPostsSpider(HNTopPostsSpider): 386 | """只关心来自 Github 的内容 387 | """ 388 | def interested_in_post(self, post: Post) -> bool: 389 | return 'github' in post.link.lower() 390 | 391 | def main(): 392 | # crawler = HNTopPostsSpider() 393 | # 使用新的子类 394 | crawler = GithubOnlyHNTopPostsSpider() 395 | <... ...> 396 | ``` 397 | 398 | 假如我们的兴趣发生了变化？没关系，增加新的子类就行： 399 | 400 | ```python 401 | class GithubNBloomBergHNTopPostsSpider(HNTopPostsSpider): 402 | """只关系来自 Github/BloomBerg 的内容 403 | """ 404 | def interested_in_post(self, post: Post) -> bool: 405 | if 'github' in post.link.lower() \ 406 | or 'bloomberg' in post.link.lower(): 407 | return True 408 | return False 409 | ``` 410 | 411 | 所有的这一切，都不需要修改原本的 `HNTopPostsSpider` 类的代码，只需要不断在它的基础上创建新的子类就能完成新需求。最终实现了对扩展开放、对改变关闭。 412 | 413 | ### 使用组合与依赖注入来改造代码 414 | 415 | 虽然类的继承特性很强大，但它并非唯一办法，[依赖注入（Dependency injection）](https://en.wikipedia.org/wiki/Dependency_injection) 是解决这个问题的另一种思路。与继承不同，依赖注入允许我们在类实例化时，通过参数将业务逻辑的变化点：**帖子过滤算法** 注入到类实例中。最终同样实现“开放-关闭原则”。 416 | 417 | 首先，我们定义一个名为 `PostFilter` 的抽象类： 418 | 419 | ```python 420 | from abc import ABC, abstractmethod 421 | 422 | class PostFilter(metaclass=ABCMeta): 423 | """抽象类：定义如何过滤帖子结果 424 | """ 425 | @abstractmethod 426 | def validate(self, post: Post) -> bool: 427 | """判断帖子是否应该被保留""" 428 | ``` 429 | 430 | > Hint：定义抽象类在 Python 的 OOP 中并不是必须的，你也可以不定义它，直接从下面的 DefaultPostFilter 开始。 431 | 432 | 然后定义一个继承于该抽象类的默认 `DefaultPostFilter` 类，过滤逻辑为保留所有结果。之后再调整一下 `HNTopPostsSpider` 类的构造方法，让它接收一个名为 `post_filter` 的结果过滤器： 433 | 434 | ```python 435 | class DefaultPostFilter(PostFilter): 436 | """保留所有帖子 437 | """ 438 | def validate(self, post: Post) -> bool: 439 | return True 440 | 441 | 442 | class HNTopPostsSpider: 443 | """抓取 HackerNews Top 内容条目 444 | 445 | :param limit: 限制条目数，默认为 5 446 | :param post_filter: 过滤结果条目的算法，默认为保留所有 447 | """ 448 | ITEMS_URL = 'https://news.ycombinator.com/' 449 | 450 | def __init__(self, limit: int = 5, post_filter: Optional[PostFilter] = None): 451 | self.limit = limit 452 | self.post_filter = post_filter or DefaultPostFilter() 453 | 454 | def fetch(self) -> Generator[Post, None, None]: 455 | # <... 已省略 ...> 456 | for item in items: 457 | # <... 已省略 ...> 458 | 459 | post = Post( ... ... ) 460 | 461 | # 使用测试方法来判断是否返回该帖子 462 | if self.post_filter.validate(post): 463 | counter += 1 464 | yield post 465 | ``` 466 | 467 | 默认情况下，`HNTopPostsSpider.fetch` 会保留所有的结果。假如我们想要定义自己的过滤算法，只要新建自己的 `PostFilter` 类即可，下面是两个分别过滤 GitHub 与 BloomBerg 的 `PostFilter` 类： 468 | 469 | ``` 470 | class GithubPostFilter(PostFilter): 471 | def validate(self, post: Post) -> bool: 472 | return 'github' in post.link.lower() 473 | 474 | 475 | class GithubNBloomPostFilter(PostFilter): 476 | def validate(self, post: Post) -> bool: 477 | if 'github' in post.link.lower() or 'bloomberg' in post.link.lower(): 478 | return True 479 | return False 480 | ``` 481 | 482 | 在 `main()` 函数中，我可以用不同的 `post_filter` 参数来实例化 `HNTopPostsSpider` 类，最终满足不同的过滤需求： 483 | 484 | ```python 485 | def main(): 486 | # crawler = HNTopPostsSpider() 487 | # crawler = HNTopPostsSpider(post_filter=GithubPostFilter()) 488 | crawler = HNTopPostsSpider(post_filter=GithubNBloomPostFilter()) 489 | 490 | posts = list(crawler.fetch()) 491 | file_title = 'Top news on HN' 492 | write_posts_to_file(posts, sys.stdout, file_title) 493 | ``` 494 | 495 | 与基于继承的方式一样，利用将“过滤算法”抽象为 `PostFilter` 类并以实例化参数的方式注入到 `HNTopPostsSpider` 中，我们同样实现了“开放-关闭原则”。 496 | 497 | ### 使用数据驱动思想来改造代码 498 | 499 | 在实现“开放-关闭”原则的众多手法中，除了继承与依赖注入外，还有一种经常被用到的方式：**“数据驱动”**。这个方式的核心思想在于：**将经常变动的东西，完全以数据的方式抽离出来。当需求变动时，只改动数据，代码逻辑保持不动。** 500 | 501 | 它的原理与“依赖注入”有一些相似，同样是把变化的东西抽离到类外部。不同的是，后者抽离的通常是类，而前者抽离的是数据。 502 | 503 | 为了让 `HNTopPostsSpider` 类的行为可以被数据驱动，我们需要使其接收 `filter_by_link_keywords` 参数： 504 | 505 | ```python 506 | class HNTopPostsSpider: 507 | """抓取 HackerNews Top 内容条目 508 | 509 | :param limit: 限制条目数，默认为 5 510 | :param filter_by_link_keywords: 过滤结果的关键词列表，默认为 None 不过滤 511 | """ 512 | ITEMS_URL = 'https://news.ycombinator.com/' 513 | 514 | def __init__(self, 515 | limit: int = 5, 516 | filter_by_link_keywords: Optional[List[str]] = None): 517 | self.limit = limit 518 | self.filter_by_link_keywords = filter_by_link_keywords 519 | 520 | def fetch(self) -> Generator[Post, None, None]: 521 | # <... 已省略 ...> 522 | for item in items: 523 | # <... 已省略 ...> 524 | 525 | post = Post( ... ... ) 526 | 527 | if self.filter_by_link_keywords is None: 528 | counter += 1 529 | yield post 530 | # 当 link 中出现任意一个关键词时，返回结果 531 | elif any(keyword in post.link for keyword in self.filter_by_link_keywords): 532 | counter += 1 533 | yield post 534 | ``` 535 | 536 | 调整了初始化参数后，还需要在 `main` 函数中定义 `link_keywords` 变量并将其传入到 `HNTopPostsSpider` 类的构造方法中，之后所有针对过滤关键词的调整都只需要修改这个列表即可，无需改动 `HNTopPostsSpider` 类的代码，同样满足了“开放-关闭原则”。 537 | 538 | ```python 539 | def main(): 540 | # link_keywords = None 541 | link_keywords = [ 542 | 'github.com', 543 | 'bloomberg.com' 544 | ] 545 | crawler = HNTopPostsSpider(filter_by_link_keywords=link_keywords) 546 | 547 | posts = list(crawler.fetch()) 548 | file_title = 'Top news on HN' 549 | write_posts_to_file(posts, sys.stdout, file_title) 550 | ``` 551 | 552 | 与前面的继承和依赖注入方式相比，“数据驱动”的代码更简洁，不需要定义额外的类。但它同样也存在缺点：**它的可定制性不如前面的两种方式**。假如，我想要以“链接是否以某个字符串结尾”作为新的过滤条件，那么现在的数据驱动代码就有心无力了。 553 | 554 | 如何选择合适的方式来让代码符合“开放-关闭原则”，需要根据具体的需求和场景来判断。这也是一个无法一蹴而就、需要大量练习和经验积累的过程。 555 | 556 | ## 总结 557 | 558 | 在这篇文章中，我通过一个具体的 Python 代码案例，向你描述了 “SOLID” 设计原则中的前两位成员：**“单一职责原则”** 与 **“开放-关闭原则”**。 559 | 560 | 这两个原则虽然看上去很简单，但是它们背后蕴藏了许多从好代码中提炼而来的智慧。它们的适用范围也不仅仅局限在 OOP 中。一旦你深入理解它们后，你可能会惊奇的在许多设计模式和框架中发现它们的影子 *（比如这篇文章就出现了至少 3 种设计模式，你知道是哪些吗？）*。 561 | 562 | 让我们最后再总结一下吧： 563 | 564 | - **“S: 单一职责原则”** 认为一个类只应该有一种被修改的原因 565 | - 编写更小的类通常更不容易违反 S 原则 566 | - S 原则同样适用于函数，你可以让函数和类协同工作 567 | - **“O: 开放-关闭原则”** 认为类应该对改动关闭，对扩展开放 568 | - 找到需求中频繁变化的那个点，是让类遵循 O 原则的重点所在 569 | - 使用子类继承的方式可以让类遵守 O 原则 570 | - 通过定义算法类，并进行依赖注入，也可以让类遵循 O 原则 571 | - 将数据与逻辑分离，使用数据驱动的方式也是改造代码的好办法 572 | 573 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 574 | 575 | [>>>下一篇【13.写好面向对象代码的原则（中）】](13-write-solid-python-codes-part-2.md) 576 | 577 | [<<<上一篇【11.高效操作文件的三个建议】](11-three-tips-on-writing-file-related-codes.md) 578 | 579 | ## 附录 580 | 581 | - 题图来源: Photo by Kelly Sikkema on Unsplash 582 | - 更多系列文章地址： 583 | 584 | 系列其他文章： 585 | 586 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 587 | - [Python 工匠：让函数返回结果的技巧](https://www.piglei.com/articles/function-returning-tips/) 588 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 589 | - [Python 工匠：高效操作文件的三个建议](https://www.piglei.com/articles/three-tips-on-writing-file-related-codes/) 590 | -------------------------------------------------------------------------------- /zh_CN/13-write-solid-python-codes-part-2.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：写好面向对象代码的原则（中） 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 13 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 在 [上一篇文章](https://www.piglei.com/articles/write-solid-python-codes-part-1/) 里，我用一个虚拟小项目作为例子，讲解了“SOLID”设计原则中的前两位成员：S *（单一职责原则）* 与 O *（开放-关闭原则）*。 12 | 13 | 在这篇文章中，我将继续介绍 SOLID 原则的第三位成员：**L（里氏替换原则）**。 14 | 15 | ## 里氏替换原则与继承 16 | 17 | 在开始前，我觉得有必要先提一下 [继承（Inheritance）](https://en.wikipedia.org/wiki/Inheritance)。因为和前面两条非常抽象的原则不同，“里氏替换原则”是一条非常具体的，和类继承有关的原则。 18 | 19 | 在 OOP 世界里，继承算是一个非常特殊的存在，它有点像一把无坚不摧的双刃剑，强大且危险。合理使用继承，可以大大减少类与类之间的重复代码，让程序事半功倍，而不当的继承关系，则会让类与类之间建立起错误的强耦合，带来大片难以理解和维护的代码。 20 | 21 | 正是因为这样，对继承的态度也可以大致分为两类。大多数人认为，继承和多态、封装等特性一样，属于面向对象编程的几大核心特征之一。而同时有另一部分人觉得，继承带来的 [坏处远比好处多](https://www.javaworld.com/article/2073649/why-extends-is-evil.html)。甚至在 Go 这门相对年轻的编程语言里，设计者直接去掉了继承，提倡完全使用组合来替代。 22 | 23 | 从我个人的编程经验来看，继承确实极易被误用。要设计出合理的继承关系，是一件需要深思熟虑的困难事儿。不过幸运的是，在这方面，"里氏替换原则"*(后简称 L 原则)* 为我们提供了非常好的指导意义。 24 | 25 | 让我们来看看它的内容。 26 | 27 | ## L：里氏替换原则 28 | 29 | 同前面的 S 与 O 两个原则的命名方式不同，里氏替换原则 *（Liskov Substitution Principle）* 是直接用它的发明者 [Barbara Liskov](https://en.wikipedia.org/wiki/Barbara_Liskov) 命名的，原文看起来像一个复杂的数学公式： 30 | 31 | > Let q(x) be a property provable about objects of x of type T. Then q(y) should be provable for objects y of type S where S is a subtype of T. 32 | > 33 | > - 出处: [Liskov substitution principle - Wikipedia](https://en.wikipedia.org/wiki/Liskov_substitution_principle) 34 | 35 | 如果把它比较通俗的翻译过来，大概是这样：**当你使用继承时，子类（派生类）对象应该可以在程序中替代父类（基类）对象使用，而不破坏程序原本的功能。** 36 | 37 | 光说有点难理解，让我们用代码来看看一个在 Python 中违反 Liskov 原则的例子。 38 | 39 | ## 一个违反 L 原则的样例 40 | 41 | 假设我们在为一个 Web 站点设计用户模型。这个站点的用户分为两类：普通用户和站点管理员。所以在代码里，我们定义了两个用户类：普通用户类 `User` 和管理员类 `Admin`。 42 | 43 | ```python 44 | class User(Model): 45 | """普通用户模型类 46 | """ 47 | def __init__(self, username: str): 48 | self.username = username 49 | 50 | def deactivate(self): 51 | """停用当前用户 52 | """ 53 | self.is_active = False 54 | self.save() 55 | 56 | class Admin(User): 57 | """管理员用户类 58 | """ 59 | def deactivate(self): 60 | # 管理员用户不允许被停用 61 | raise RuntimeError('admin can not be deactivated!') 62 | ``` 63 | 64 | 因为普通用户的绝大多数操作在管理员上都适用，所以我们把 `Admin` 类设计成了继承自 `User` 类的子类。不过在“停用”操作方面，管理员和普通用户之间又有所区别： **普通用户可以被停用，但管理员不行。** 65 | 66 | 于是在 `Admin` 类里，我们重写了 `deactivate` 方法，使其抛出一个 `RuntimeError` 异常，让管理员对象无法被停用。 67 | 68 | 子类继承父类，然后重写父类的少量行为，这看上去正是类继承的典型用法。但不幸的是，这段代码违反了“里氏替换原则”。具体是怎么回事呢？让我们来看看。 69 | 70 | ### 不当继承关系如何违反 L 原则 71 | 72 | 现在，假设我们需要写一个新函数，它可以同时接受多个用户对象作为参数，批量将它们停用。代码如下： 73 | 74 | ```python 75 | def deactivate_users(users: Iterable[User]): 76 | """批量停用多个用户 77 | """ 78 | for user in users: 79 | user.deactivate() 80 | ``` 81 | 82 | 很明显，上面的代码是有问题的。因为 `deactivate_users` 函数在参数注解里写到，它接受一切 **可被迭代的 User 对象**，那么管理员 `Admin` 是不是 `User` 对象？当然是，因为它是继承自 `User` 类的子类。 83 | 84 | 但是，如果你真的把 `[User("foo"), Admin("bar_admin")]` 这样的用户列表传到 `deactivate_users` 函数里，程序立马就会抛出 `RuntimeError` 异常，因为管理员对象 `Admin("bar_admin")` 压根不支持停用操作。 85 | 86 | 在 `deactivate_users` 函数看来，子类 `Admin` 无法随意替换父类 `User` 使用，所以现在的代码是不符合 L 原则的。 87 | 88 | ### 一个简单但错误的解决办法 89 | 90 | 要修复上面的函数，最直接的办法就是在函数内部增加一个额外的类型判断： 91 | 92 | ```python 93 | def deactivate_users(users: Iterable[User]): 94 | """批量停用多个用户 95 | """ 96 | for user in users: 97 | # 管理员用户不支持 deactivate 方法，跳过 98 | if isinstance(user, Admin): 99 | logger.info(f'skip deactivating admin user {user.username}') 100 | continue 101 | 102 | user.deactivate() 103 | ``` 104 | 105 | 在修改版的 `deactivate_users` 函数里，如果它在循环时恰好发现某个用户是 `Admin` 类，就跳过这次操作。这样它就能正确处理那些混合了管理员的用户列表了。 106 | 107 | 但是，这样修改的缺点是显而易见的。因为虽然到目前为止，只有 `Admin` 类型的用户不允许被停用。但是，**谁能保证未来不会出现其他不能被停用的用户类型呢？**比如： 108 | 109 | - 公司员工不允许被停用 110 | - VIP 用户不允许被停用 111 | - 等等(... ...) 112 | 113 | 而当这些新需求在未来不断出现时，我们就需要重复的修改 `deactivate_users` 函数，来不断适配这些无法被停用的新用户类型。 114 | 115 | ```python 116 | def deactivate_users(users: Iterable[User]): 117 | for user in users: 118 | # 在类型判断语句不断追加新用户类型 119 | if isinstance(user, (Admin, VIPUser, Staff)): 120 | ... ... 121 | ``` 122 | 123 | 现在，让我们再回忆一下前面的 SOLID 第二原则：**“开放-关闭原则”**。这条原则认为：好的代码应该对扩展开发，**对修改关闭**。而上面的函数很明显不符合这条原则。 124 | 125 | 到这里你会发现，**SOLID 里的每条原则并非完全独立的个体，它们之间其实互有联系。**比如，在这个例子里，我们先是违反了“里氏替换原则”，然后我们使用了错误的修复方式：*增加类型判断*。之后发现，这样的代码同样也无法符合“开放-关闭原则”。 126 | 127 | ### 正确的修改办法 128 | 129 | 既然为函数增加类型判断无法让代码变得更好，那我们就应该从别的方面入手。 130 | 131 | “里氏替换原则”提到，**子类 *（Admin）* 应该可以随意替换它的父类 *（User）*，而不破坏程序 *（deactivate_users）* 本身的功能**。 我们试过直接修改类的使用者来遵守这条原则，但是失败了。所以这次，让我们试着从源头上解决问题：重新设计类之间的继承关系。 132 | 133 | 具体点来说，子类不能只是简单通过抛出异常的方式对某个类方法进行“退化”。如果 *“对象不能支持某种操作”* 本身就是这个类型的 **核心特征** 之一，那我们在进行父类设计时，就应该把这个 **核心特征** 设计进去。 134 | 135 | 拿用户类型举例，*“用户可能无法被停用”* 就是 `User` 类的核心特征之一，所以在设计父类时，我们就应该把它作为类方法 *（或属性）* 写进去。 136 | 137 | 让我们看看调整后的代码： 138 | 139 | ```python 140 | class User(Model): 141 | """普通用户模型类 142 | """ 143 | def __init__(self, username: str): 144 | self.username = username 145 | 146 | def allow_deactivate(self) -> bool: 147 | """是否允许被停用 148 | """ 149 | return True 150 | 151 | def deactivate(self): 152 | """将当前用户停用 153 | """ 154 | self.is_active = True 155 | self.save() 156 | 157 | class Admin(User): 158 | """管理员用户类 159 | """ 160 | def allow_deactivate(self) -> bool: 161 | # 管理员用户不允许被停用 162 | return False 163 | 164 | def deactivate_users(users: Iterable[User]): 165 | """批量停用多个用户 166 | """ 167 | for user in users: 168 | if not user.allow_deactivate(): 169 | logger.info(f'user {user.username} does not allow deactivating, skip.') 170 | continue 171 | 172 | user.deactivate() 173 | ``` 174 | 175 | 在新代码里，我们在父类中增加了 `allow_deactivate` 方法，由它来决定当前的用户类型是否允许被停用。而在 `deactivate_users` 函数中，也不再需要通过脆弱的类型判断，来判定某类用户是否可以被停用。我们只需要调用 `user.allow_deactivate()` 方法，程序便能自动跳过那些不支持停用操作的用户对象。 176 | 177 | 在这样的设计中，`User` 类的子类 `Admin` 做到了可以完全替代父类使用，而不会破坏程序 `deactivate_users` 的功能。 178 | 179 | 所以我们可以说，修改后的类继承结构是符合里氏替换原则的。 180 | 181 | ## 另一种违反方式：子类修改方法返回值 182 | 183 | 除了上面的例子外，还有一种常见的违反里氏替换原则的情况。让我们看看下面这段代码： 184 | 185 | ```python 186 | class User(Model): 187 | """普通用户模型类 188 | """ 189 | def __init__(self, username: str): 190 | self.username = username 191 | 192 | def list_related_posts(self) -> List[int]: 193 | """查询所有与之相关的帖子 ID 194 | """ 195 | return [post.id for post in session.query(Post).filter(username=self.username)] 196 | 197 | class Admin(User): 198 | """管理员用户类 199 | """ 200 | def list_related_posts(self) -> Iterable[int]: 201 | # 管理员与所有的帖子都有关，为了节约内存，使用生成器返回帖子 ID 202 | for post in session.query(Post).all(): 203 | yield post.id 204 | ``` 205 | 206 | 在这段代码里，我给用户类增加了一个新方法：`list_related_posts`，调用它可以拿到所有和当前用户有关的帖子 ID。对于普通用户，方法返回的是自己发布过的所有帖子，而管理员则是站点里的所有帖子。 207 | 208 | 现在，假设我需要写一个函数，来获取和用户有关的所有帖子标题： 209 | 210 | ```python 211 | def list_user_post_titles(user: User) -> Iterable[str]: 212 | """获取与用户有关的所有帖子标题 213 | """ 214 | for post_id in user.list_related_posts(): 215 | yield session.query(Post).get(post_id).title 216 | ``` 217 | 218 | 对于上面的 `list_user_post_titles` 函数来说，无论传入的 `user` 参数是 `User` 还是 `Admin` 类型，它都能正常工作。因为，虽然普通用户和管理员类型的 `list_related_posts` 方法返回结果略有区别，但它们都是 **“可迭代的帖子 ID”**，所以函数里的循环在碰到不同的用户类型时都能正常进行。 219 | 220 | 既然如此，那上面的代码符合“里氏替换原则”吗？答案是否定的。因为虽然在当前 `list_user_post_titles` 函数的视角看来，子类 `Admin` 可以任意替代父类 `User` 使用，但这只是特殊用例下的一个巧合，并没有通用性。请看看下面这个场景。 221 | 222 | 有一位新成员最近加入了项目开发，她需要实现一个新函数来获取与用户有关的所有帖子数量。当她读到 `User` 类代码时，发现 `list_related_posts` 方法返回一个包含所有帖子 ID 的列表，于是她就此写下了统计帖子数量的代码： 223 | 224 | ```python 225 | def get_user_posts_count(user: User) -> int: 226 | """获取与用户相关的帖子个数 227 | """ 228 | return len(user.list_related_posts()) 229 | ``` 230 | 231 | 在大多数情况下，当 `user` 参数只是普通用户类时，上面的函数是可以正常执行的。 232 | 233 | 不过有一天，有其他人偶然使用了一个管理员用户调用了上面的函数，马上就碰到了异常：`TypeError: object of type 'generator' has no len()`。这时因为 `Admin` 虽然是 `User` 类型的子类，但它的 `list_related_posts` 方法返回却是一个可迭代的生成器，并不是列表对象。而生成器是不支持 `len()` 操作的。 234 | 235 | 所以，对于新的 `get_user_posts_count` 函数来说，现在的用户类继承结构仍然违反了 L 原则。 236 | 237 | ### 分析类方法返回结果 238 | 239 | 在我们的代码里，`User` 类和 `Admin` 类的 `list_related_posts` 返回的是两类不同的结果： 240 | 241 | - `User 类`：返回一个包含帖子 ID 的列表对象 242 | - `Admin 类`：返回一个产生帖子 ID 的生成器 243 | 244 | 很明显，二者之间存在共通点：它们都是可被迭代的 int 对象（`Iterable[int]`）。这也是为什么对于第一个获取用户帖子标题的函数来说，两个用户类可以互相交换使用的原因。 245 | 246 | 不过，针对某个特定函数，子类可以替代父类使用，并不等同于代码就符合“里氏替换原则”。要符合 L 原则，**我们一定得让子类方法和父类返回同一类型的结果，支持同样的操作。或者更进一步，返回支持更多种操作的子类型结果也是可以接受的。** 247 | 248 | 而现在的设计没做到这点，现在的子类返回值所支持的操作，只是父类的一个子集。`Admin` 子类的 `list_related_posts` 方法所返回的生成器，只支持父类 `User` 返回列表里的“迭代操作”，而不支持其他行为（比如 `len()`）。所以我们没办法随意的用子类替换父类，自然也就无法符合里氏替换原则。 249 | 250 | > 注意：此处说“生成器”支持的操作是“列表”的子集其实不是特别严谨，因为生成器还支持 `.send()` 等其他操作。不过在这里，我们可以只关注它的可迭代特性。 251 | 252 | ### 如何修改代码 253 | 254 | 为了让代码符合“里氏替换原则”。我们需要让子类和父类的同名方法，返回同一类结果。 255 | 256 | ```python 257 | class User(Model): 258 | """普通用户模型类 259 | """ 260 | def __init__(self, username: str): 261 | self.username = username 262 | 263 | def list_related_posts(self) -> Iterable[int]: 264 | """查询所有与之相关的帖子 ID 265 | """ 266 | for post in session.query(Post).filter(username=self.username): 267 | yield post.id 268 | 269 | def get_related_posts_count(self) -> int: 270 | """获取与用户有关的帖子总数 271 | """ 272 | value = 0 273 | for _ in self.list_related_posts(): 274 | value += 1 275 | return value 276 | 277 | 278 | class Admin(User): 279 | """管理员用户类 280 | """ 281 | def list_related_posts(self) -> Iterable[int]: 282 | # 管理员与所有的帖子都有关，为了节约内存，使用生成器返回 283 | for post in session.query(Post).all(): 284 | yield post.id 285 | ``` 286 | 287 | 而对于“获取与用户有关的帖子总数”这个需求，我们可以直接在父类 `User` 中定义一个 `get_related_posts_count` 方法，遍历帖子 ID，统计数量后返回。 288 | 289 | ### 方法参数与 L 原则 290 | 291 | 除了子类方法返回不一致的类型以外，子类对父类方法参数的变更也容易导致违反 L 原则。拿下面这段代码为例： 292 | 293 | ```python 294 | class User(Model): 295 | def list_related_posts(self, include_hidden: bool = False) -> List[int]: 296 | # ... ... 297 | 298 | 299 | class Admin(User): 300 | def list_related_posts(self) -> List[int]: 301 | # ... ... 302 | ``` 303 | 304 | 如果父类 `User` 的 `list_related_posts` 方法接收一个可选的 `include_hidden` 参数，那它的子类就不应该去掉这个参数。否则当某个函数调用依赖了 `include_hidden` 参数，但用户对象却是子类 `Admin` 类型时，程序就会报错。 305 | 306 | 为了让代码符合 L 原则，我们必须做到 **让子类的方法参数签名和父类完全一致，或者更宽松**。这样才能做到在任何使用参数调用父类方法的地方，随意用子类替换。 307 | 308 | 比如下面这样就是符合 L 原则的： 309 | 310 | ```python 311 | class User(Model): 312 | def list_related_posts(self, include_hidden: bool = False) -> List[int]: 313 | # ... ... 314 | 315 | 316 | class Admin(User): 317 | def list_related_posts(self, include_hidden: bool = False, active_only = True) -> List[int]: 318 | # 子类可以为方法增加额外的可选参数：active_only 319 | # ... ... 320 | ``` 321 | 322 | ## 总结 323 | 324 | 在这篇文章里，我通过两个具体场景，向你描述了 “SOLID” 设计原则中的第三位成员：**里氏替换原则**。 325 | 326 | “里氏替换原则”是一个非常具体的原则，它专门为 OOP 里的继承场景服务。当你设计类继承关系，尤其是编写子类代码时，请经常性的问自己这个问题：*“如果我把项目里所有使用父类的地方换成这个子类，程序是否还能正常运行？”* 327 | 328 | 如果答案是否定的，那么你就应该考虑调整一下现在的类设计了。调整方式有很多种，有时候你得把大类拆分为更小的类，有时候你得调换类之间的继承关系，有时候你得为父类添加新的方法和属性，就像文章里的第一个场景一样。只要开动脑筋，总会找到合适的办法。 329 | 330 | 让我们最后再总结一下吧： 331 | 332 | - **“L：里氏替换原则”** 认为子类应该可以任意替换父类被使用 333 | - 在类的使用方增加具体的类型判断（*isinstance*），通常不是最佳解决方案 334 | - 违反里氏替换原则，通常也会导致违反“开放-关闭”原则 335 | - 考虑什么是类的核心特征，然后为父类增加新的方法和属性可以帮到你 336 | - 子类方法应该和父类同名方法返回同一类型，或者返回支持更多操作的子类型也行 337 | - 子类的方法参数应该和父类同名方法完全一致，或者更为宽松 338 | 339 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 340 | 341 | [>>>下一篇【14.写好面向对象代码的原则（下）】](14-write-solid-python-codes-part-3.md) 342 | 343 | [<<<上一篇【12.写好面向对象代码的原则（上）】](12-write-solid-python-codes-part-1.md) 344 | 345 | ## 附录 346 | 347 | - 题图来源: Photo by NeONBRAND on Unsplash 348 | - 更多系列文章地址： 349 | 350 | 系列其他文章： 351 | 352 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 353 | - [Python 工匠：写好面向对象代码的原则（上）](https://www.piglei.com/articles/write-solid-python-codes-part-1/) 354 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 355 | - [Python 工匠：高效操作文件的三个建议](https://www.piglei.com/articles/three-tips-on-writing-file-related-codes/) 356 | -------------------------------------------------------------------------------- /zh_CN/14-write-solid-python-codes-part-3.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：写好面向对象代码的原则（下） 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 14 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 在这篇文章中，我将继续介绍 SOLID 原则剩下的两位成员：**I（接口隔离原则）** 和 **D（依赖倒置原则）**。为了方便，这篇文章将会使用先 D 后 I 的顺序。 12 | 13 | ## D：依赖倒置原则 14 | 15 | 软件是由一个个模块组合而成的。当你跟别人说：*“我在写一个很复杂的软件”*，其实你并不是直接在写那个软件，你只是在编写它的一个个模块，最后把它们放在一起组合成你的软件。 16 | 17 | 有了模块，模块间自然就有了依赖关系。比如，你的个人博客可能依赖着 Flask 框架，而 Flask 又依赖了 Werkzeug，Werkzeug 又由更多个低层模块组成。 18 | 19 | 依赖倒置原则（Dependency Inversion Principle）就是一条和依赖关系相关的原则。它认为：**“高层模块不应该依赖于低层模块，二者都应该依赖于抽象。”** 20 | 21 | > High-level modules should not depend on low-level modules. Both should depend on abstractions. 22 | 23 | 这个原则看上去有点反直觉。毕竟，在我们的第一堂编程课上，老师就是这么教我们写代码的：*“高层模块要依赖低层模块，hello world 程序依赖 printf()。”* 那为什么这条原则又说不要这样做呢？而依赖倒置原则里的“倒置”又是指什么？ 24 | 25 | 让我们先把这些问题放在一边，看看下面这个小需求。上面这些问题的答案都藏在这个需求中。 26 | 27 | ### 需求：按域名分组统计 HN 新闻数量 28 | 29 | 这次出场的还是我们的老朋友：新闻站点 [Hacker News](https://news.ycombinator.com/)。在 HN 上，每个用户提交的条目标题后面，都跟着这条内容的来源域名。 30 | 31 | 我想要按照来源域名来分组统计条目数量，这样就能知道哪个站在 HN 上最受欢迎。 32 | 33 |
34 | 35 | 图：Hacker News 条目来源截图 36 |
37 | 38 | 这个需求非常简单，使用 `requests`、`lxml` 模块可以很快完成任务： 39 | 40 | ```python 41 | # file: hn_site_grouper.py 42 | import requests 43 | from lxml import etree 44 | from typing import Dict 45 | from collections import Counter 46 | 47 | 48 | class SiteSourceGrouper: 49 | """对 HN 页面的新闻来源站点进行分组统计 50 | """ 51 | def __init__(self, url: str): 52 | self.url = url 53 | 54 | def get_groups(self) -> Dict[str, int]: 55 | """获取 (域名, 个数) 分组 56 | """ 57 | resp = requests.get(self.url) 58 | html = etree.HTML(resp.text) 59 | # 通过 xpath 语法筛选新闻域名标签 60 | elems = html.xpath('//table[@class="itemlist"]//span[@class="sitestr"]') 61 | 62 | groups = Counter() 63 | for elem in elems: 64 | groups.update([elem.text]) 65 | return groups 66 | 67 | 68 | def main(): 69 | groups = SiteSourceGrouper("https://news.ycombinator.com/").get_groups() 70 | # 打印最常见的 3 个域名 71 | for key, value in groups.most_common(3): 72 | print(f'Site: {key} | Count: {value}') 73 | 74 | 75 | if __name__ == '__main__': 76 | main() 77 | ``` 78 | 79 | 代码执行结果： 80 | 81 | ```bash 82 | ❯ python hn_sitestr_grouper.py 83 | Site: github.com | Count: 2 84 | Site: howonlee.github.io | Count: 1 85 | Site: latimes.com | Count: 1 86 | ``` 87 | 88 | 这段代码很短，核心代码总共不到 20 行。现在，让我们来理一理它里面的依赖关系。 89 | 90 | `SiteSourceGrouper` 是我们的核心类。为了完成任务，它需要使用 `requests` 模块获取首页内容、`lxml` 模块解析标题。所以，现在的依赖关系是“正向”的，高层模块 `SiteSourceGrouper` 依赖低层模块 `requests`、`lxml`。 91 | 92 |
93 | 94 | 图：SiteSourceGrouper 依赖 requests、lxml 95 |
96 | 97 | 也许现在这张图在你眼里看起来特别合理。正常的依赖关系不就应该是这样的吗？别着急，我们还没给代码写单元测试呢。 98 | 99 | ### 为 SiteSourceGrouper 编写单元测试 100 | 101 | 现在让我来为这段代码加上单元测试。首先让最普通的情况开始： 102 | 103 | ```python 104 | from hn_site_grouper import SiteSourceGrouper 105 | from collections import Counter 106 | 107 | 108 | def test_grouper_returning_valid_types(): 109 | """测试 get_groups 是否返回了正确类型 110 | """ 111 | grouper = SiteSourceGrouper('https://news.ycombinator.com/') 112 | result = grouper.get_groups() 113 | assert isinstance(result, Counter), "groups should be Counter instance" 114 | ``` 115 | 116 | 这是一个再简单不过的单元测试，我调用了 `SiteSourceGrouper.get_groups()` 方法，然后简单校验了一下返回结果类型是否正常。 117 | 118 | 这个测试在本地电脑上执行时没有一点问题，可以正常通过。但当我在服务器上执行这段单元测试代码时，却发现它根本没办法成功。因为 **我的服务器不能访问外网。** 119 | 120 | ```python 121 | # 运行单元测试时提示网络错误 122 | requests.exceptions.ConnectionError: HTTPSConnectionPool(host='news.ycombinator.com', port=443): ... ... [Errno 8] nodename nor servname provided, or not known')) 123 | ``` 124 | 125 | 到这里，单元测试暴露了 `SiteSourceGrouper` 类的一个问题：*它的核心逻辑依赖 requests 模块和网络连接，严格限制了单元测试的执行条件。* 126 | 127 | 既然如此，那要如何解决这个问题呢？如果你去问一个有经验的 Python 的开发者，十有八九他会甩给你一句话：**“用 mock 啊！”** 128 | 129 | #### 使用 mock 模块 130 | 131 | [mock](https://docs.python.org/3/library/unittest.mock.html) 是 unittest 里的一个模块，同时也是一类测试手法的统称。假如你需要测试的模块里有一部分依赖很难被满足*（比如代码需要访问一整套 Kubernetes 集群）*，或者你想在测试时故意替换掉某些依赖，那么 mock 就能派上用场。 132 | 133 | 在这个例子里，使用 unittest.mock 模块需要做下面这些事情： 134 | 135 | - 把一份正确的 HN 页面内容保存为本地文件 `static_hn.html` 136 | - 在测试文件中导入 `unittest.mock` 模块 137 | - 在测试函数中，通过 [`mock.path('requests.get')`](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch) 替换网络请求部分 138 | - 将其修改为直接返回文件 `static_hn.html` 的内容 139 | 140 | 使用 mock 后的代码看起来是这样的： 141 | 142 | ```python 143 | from unittest import mock 144 | 145 | def test_grouper_returning_valid_types(): 146 | """测试 get_groups 是否返回了正确类型 147 | """ 148 | resp = mock.Mock() 149 | # Mock 掉 requests.get 函数 150 | with mock.patch('hn_site_grouper.requests.get') as mocked_get: 151 | mocked_get.return_value = resp 152 | with open('static_hn.html', 'r') as fp: 153 | # Mock 掉响应的 text 字段 154 | resp.text = fp.read() 155 | 156 | grouper = SiteSourceGrouper('https://news.ycombinator.com/') 157 | result = grouper.get_groups() 158 | assert isinstance(result, Counter), "groups should be Counter instance" 159 | ``` 160 | 161 | 上面的代码并不算复杂。对于 Python 这类动态语言来说，使用 mock 有着一种得天独厚的优势。因为在 Python 里，运行时的一切对象几乎都可以被替换掉。 162 | 163 | 不过虽然 mock 用起来很方便，但它不是解决我们问题的最佳做法。因为 mock 在带来方便的同时，也让测试代码变得更复杂和难以理解。而且，给测试加上 mock 也仅仅只是让我的单元测试能够跑起来，糟糕设计仍然是糟糕设计。它无法体现出单元测试最重要的价值之一：**“通过编写测试反向推动设计改进”**。 164 | 165 | 所以，我们需要做的是改进依赖关系，而不只是简单的在测试时把依赖模块替换掉。如何改进依赖关系？让我们看看“依赖倒置”是如何做的。 166 | 167 | ### 实现依赖倒置原则 168 | 169 | 首先，让我们重温一下“依赖倒置原则”*（后简称 D 原则）* 的内容：**“高层模块不应该依赖于低层模块，二者都应该依赖于抽象。”** 170 | 171 | 在上面的代码里，高层模块 `SiteSourceGrouper` 就直接依赖了低层模块 `requests`。为了让代码符合 D 原则，我们首先需要创造一个处于二者中间的抽象，然后让两个模块可以都依赖这个新的抽象层。 172 | 173 | 创建抽象的第一步 *（可能也是最重要的一步）*，就是确定这个抽象层的职责。在例子中，高层模块主要依赖 `requests` 做了这些事： 174 | 175 | - 通过 `requests.get()` 获取 response 176 | - 通过 `response.text` 获取响应文本 177 | 178 | 所以，这个抽象层的主要职责就是产生 HN 站点的页面文本。我们可以给它起个名字：`HNWebPage`。 179 | 180 | 确定了抽象层的职责和名字后，接下来应该怎么实现它呢？在 Java 或 Go 语言里，标准答案是定义 **Interface**（接口）。因为对于这些编程语言来说，“接口”这两个字基本就可以等同于“抽象”。 181 | 182 | 拿 Go 来说，“Hacker News 站点页面”这层抽象就可以被定义成这样的 Interface： 183 | 184 | ```go 185 | type HNWebPage interface { 186 | // GetText 获取页面文本 187 | GetText() (string, error) 188 | } 189 | ``` 190 | 191 | 不过，Python 根本没有接口这种东西。那该怎么办呢？虽然 Python 没有接口，但是有一个非常类似的东西：**“抽象类（Abstrace Class）”**。使用 [`abc`](https://docs.python.org/3/library/abc.html) 模块就可以轻松定义出一个抽象类： 192 | 193 | ```python 194 | from abc import ABCMeta, abstractmethod 195 | 196 | 197 | class HNWebPage(metaclass=ABCMeta): 198 | """抽象类：Hacker New 站点页面 199 | """ 200 | 201 | @abstractmethod 202 | def get_text(self) -> str: 203 | raise NotImplementedError 204 | ``` 205 | 206 | 抽象类和普通类的区别之一就是你不能将它实例化。如果你尝试实例化一个抽象类，解释器会报出下面的错误： 207 | 208 | ```python 209 | TypeError: Can't instantiate abstract class HNWebPage with abstract methods get_text 210 | ``` 211 | 212 | 所以，光有抽象类还不能算完事，我们还得定义几个依赖这个抽象类的实体。首先定义的是 `RemoteHNWebPage` 类。它的作用就是通过 requests 模块请求 HN 页面，返回页面内容。 213 | 214 | ```python 215 | class RemoteHNWebPage(HNWebPage): 216 | """远程页面，通过请求 HN 站点返回内容""" 217 | 218 | def __init__(self, url: str): 219 | self.url = url 220 | 221 | def get_text(self) -> str: 222 | resp = requests.get(self.url) 223 | return resp.text 224 | ``` 225 | 226 | 定义了 `RemoteHNWebPage` 类后，`SiteSourceGrouper` 类的初始化方法和 `get_groups` 也需要做对应的调整： 227 | 228 | ```python 229 | class SiteSourceGrouper: 230 | """对 HN 页面的新闻来源站点进行分组统计 231 | """ 232 | 233 | def __init__(self, page: HNWebPage): 234 | self.page = page 235 | 236 | def get_groups(self) -> Dict[str, int]: 237 | """获取 (域名, 个数) 分组 238 | """ 239 | html = etree.HTML(self.page.get_text()) 240 | # 通过 xpath 语法筛选新闻域名标签 241 | elems = html.xpath('//table[@class="itemlist"]//span[@class="sitestr"]') 242 | 243 | groups = Counter() 244 | for elem in elems: 245 | groups.update([elem.text]) 246 | return groups 247 | 248 | 249 | def main(): 250 | # 实例化 page，传入 SiteSourceGrouper 251 | page = RemoteHNWebPage(url="https://news.ycombinator.com/") 252 | grouper = SiteSourceGrouper(page).get_groups() 253 | ``` 254 | 255 | 做完这些修改后，让我们再看看现在的模块依赖关系： 256 | 257 |
258 | 259 | 图：SiteSourceGrouper 和 RemoteHNWebPage 都依赖抽象层 HNWebPage 260 |
261 | 262 | 在图中，高层模块不再依赖低层模块，二者同时依赖于抽象概念 `HNWebPage`，低层模块的依赖箭头和之前相比倒过来了。所以我们称其为 **依赖倒置**。 263 | 264 | ### 依赖倒置后的单元测试 265 | 266 | 再回到之前的单元测试上来。通过引入了新的抽象层 `HNWebPage`，我们可以实现一个不依赖外部网络的新类型 `LocalHNWebPage`。 267 | 268 | ```python 269 | class LocalHNWebPage(HNWebPage): 270 | """本地页面，根据本地文件返回页面内容""" 271 | 272 | def __init__(self, path: str): 273 | self.path = path 274 | 275 | def get_text(self) -> str: 276 | with open(self.path, 'r') as fp: 277 | return fp.read() 278 | ``` 279 | 280 | 所以，单元测试也可以改为使用 `LocalHNWebPage`： 281 | 282 | ```python 283 | def test_grouper_from_local(): 284 | page = LocalHNWebPage(path="./static_hn.html") 285 | grouper = SiteSourceGrouper(page) 286 | result = grouper.get_groups() 287 | assert isinstance(result, Counter), "groups should be Counter instance" 288 | ``` 289 | 290 | 这样就可以在没有外网的服务器上测试 `SiteSourceGrouper` 类的核心逻辑了。 291 | 292 | > Hint：其实上面的测试函数 `test_grouper_from_local` 远远算不上一个合格的测试用例。 293 | > 294 | > 如果真要测试 `SiteSourceGrouper` 的核心逻辑。我们应该准备一个虚构的 Hacker News 页面 *（比如刚好包含 5 个 来源自 github.com 的条目）*，然后判断结果是否包含 `assert result['github.com] == 5` 295 | 296 | ### 问题：一定要使用抽象类 abc 吗？ 297 | 298 | 为了实现依赖倒置，我们在上面定义了抽象类：`HNWebPage`。那是不是只有定义了抽象类才能实现依赖倒置？只有用了抽象类才算是依赖倒置呢？ 299 | 300 | **答案是否定的。** 如果你愿意，你可以把代码里的抽象类 `HNWebPage` 以及所有的相关引用都删掉，你会发现没有它们代码仍然可以正常运行。 301 | 302 | 这是因为 Python 是一门“鸭子类型”语言。这意味着只要 `RemoteHNWebPage` 和 `LocalHNWebPage` 类型保持着统一的接口协议*（提供 .get_text() 公开方法）*，并且它们的 **协议符合我们定义的抽象**。那么那个中间层就存在，依赖倒置就是成立的。至于这份 **协议** 是通过抽象类还是普通父类（甚至可以是普通函数）定义的，就没那么重要了。 303 | 304 | 所以，虽然在某些编程语言中，实现依赖倒置必须得定义新的接口类型，但在 Python 里，依赖倒置并不是抽象类 abc 的特权。 305 | 306 | ### 问题：抽象一定是好东西吗？ 307 | 308 | 前面的所有内容，都是在说新增一个抽象层，然后让依赖关系倒过来的种种好处。所以，多抽象的代码一定就是好的吗？缺少抽象的代码就一定不够灵活？ 309 | 310 | 和所有这类问题的标准回答一样，答案是：**视情况而定。** 311 | 312 | 当你习惯了依赖倒置原则以后，你会发现 *抽象（Abstract）* 其实是一种思维方式，而不仅仅是一种编程手法。如果你愿意，你可以在代码里的所有地方都 **硬挤** 一层额外抽象出来： 313 | 314 | - 比如代码依赖了 lxml 模块的 xpath 具体实现，我是不是得定义一层 *“HNTitleDigester”* 把它抽象进去？ 315 | - 比如代码里的字符串字面量也是具体实现，我是不是得定义一个 *"StringLike"* 类型把它抽象进去？ 316 | - ... ... 317 | 318 | 事实上，抽象的好处显而易见：**它解耦了高层模块和低层模块间的依赖关系，让代码变得更灵活。** 但抽象同时也带来了额外的编码与理解成本。所以，了解何时 **不** 抽象与何时抽象同样重要。**只有对代码中那些现在或未来会发生变化的东西进行抽象，才能获得最大的收益。** 319 | 320 | ## I：接口隔离原则 321 | 322 | 接口隔离原则*（后简称 I 原则）*全称为 *“Interface Segregation Principles”*。顾名思义，它是一条和“接口（Interface）”有关的原则。 323 | 324 | 我在前面解释过何为“接口（Interface）”。**接口是模块间相互交流的抽象协议**，它在不同的编程语言里有着不同的表现形态。比如在 Go 里它是 `type ... interface`，而在 Python 中它可以是抽象类、普通类或者函数，甚至某个只在你大脑里存在的一套协议。 325 | 326 | I 原则认为：**“客户（client）应该不依赖于它不使用的方法”** 327 | 328 | > The interface-segregation principle (ISP) states that no client should be forced to depend on methods it does not use. 329 | 330 | 这里说的“客户（Client）”指的是接口的使用方 *（客户程序）*，也就是调用接口方法的高层模块。拿上一个统计 HN 页面条目的例子来说： 331 | 332 | - `使用方（客户程序）`：SiteSourceGrouper 333 | - `接口（其实是抽象类）`：HNWebPage 334 | - `依赖关系`：调用接口方法：`get_text()` 获取页面文本 335 | 336 | 在 I 原则看来，**一个接口所提供的方法，应该就是使用方所需要的方法，不多不少刚刚好。** 所以，在上个例子里，我们设计的接口 `HNWebPage` 是符合接口隔离原则的。因为它没有向使用方提供任何后者不需要的方法 。 337 | 338 | > 你需要 get_text()！我提供 get_text()！刚刚好！ 339 | 340 | 所以，这条原则看上去似乎很容易遵守。既然如此，让我们试试来违反它吧！ 341 | 342 | ### 例子：开发页面归档功能 343 | 344 | 让我们接着上一个例子开始。在实现了上个需求后，我现在有一个代表 Hacker News 站点页面的抽象类 `HNWebPage`，它只提供了一种行为，就是获取当前页面的文本内容。 345 | 346 | ```python 347 | class HNWebPage(metaclass=ABCMeta): 348 | 349 | @abstractmethod 350 | def get_text(self) -> str: 351 | """获取页面文本内容""" 352 | ``` 353 | 354 | 现在，假设我要开发一个和 HN 页面有关的新功能： **我想在不同时间点对 HN 首页内容进行归档，观察热点新闻在不同时间点发生的变化。** 所以除了页面文本内容外，我还需要拿到页面的大小、生成时间这些额外信息，然后将它们都保存到数据库中。 355 | 356 | 为了做到这一点，现在的 `HNWebPage` 类需要被扩展一下： 357 | 358 | ```python 359 | class HNWebPage(metaclass=ABCMeta): 360 | 361 | @abstractmethod 362 | def get_text(self) -> str: 363 | """获取页面文本内容""" 364 | 365 | # 新增 get_size 与 get_generated_at 366 | 367 | @abstractmethod 368 | def get_size(self) -> int: 369 | """获取页面大小""" 370 | 371 | @abstractmethod 372 | def get_generated_at(self) -> datetime.datetime: 373 | """获取页面生成时间""" 374 | ``` 375 | 376 | 我在原来的类上增加了两个新的抽象方法：`get_size` 和 `get_generated_at`。这样归档程序就能通过它们拿到页面大小和生成时间了。 377 | 378 | 改完抽象类后，紧接着的任务就是修改依赖它的实体类。 379 | 380 | ### 问题：实体类不符合 HNWebPage 接口规范 381 | 382 | 在修改抽象类前，我们有两个实现了它协议的实体类：`RemoteHNWebPage` 和 `LocalHNWebPage`。如今，`HNWebPage` 增加了两个新方法 `get_size` 和 `get_generated_at`。我们自然需要把这两个实体类也加上这两个方法。 383 | 384 | `RemoteHNWebPage` 类的修改很好做，我们只要让 `get_size` 放回页面长度，让 `get_generated_at` 返回当前时间就行了。 385 | 386 | ```python 387 | # class RemoteHNWebPage: 388 | # 389 | def get_generated_at(self) -> datetime.datetime: 390 | # 页面生成时间等同于通过 requests 请求的时间 391 | return datetime.datetime.now() 392 | ``` 393 | 394 | 但是，在给 `LocalHNWebPage` 添加 `get_generated_at` 方法时，我碰到了一个问题。`LocalHNWebPage` 是一个完全基于本地页面文件作为数据来源的类，仅仅通过 “static_hn.html” 这么一个本地文件，我根本就没法知道它的内容是什么时候生成的。 395 | 396 | 这时我只能选择让它的 `get_generated_at` 方法返回一个错误的结果 *（比如文件的修改时间）*，或者直接抛出异常。无论是哪种做法，我都可能违反 [里式替换原则](https://www.piglei.com/articles/write-solid-python-codes-part-2/)。 397 | 398 | > Hint：里式替换原则认为子类（派生类）对象应该可以在程序中替代父类（基类）对象使用，而不破坏程序原本的功能。让方法抛出异常显然破坏了这一点。 399 | 400 | ```python 401 | # class LocalHNWebPage: 402 | # 403 | def get_generated_at(self) -> datetime.datetime: 404 | raise NotImplementedError("local web page can not provide generate_at info") 405 | ``` 406 | 407 | 所以，对现有接口的盲目扩展暴露出来一个问题：**更多的接口方法意味着更高的实现成本，给实现方带来麻烦的概率也变高了。** 408 | 409 | 不过现在让我们暂且把这个问题放到一边，继续写一个 `SiteAchiever` 类完成归档任务： 410 | 411 | ```python 412 | class SiteAchiever: 413 | """将不同时间点的 HN 页面归档""" 414 | 415 | def save_page(self, page: HNWebPage): 416 | """将页面保存到后端数据库 417 | """ 418 | data = { 419 | "content": page.get_text(), 420 | "generated_at": page.get_generated_at(), 421 | "size": page.get_size(), 422 | } 423 | # 将 data 保存到数据库中 424 | ``` 425 | 426 | ### 成功违反 I 协议 427 | 428 | 代码写到这，让我们回头看看上个例子里的 *条目来源分组类 `SiteSourceGrouper`* 。 429 | 430 |
431 | 432 | 图：成功违反了 I 协议 433 |
434 | 435 | 当我修改完抽象类后，虽然 `SiteSourceGrouper` 仍然依赖着 `HNWebPage`，但它其实只使用了 `get_text` 这一个方法而已，其他 `get_size`、`get_generated` 这些它 **不使用的方法也成为了它的依赖。** 436 | 437 | 很明显，现在的设计违反了接口隔离原则。为了修复这一点，我们需要将 `HNWebPage` 拆成更小的接口。 438 | 439 | ### 如何分拆接口 440 | 441 | 设计接口有一个技巧：**让客户（调用方）来驱动协议设计**。让我们来看看，`HNWebPage` 到底有哪些客户： 442 | 443 | - `SiteSourceGrouper`：域名来源统计，依赖 `get_text()` 444 | - `SiteAchiever`：HN 页面归档程序，依赖 `get_text()`、`get_size()`、`get_generated_at()` 445 | 446 | 按照上面的方式，我们可以把 `HNWebPage` 分离成两个独立的抽象类： 447 | 448 | ```python 449 | class ContentOnlyHNWebPage(metaclass=ABCMeta): 450 | """抽象类：Hacker New 站点页面（仅提供内容） 451 | """ 452 | 453 | @abstractmethod 454 | def get_text(self) -> str: 455 | raise NotImplementedError 456 | 457 | 458 | class HNWebPage(ContentOnlyHNWebPage): 459 | """抽象类：Hacker New 站点页面（含元数据） 460 | """ 461 | 462 | @abstractmethod 463 | def get_size(self) -> int: 464 | """获取页面大小""" 465 | 466 | @abstractmethod 467 | def get_generated_at(self) -> datetime.datetime: 468 | """获取页面生成时间""" 469 | ``` 470 | 471 | 将旧类拆分成两个不同的抽象类后，`SiteSourceGrouper` 和 `SiteAchiever` 就可以分别依赖不同的抽象类了。 472 | 473 | 同时，对于 `LocalHNWebPage` 类来说，它也只需要实现那个只返回的文本的 `ContentOnlyHNWebPage` 就行。 474 | 475 |
476 | 477 | 图：实施接口隔离后的结果 478 |
479 | 480 | ### 一些不容易发现的违反情况 481 | 482 | 虽然我花了很长的篇幅，用了好几个抽象类才把接口隔离原则讲明白，但其实在我们的日常编码中，对这条原则的违反经常会出现在一些更容易被忽视的地方。 483 | 484 | 举个例子，当我们在 web 站点里判断用户请求的 Cookies 或头信息是否包含某个标记值时，我们经常直接写一个依赖整个 `request` 对象的函数： 485 | 486 | ```python 487 | def is_new_visitor(request: HttpRequest) -> bool: 488 | """从 Cookies 判断是否新访客 489 | """ 490 | return request.COOKIES.get('is_new_visitor') == 'y' 491 | ``` 492 | 493 | 但事实上，除了 `.COOKIES` 以外，`is_new_visitor` 根本就不需要 `request` 对象里面的任何其他内容。“用户请求对象（request）”是一个比“Cookie 字典（request.COOKIES）”复杂得多的抽象。我们完全可以把函数改成只接收 cookies 字典。 494 | 495 | ```python 496 | def is_new_visitor(cookies: Dict) -> bool: 497 | """从 Cookies 判断是否新访客 498 | """ 499 | return cookies.get('is_new_visitor') == 'y' 500 | ``` 501 | 502 | 类似的情况还有很多，比如一个发短信的函数本身只需要两个参数 `电话号码` 和 `用户姓名`，但是函数却依赖了整个用户对象 `User`，里面包含着几十个用不上的其他字段和方法。 503 | 504 | 对于这类函数，我们都可以重新考虑一下它们的抽象是否合理，是否需要应用接口隔离原则。 505 | 506 | ### 现实世界中的接口隔离 507 | 508 | 当你知道了接口隔离原则的种种好处后，你很自然就会养成写小类、小接口的习惯。在现实世界里，其实已经有很多小而精的接口设计可以供你参考。比如： 509 | 510 | - Python 的 [collections.abc](https://docs.python.org/3/library/collections.abc.html) 模块里面有非常多的小接口 511 | - Go 里面的 [Reader 和 Writer](https://golang.org/pkg/io/#Reader) 也是非常好的例子 512 | 513 | ## 总结 514 | 515 | 在这篇文章里，我向你介绍了 SOLID 原则的最后两位成员：**“依赖倒置原则”** 与 **“接口隔离原则”**。 516 | 517 | 这两条原则之间有一个共同点，那就是它们都和 **“抽象”** 有着紧密的联系。前者告诉我们要面向抽象而非实现编程，后者则教导我们在设计抽象时应该做到精准。 518 | 519 | 最后再总结一下： 520 | 521 | - **“D：依赖倒置原则”** 认为高层模块和低层模块都应该依赖于抽象 522 | - 依赖抽象，意味着我们可以完全修改低层实现，而不影响高层代码 523 | - 在 Python 中你可以使用 abc 模块来定义抽象类 524 | - 除 abc 外，你也可以使用其他技术来完成依赖倒置 525 | - **“I：接口隔离原则”** 认为客户不应该依赖任何它不使用的方法 526 | - 设计接口就是设计抽象 527 | - 违反接口隔离原则也可能会导致违反单一职责与里式替换原则 528 | - 写更小的类、写更小的接口在大多数情况下是个好主意 529 | 530 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 531 | 532 | [>>>下一篇【15.在边界处思考】](15-thinking-in-edge-cases.md) 533 | 534 | [<<<上一篇【13.写好面向对象代码的原则（中）】](13-write-solid-python-codes-part-2.md) 535 | 536 | ## 附录 537 | 538 | - 题图来源: Photo by Carolina Garcia Tavizon on Unsplash 539 | - 更多系列文章地址： 540 | 541 | 系列其他文章： 542 | 543 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 544 | - [Python 工匠：写好面向对象代码的原则（上）](https://www.piglei.com/articles/write-solid-python-codes-part-1/) 545 | - [Python 工匠：写好面向对象代码的原则（中）](https://www.piglei.com/articles/write-solid-python-codes-part-2/) 546 | - [Python 工匠：写好面向对象代码的原则（下）](https://www.piglei.com/articles/write-solid-python-codes-part-3/) 547 | -------------------------------------------------------------------------------- /zh_CN/15-thinking-in-edge-cases.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：在边界处思考 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 15 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 2016 年，Linux 操作系统的创造者 Linus Torvalds 参加了一场[TED 访谈节目](https://www.ted.com/talks/linus_torvalds_the_mind_behind_linux/transcript?language=en)。整个节目的前半部分，主要是他在讲如何在家光着膀子写出 Linux 的故事，没有涉及太多编程相关的事情。 12 | 13 | 不过在访谈快结束时，突然出现了一个有趣的环节。主持人向 Linus 提问道：“你曾说过更愿意和那些有着好的 **代码品味** 的人共事，那在你眼里，什么才是好的代码品味？” 14 | 15 | 为了解释这个问题，Linus 在大屏幕上展示了一份代码。我把其摘抄如下。 16 | 17 | ```c 18 | remove_list_entry(entry) { 19 | prev = NULL; 20 | walk = head; 21 | 22 | // 遍历链表 23 | while (walk != entry) { 24 | prev = walk; 25 | walk = walk->next; 26 | } 27 | 28 | // 关键：当要删除时，判断当前位置是否在链表头部进行不同的动作 29 | if (!prev) 30 | head = entry->next; 31 | else 32 | prev->next = entry->next; 33 | } 34 | ``` 35 | 36 | 函数 `remove_list_entry` 的主要功能是通过遍历链表，删除里面的某个成员。但在这份代码中，存在一个 **[边界情况（Edge Case）](https://en.wikipedia.org/wiki/Edge_case)**。 37 | 38 | 在编程时，“边界情况”是指那些只在极端情景下出现的情况。比如在上面的代码里，当我们要找的元素刚好处于链表头部时，就是一个边界情况。为了处理它，函数在删除前进行了一次 `if / else` 判断。 39 | 40 | Linus 认为这条 if 语句是整段代码的“坏味道”来源，写出它的人代码品味不够好 ☹️。那么，一个品味更好的人应该怎么写呢？很快，屏幕上出现了第二份代码。 41 | 42 | ```c 43 | remove_list_entry(entry) { 44 | indirect = &head 45 | 46 | // 遍历链表过程代码已省略 47 | 48 | // 当要删除时，直接进行指针操作删除 49 | *indirect = entry->next 50 | } 51 | ``` 52 | 53 | 在新代码中，`remove_list_entry` 函数利用了 C 语言里的指针特性，把之前的 `if / else` 完全消除了。无论待删除的目标是在链表头部还是中间，函数都能一视同仁的完成删除操作。之前的边界情况消失了。 54 | 55 | 看到这你是不是在犯嘀咕：*Python 又没有指针，你跟我说这么多指针不指针的干啥？* 虽然 Python 没有指针，但我觉得这个例子为我们提供了一个很有趣的主题。那就是 **如何充分利用语言特性，更好的处理编码时的边界情况。** 56 | 57 | 我认为，好代码在处理边界情况时应该是简洁的、“润物细无声”的。就像上面的例子一样，可以做到让边界情况消融在代码主流程中。在写 Python 时，有不少编码技巧和惯例可以帮我们做到这一点，一块来看看吧。 58 | 59 | ## 第一课：使用分支还是异常？ 60 | 61 | 今天周末，你计划参加朋友组织的聚餐，临出门时突然想起来最近是雨季。于是你掏出手机打开天气 App，看看今天是不是会下雨。如果下雨，就带上一把伞再出门。 62 | 63 | 假如把“今天下雨”类比成编程时的 *边界情况*，那“看天气预报 + 带伞”就是我们的边界处理代码。这种 `if 下雨 then 带伞` 的分支式判断，基本是一种来自直觉的思考本能。所以，当我们在编程时发现边界情况时，第一反应往往就是：**“弄个 if 分支把它包起来吧！”**。 64 | 65 | 比如下面这段代码： 66 | 67 | ```python 68 | def counter_ap(l): 69 | """计算列表里面每个元素出现的数量""" 70 | result = {} 71 | for key in l: 72 | # 主流程：累加计数器 73 | if key in result: 74 | result[key] += 1 75 | # **边界情况：当元素第一次出现时，先初始化值为 1** 76 | else: 77 | result[key] = 1 78 | return result 79 | 80 | # 执行结果： 81 | print(counter_ap(['apple', 'banana', 'apple'])) 82 | {'apple': 2, 'banana': 1} 83 | ``` 84 | 85 | 在上面的循环里，代码的主流程是*“对每个 key 的计数器加 1”*。但是，当 result 字典里还没有 `key` 元素时，是不能直接进行累加操作的（会抛出 `KeyError`）。 86 | 87 | ```python 88 | >>> result = {} 89 | >>> result['foo'] += 1 90 | Traceback (most recent call last): 91 | File "", line 1, in 92 | KeyError: 'foo' 93 | ``` 94 | 95 | 于是一个边界情况出现了：当元素第一次出现时，我们需要对值进行初始化。 96 | 97 | 所以，我专门写了一条 `if` 语句去处理这个边界情况。代码简单，无需过多解释。但你可能不知道的是，其实有一个术语来专门描述这种编程风格：**“（LBYL）Look Before You Leap”**。 98 | 99 | “LBYL” 这缩写不太好翻译。用大白话讲，就是在进行操作前，先对可能的边界情况进行条件判断。根据结果不同，确定是处理边界情况，还是执行主流程。 100 | 101 | 如之前所说，使用 “LBYL” 来处理边界情况，几乎是一种直觉式的行为。*“有边界情况，就加上 if 分支”*和*“如果天气预报说下雨，我就带伞出门”*一样，是一种基本不需要过脑子的操作。 102 | 103 | 而在 LBYL 之外，有着与其形成鲜明对比的另外一种风格：**“EAFP（Easier to Ask for Forgiveness than Permission）”**。 104 | 105 | ### 获取原谅比许可简单(EAFP) 106 | 107 | “EAFP” 通常被翻译成“获取原谅比许可简单”。如果还用下雨举例，那 EAFP 的做法就类似于 *“出门前不看任何天气预报，如果淋雨了，就回家后洗澡吃感冒药 💊”*。 108 | 109 | 使用 EAFP 风格的代码是这样的： 110 | 111 | ```python 112 | def counter_af(l): 113 | result = {} 114 | for key in l: 115 | try: 116 | # 总是直接执行主流程：累加计数器 117 | result[key] += 1 118 | except KeyError: 119 | # 边界情况：当元素第一次出现时会报错 KeyError，此时进行初始化 120 | result[key] = 1 121 | return result 122 | ``` 123 | 124 | 和 LBYL 相比，EAFP 编程风格更为简单粗暴。它总是直奔主流程而去，把边界情况都放在异常处理 `try except` 块内消化掉。 125 | 126 | 如果你问我：“这两种编程风格哪个更好？”，我只能说整个 Python 社区对基于异常捕获的“请求原谅（EAFP）”型编程风格有着明显的偏爱。其中的原因有很多。 127 | 128 | 首先，和许多其他编程语言不同，在 Python 里抛出异常是一个很轻量的操作，即使程序会大量抛出、捕获异常，使用 EAFP 也不会给程序带来额外的负担。 129 | 130 | 其次，“请求原谅”在性能上通常也更有优势，因为程序总是直奔主流程而去，只有极少数情况下才需要处理边界情况。拿上面的例子来说，第二段代码通常会比第一段更快，因为它不用在每次循环时都做一次额外的成员检查。 131 | 132 | > Hint：如果你想了解更多这方面的知识，建议阅读： [Write Cleaner Python: Use Exceptions](https://jeffknupp.com/blog/2013/02/06/write-cleaner-python-use-exceptions/) 133 | 134 | 所以，每当你想凭直觉写下 `if else` 来处理边界情况时，先考虑下使用 `try` 来捕获异常是不是更合适。毕竟，Pythonista 们总是喜欢“吃感冒药 💊”胜过“看天气预报”。😅 135 | 136 | ## 当容器内容不存在时 137 | 138 | Python 里有很多内建的容器类型，比如字典、列表、集合等等。在进行容器操作时，经常会出现一些边界情况。其中“要访问的内容不存在”，是最为常见的一类： 139 | 140 | - 操作字典时，访问的键 `key` 不存在，会抛出 `KeyError` 异常 141 | - 操作列表、元组时，访问的下标 `index` 不存在，会抛出 `IndexError` 异常 142 | 143 | 对于这类边界情况，除了针对性的捕获对应异常外，还有许多其他处理方式。 144 | 145 | ### 使用 defaultdict 改写示例 146 | 147 | 在前面的例子里，我们使用了 `try except` 语句处理了*“key 第一次出现”*这个边界情况。虽然我说过，使用 `try` 的代码比 `if` 更好，但这不代表它就是一份地道的 Python 代码。 148 | 149 | 为什么？因为如果你想统计列表元素的话，直接用 `collections.defaultdict` 就可以了： 150 | 151 | ```python 152 | from collections import defaultdict 153 | 154 | 155 | def counter_by_collections(l): 156 | result = defaultdict(int) 157 | for key in l: 158 | result[key] += 1 159 | return result 160 | ``` 161 | 162 | 这样的代码既不用“获取许可”，也无需“请求原谅”。 整个函数只有一个主流程，代码更清晰、更自然。 163 | 164 | 为什么 `defaultdict` 可以让边界情况消失？因为究其根本，之前的代码就是少了针对 *“键不存在”* 时的默认处理逻辑。所以，当我们用 `defaultdict` 声明了如何处理这个边界情况时，原本需要手动判断的部分就消失了。 165 | 166 | > Hint：就上面的例子来说，使用 [collections.Counter](https://docs.python.org/3/library/collections.html#collections.Counter) 也能达到同样的目的。 167 | 168 | ### 使用 setdefault 取值并修改 169 | 170 | 有时候，我们需要操作字典里的某个值，但它又可能并不存在。比如下面这个例子： 171 | 172 | ```python 173 | # 往字典的 values 键追加新值，假如不存在，先以列表初始化 174 | try: 175 | d['values'].append(value) 176 | except KeyError: 177 | d['values'] = [value] 178 | ``` 179 | 180 | 针对这种情况，我们可以使用 **`d.setdefault(key, default=None)`** 方法来简化边界处理逻辑，直接替换上面的异常捕获语句： 181 | 182 | ```python 183 | # 如果 setdefault 指定的 key（此处为 "values"）不存在，以 [] 初始化，否则返回已存在 184 | # 的值。 185 | d.setdefault('values', []).append(value) 186 | ``` 187 | 188 | > Hint：使用 `defaultdict(list)` 同样可以利索的解决这个问题。 189 | 190 | ### 使用 dict.pop 删除不存在的键 191 | 192 | 如果我们要删除字典的某个 `key`，一般会使用 `del` 关键字。但当 `key` 不存在时，删除操作就会抛出 `KeyError` 异常。 193 | 194 | 所以，想要安全删除某个 `key`，还得加上一段异常捕获逻辑。 195 | 196 | ```python 197 | try: 198 | del d[key] 199 | except KeyError: 200 | # 忽略 key 不存在的情况 201 | pass 202 | ``` 203 | 204 | 但假设只是单纯的想删除某个 `key`，并不关心它是否存在、有没有删成功。使用 `dict.pop(key, default)` 方法就够了。 205 | 206 | 只要在调用 `dict.pop` 方法时传入默认值，`key` 不存在时就不会抛出异常了。 207 | 208 | ```python 209 | # 使用 pop 方法，指定 default 值为 None，当 key 不存在时，不会报错 210 | d.pop(key, None) 211 | ``` 212 | 213 | > Hint：严格来说，`pop` 方法的主要用途并不是去删除某个 key，而是 **取出** 某个 key 对应的值。不过我觉得偶尔用它来做删除也无伤大雅。 214 | 215 | ### 当列表切片越界时 216 | 217 | 所有人都知道，当你的列表*（或元组）*只有 3 个元素，而你想要访问第 4 个时，解释器会报出 `IndexError` 错误。我们通常称这类错误为*“数组越界”*。 218 | 219 | ```python 220 | >>> l = [1, 2, 3] 221 | >>> l[2] 222 | 3 223 | >>> l[3] 224 | Traceback (most recent call last): 225 | File "", line 1, in 226 | IndexError: list index out of range 227 | ``` 228 | 229 | 但你可能不知道的是，假如你请求的不是某一个元素，而是一段范围的切片。那么无论你指定的范围是否有效，程序都只会返回一个空列表 `[]`，而不会抛出任何错误： 230 | 231 | ```python 232 | >>> l = [] 233 | >>> l[1000:1001] 234 | [] 235 | ``` 236 | 237 | 了解了这点后，你会发现像下面这种边界处理代码根本没有必要： 238 | 239 | ```python 240 | def sum_list(l, limit): 241 | """对列表的前 limit 个元素求和 242 | """ 243 | # 如果 limit 过大，设置为数组长度避免越界 244 | if limit > len(l): 245 | limit = len(l) 246 | return sum(l[:limit]) 247 | ``` 248 | 249 | 因为做切片不会抛出任何错误，所以不需要判断 limit 是否超出范围，直接做 `sum` 操作即可： 250 | 251 | ```python 252 | def sum_list(l, limit): 253 | return sum(l[:limit]) 254 | ``` 255 | 256 | 利用这个特点，我们还可以简化一些特定的边界处理逻辑。比如安全删除列表的某个元素： 257 | 258 | ```python 259 | # 使用异常捕获安全删除列表的第 5 个元素 260 | try: 261 | l.pop(5) 262 | except IndexError: 263 | pass 264 | 265 | # 删除从 5 开始的长度为 1 的切片，不需要捕获任何异常 266 | del l[5:6] 267 | ``` 268 | 269 | ## 好用又危险的 “or” 操作符 270 | 271 | `or` 是一个几乎在所有编程语言里都有的操作符，它在 Python 里通常被用来和 `and` 一起做布尔值逻辑运算。比如: 272 | 273 | ```python 274 | >>> False or True 275 | True 276 | ``` 277 | 278 | 但 `or` 还有一个有趣的特点是短路求值，比如在下面的例子里，`1 / 0` 永远不会被执行*（也就意味着不会抛出 ZeroDivisionError）*： 279 | 280 | ```python 281 | >>> True or (1 / 0) 282 | True 283 | ``` 284 | 285 | 在很多场景下，我们可以利用 `or` 的特点来简化一些边界处理逻辑。看看下面这个例子： 286 | 287 | ```python 288 | context = {} 289 | # 仅当 extra_context 不为 None 时，将其追加进 context 中 290 | if extra_context: 291 | context.update(extra_context) 292 | ``` 293 | 294 | 在这段代码里，`extra_context` 的值一般情况下会是一个字典，但有时也可能是 `None`。所以我加了一个条件判断语句，当它的值不为 `None` 时才做 `.update` 操作。 295 | 296 | 如果使用 `or` 操作符，我们可以让上面的语句更简练： 297 | 298 | ```python 299 | context.update(extra_context or {}) 300 | ``` 301 | 302 | 因为 `a or b or c or ...` 这样的表达式，会返回这些变量里第一个布尔值为真的值，直到最后一个为止。所以 `extra_context or {}` 在 `extra_context` 为 `None` 时其实就等于 `{}`。因此之前的条件判断就可以被简化成一个 `or` 表达式了。 303 | 304 | 使用 `a or b` 来表示*“ a 为空时用 b 代替”*，这种写法一点也不新鲜。你在各种编程语、各类框架源码源码里都能发现它的影子。但在这个写法下，其实也藏有一个陷阱。 305 | 306 | 因为 `or` 操作计算的是变量的布尔真假值。所以，不光是 `None`，所有的 0、[]、{}、set() 以及其他所有会被判断为布尔假的东西，都会在 `or` 运算中被忽略。 307 | 308 | ```python 309 | # 所有的 0、空列表、空字符串等，都是布尔假值 310 | >>> bool(None), bool(0), bool([]), bool({}), bool(''), bool(set()) 311 | (False, False, False, False, False, False) 312 | ``` 313 | 314 | 如果忘记了 `or` 的这个特点，可能会碰到一些很奇怪的问题。比如这段代码： 315 | 316 | ```python 317 | timeout = config.timeout or 60 318 | ``` 319 | 320 | 虽然上面代码的目的，是想要判断当 `config.timeout` 为 `None` 时使用 60 做默认值。但假如 `config.timeout` 的值被主动配置成了 `0` 秒，`timeout` 也会因为上面的 `0 or 60 = 60` 运算被重新赋值为 60。正确的配置因此被忽略掉了。 321 | 322 | 所以，有时使用 `if` 来进行精确的边界处理会更稳妥一些： 323 | 324 | ```python 325 | if config.timeout is None: 326 | timeout = 60 327 | ``` 328 | 329 | ## 不要手动去做数据校验 330 | 331 | 无数前辈的经验告诉我们：*“不要信任任何用户输入”*。这意味着所有存在用户输入的地方，都必须对其进行校验。那些无效、危险的用户输入值，就是需要我们处理的边界情况。 332 | 333 | 假如我在写一个命令行小程序，需要让用户输入一个 0-100 范围的数字。要是用户的输入无效，就要求其重新输入。 334 | 335 | 程序大概长这样： 336 | 337 | ```python 338 | def input_a_number(): 339 | """要求用户输入一个 0-100 的数字，如果无效则重新输入 340 | """ 341 | while True: 342 | number = input('Please input a number (0-100): ') 343 | 344 | # 此处往下的三条 if 语句都是输入值的边界校验代码 345 | if not number: 346 | print('Input can not be empty!') 347 | continue 348 | if not number.isdigit(): 349 | print('Your input is not a valid number!') 350 | continue 351 | if not (0 <= int(number) <= 100): 352 | print('Please input a number between 0 and 100!') 353 | continue 354 | 355 | number = int(number) 356 | break 357 | 358 | print(f'Your number is {number}') 359 | ``` 360 | 361 | 执行效果如下： 362 | 363 | ```python 364 | Please input a number (0-100): 365 | Input can not be empty! 366 | Please input a number (0-100): foo 367 | Your input is not a valid number! 368 | Please input a number (0-100): 65 369 | Your number is 65 370 | ``` 371 | 372 | 这个函数一共有 14 行有效代码。其中有 3 段 if 共 9 行代码，都是用于校验的边界值检查代码。也许你觉得这样的检查很正常，但请想象一下，假如需要校验的输入不止一个、校验逻辑也比这个复杂怎么办？那样的话，**这些边界值检查代码就会变得又臭又长。** 373 | 374 | 如何改进这些代码呢？把它们抽离出去，作为一个校验函数和核心逻辑隔离开是个不错的办法。但更重要的在于，要把 *“输入数据校验”* 作为一个独立的职责与领域，用更恰当的模块来完成这项工作。 375 | 376 | 在数据校验这块，[pydantic](https://pydantic-docs.helpmanual.io/) 模块是一个不错的选择。如果用它来做校验，代码可以被简化成这样: 377 | 378 | ```python 379 | from pydantic import BaseModel, conint, ValidationError 380 | 381 | 382 | class NumberInput(BaseModel): 383 | # 使用类型注解 conint 定义 number 属性的取值范围 384 | number: conint(ge=0, le=100) 385 | 386 | 387 | def input_a_number_with_pydantic(): 388 | while True: 389 | number = input('Please input a number (0-100): ') 390 | 391 | # 实例化为 pydantic 模型，捕获校验错误异常 392 | try: 393 | number_input = NumberInput(number=number) 394 | except ValidationError as e: 395 | print(e) 396 | continue 397 | 398 | number = number_input.number 399 | break 400 | 401 | print(f'Your number is {number}') 402 | ``` 403 | 404 | 在日常编码时，我们应该尽量避免去手动校验数据。而是应该使用*（或者自己实现）*合适的第三方校验模块，把这部分边界处理工作抽象出去，简化主流程代码。 405 | 406 | > Hint: 假如你在开发 Web 应用，那么数据校验部分通常来说都挺容易。比如 Django 框架有自己的 forms 模块，Flask 也可以使用 WTForms 来进行数据校验。 407 | 408 | ## 不要忘记做数学计算 409 | 410 | 很多年前刚接触 Web 开发时，我想学着用 JavaScript 来实现一个简单的文字跑马灯动画。如果你不知道啥是“跑马灯”，我可以稍微解释一下。“跑马灯”就是让一段文字从页面左边往右边不断循环滚动，十几年前的网站特别流行这个。😬 411 | 412 | 我记得里面有一段逻辑是这样的：*控制文字不断往右边移动，当横坐标超过页面宽度时，重置坐标后继续*。我当时写出来的代码，翻译成 Python 大概是这样： 413 | 414 | ```python 415 | while True: 416 | if element.position_x > page_width: 417 | # 边界情况：当对象位置超过页面宽度时，重置位置到最左边 418 | element.position_x -= page_width 419 | 420 | # 元素向右边滚动一个单位宽度 421 | element.position_x += width_unit 422 | ``` 423 | 424 | 看上去还不错对不对？我刚写完它时也是这么认为的。但后来有一天，我重新看到它时，才发现其中的古怪之处。 425 | 426 | 在上面的代码里，我需要在主循环里保证 “element.position_x 不会超过页面宽度 page_width”。所以我写了一个 if 来处理当 `position_x` 超过页面宽度的情况。 427 | 428 | 但如果是要保证某个累加的数字 *（position_x）* 不超过另一个数字 *（page_width）*，直接用 `%` 做取模运算不就好了吗？ 429 | 430 | ```python 431 | while True: 432 | # 使用 % page_width 控制不要超过页面宽度 433 | element.position_x = (element.position_x + width_unit) % page_width 434 | ``` 435 | 436 | 这样写的话，代码里的边界情况就连着那行 `if` 语句一起消失了。 437 | 438 | 和取模运算类似的操作还有很多，比如 `abs()`、`math.floor()` 等等。我们应该记住，不要写出 `if value < 0: value = -value` 这种“边界判断代码”，直接使用 `abs(value)` 就好，不要重新发明绝对值运算。 439 | 440 | ## 总结 441 | 442 | “边界情况（Edge cases）”是我们在日常编码时的老朋友。但它不怎么招人喜欢，毕竟，我们都希望自己的代码只有一条主流程贯穿始终，不需要太多的条件判断、异常捕获。 443 | 444 | 但边界情况同时又是无法避免的，只要有代码，边界情况就会存在。所以，如果能更好的处理它们，我们的代码就可以变得更清晰易读。 445 | 446 | 除了上面介绍的这些思路外，还有很多东西都可以帮助我们处理边界情况，比如利用面向对象的多态特性、使用 [空对象模式](https://github.com/piglei/one-python-craftsman/blob/master/zh_CN/5-function-returning-tips.md#5-%E5%90%88%E7%90%86%E4%BD%BF%E7%94%A8%E7%A9%BA%E5%AF%B9%E8%B1%A1%E6%A8%A1%E5%BC%8F) 等等。 447 | 448 | 最后再总结一下： 449 | 450 | - 使用条件判断和异常捕获都可以用来处理边界情况 451 | - 在 Python 里，我们更倾向于使用基于异常捕获的 EAFP 风格 452 | - 使用 defaultdict / setdefault / pop 可以巧妙的处理当键不存在时的边界情况 453 | - 对列表进行不存在的范围切片不会抛出异常 454 | - 使用 `or` 可以简化默认值边界处理逻辑，但也要注意不要掉入陷阱 455 | - 不要手动去做数据校验，使用 `pydantic` 或其他的数据校验模块 456 | - 利用取模、绝对值计算等方式，可以简化一些特定的边界处理逻辑 457 | 458 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 459 | 460 | [<<<上一篇【14.写好面向对象代码的原则（下）】](14-write-solid-python-codes-part-3.md) 461 | 462 | > 为了避免内容重复，在系列第 4 篇“容器的门道”里出现的 EAPF 相关内容会被删除，并入到本文中。 463 | 464 | ## 附录 465 | 466 | - 题图来源: Photo by Jessica Ruscello on Unsplash 467 | - 更多系列文章地址： 468 | 469 | 系列其他文章： 470 | 471 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 472 | - [Python 工匠：写好面向对象代码的原则（上）](https://www.piglei.com/articles/write-solid-python-codes-part-1/) 473 | - [Python 工匠：让函数返回结果的技巧](https://www.piglei.com/articles/function-returning-tips/) 474 | -------------------------------------------------------------------------------- /zh_CN/16-stmt-expr-and-walrus-operator.md: -------------------------------------------------------------------------------- 1 | 让我们从两行最简单的 Python 代码开始。 2 | 3 | ```python 4 | >>> name = 'piglei' 5 | >>> print(f'Hello {name}!') 6 | Hello piglei! 7 | ``` 8 | 9 | 这是一个“Hello World”程序，你也许已经见过它无数次，对里面的每个字母都了如指掌。但你可能从未意识到，上面两行代码，刚好对应着 Python 语言里的两个重要概念：**语句（statement）** 和 **表达式（expression）**。 10 | 11 | 具体来说，`name = 'piglei'` 是一行赋值语句，它将字符串 `'piglei'` 赋给了 `name` 变量。`print(f'Hello {name}!')` 则是一个表达式，它通过调用内置函数 `print` 往屏幕打印信息。 12 | 13 | ### 表达式的特点 14 | 15 | 编写代码时，语句和表达式是两类最基本的代码单元。 16 | 17 | 虽然在日常表达中，我们会把语句和表达式区分开来，但二者并非完全不同——表达式实际上就是一种特殊的语句。和普通语句比起来，表达式的特别之处在于它拥有一个（或多个）返回值。 18 | 19 | 举例来说，前面的 `print(...)` 表达式就会返回一个值：`None`。你可以像下面这样获取它： 20 | 21 | ```python 22 | # print 函数总是返回 None 23 | >>> val = print(f'Hello {name}!') 24 | Hello piglei! 25 | >>> val is None 26 | True 27 | ``` 28 | 29 | 虽然这么做没啥实际用途，但它足够体现出表达式的独特之处——因为你永远无法对普通语句做出类似的事情。无论是“赋值语句”、“循环语句”，还是一个“条件分支语句”，你永远都无法将其赋值给某个变量，这在语法上无从谈起： 30 | 31 | ```python 32 | >>> val = (name = 'piglei') 33 | File "", line 1 34 | val = (name = 'piglei') 35 | ^ 36 | SyntaxError: invalid syntax #1 37 | ``` 38 | 39 | 1. 意料之中，抛出了语法错误（`SyntaxError`） 40 | 41 | 不过，Python 3.8 版本发布以后，表达式和语句间的分界线突然变得前所未有的模糊。上面这行错误代码，只要增加一个冒号就可以变得合法： 42 | 43 | ```python 44 | >>> val = (name := 'piglei') 45 | >>> val, name 46 | ('piglei', 'piglei') 47 | ``` 48 | 49 | 这便是“海象操作符（walrus operator）”——`:=`——的威力。 50 | 51 | ### 海象操作符 52 | 53 | 也许你会好奇，“海象操作符”这名字是怎么来的，为啥蟒蛇（python）的世界里会突然冒出一头海象（walrus）？假如你把头向左倾斜 90 度，仔细观察 `:=` 符号，就会发现其中的奥秘：它看起来就像一头海象的面部，冒号是鼻孔，等号是它的两根长牙。 54 | 55 | 使用 `:=` 操作符，可以构建出学名为“赋值表达式（Assignment Expressions）”的东西。在赋值表达式出现前，变量的赋值只能通过语句来完成。它出现后，我们便可在一个表达式内完成赋值，同时返回所赋值的变量。 56 | 57 | ```python 58 | >>> val = (name := 'piglei') #1 59 | ``` 60 | 61 | 1. `(name := 'piglei')` 就是一个赋值表达式，它同时做到了两件事：将 `'piglei'` 赋值为 `name` 变量；返回 `name` 变量的值。 62 | 63 | 赋值表达式几乎可以被用在任何你能想到的地方，比如条件分支、循环和列表推导式，等等。 64 | 65 | 让我们来看几个典型场景。 66 | 67 | #### 1. 用于分支语句 68 | 69 | 有一个函数，功能是从一段字符串中找出第一个以字母“w”开头的单词，如未找到，再尝试找以“w”结尾的。代码可以这么写： 70 | 71 | ```python 72 | import re 73 | 74 | LEADING_W_WORD = re.compile(r'\bw\w*?\b', re.I) 75 | TRAILING_W_WORD = re.compile(r'\b\w*?w\b', re.I) 76 | 77 | def find_w_word(s): 78 | """找到并打印字符串中第一个以 w 开头的单词，如未找到，再试着找 w 结尾的""" 79 | if LEADING_W_WORD.search(s): 80 | word = LEADING_W_WORD.search(s).group() 81 | print(f'Found word starts with "w": {word}') 82 | elif TRAILING_W_WORD.search(s): 83 | word = TRAILING_W_WORD.search(s).group() 84 | print(f'Found word ends with "w": {word}') 85 | ``` 86 | 87 | 调用效果如下： 88 | 89 | ```python 90 | >>> find_w_word('Guido found several examples where a programmer repeated a subexpression') 91 | Found word starts with "w": where 92 | ``` 93 | 94 | 上面的代码存在一个小问题，每个负责正则搜索的表达式 `LEADING_W_WORD.search(s)` 分别重复出现了两次：一次在分支判断处，另一次在分支内部。 95 | 96 | 这种重复会让代码更难维护，也会影响程序的执行性能。因此，大部分时候我们会通过定义变量来消除重复： 97 | 98 | ```python 99 | def find_w_word_v2(s): 100 | """找到并打印字符串中第一个以 w 开头的单词，如未找到，再试着找 w 结尾的""" 101 | l_match = LEADING_W_WORD.search(s) #1 102 | if l_match: 103 | word = l_match.group() 104 | print(f'Found word starts with "w": {word}') 105 | else: 106 | t_match = TRAILING_W_WORD.search(s) 107 | if t_match: 108 | word = t_match.group() 109 | print(f'Found word ends with "w": {word}') 110 | ``` 111 | 112 | 1. 定义一个变量 `l_match` 保存 `.search()` 返回的匹配结果 113 | 114 | 但这样虽然消除了重复，却引入了更深的嵌套层级，还是难以让人满意。 115 | 116 | 有了赋值表达式后，我们可以更进一步，直接在分支判断语句中一次性完成表达式的运算和赋值。于是，代码可以被进一步简化成这样： 117 | 118 | ```python 119 | def find_w_word_v3(s): 120 | """找到并打印字符串中第一个以 w 开头的单词，如未找到，再试着找 w 结尾的""" 121 | if l_match := LEADING_W_WORD.search(s): 122 | word = l_match.group() 123 | print(f'Found word starts with "w": {word}') 124 | elif t_match := TRAILING_W_WORD.search(s): 125 | word = t_match.group() 126 | print(f'Found word ends with "w": {word}') 127 | ``` 128 | 129 | 修改之后，代码变得更扁平，逻辑也更加紧凑了。 130 | 131 | 除了 `if` 条件分支，`while` 循环中也可以使用赋值表达式。比如，下面这种模式的循环代码十分常见： 132 | 133 | ```python 134 | while True: 135 | chunk = fp.read(2048) 136 | if not chunk: 137 | break 138 | # 继续后续对 chunk 的处理... 139 | ``` 140 | 141 | 如果使用赋值表达式，它可以被简化成下面这样： 142 | 143 | ```python 144 | while chunk := fp.read(2048): 145 | # 继续后续对 chunk 的处理... 146 | ``` 147 | 148 | #### 2. 消除推导式中的重复 149 | 150 | 前面演示了在分支语句中使用赋值表达式，除此之外，你也可以在各类推导式中使用它。 151 | 152 | 举个例子，在构建一个推导式时，我们有时可能会需要同时做到以下两件事： 153 | 154 | 1. 预计算每个成员，判断结果是否满足要求 155 | 2. 如满足，将预计算的结果置入新对象 156 | 157 | 下面的代码完成了这个功能： 158 | 159 | ```python 160 | # 仅挑选 func(...) > 100 的成员构建新列表 161 | new_objs = [func(p) for p in objs if func(p) > 100] 162 | ``` 163 | 164 | 虽然它满足需求，但也有一个严重的问题：`func(p)` 在每次迭代时会被重复执行两次，这很可能会成为一个潜在的性能隐患。 165 | 166 | 在以前，如果你想优化这个问题，除了把表达式拆成普通 `for` 循环外没什么其他办法。但有了赋值表达式，代码可被轻松优化成这样： 167 | 168 | ```python 169 | new_objs = [v for p in objs if (v := func(p)) > 100] 170 | ``` 171 | 172 | 重复的函数调用原地消失了。 173 | 174 | #### 3. 捕获推导式的中间结果 175 | 176 | 从某种角度上看，赋值表达式是一种有“副作用”的表达式，它的副作用就是在返回值的同时，完成变量赋值。如果你有意地利用这种副作用，就能完成一些相当出人意料的事情。 177 | 178 | 让我来举个例子。`any()` 是 Python 的一个内建函数，它接收一个可迭代对象作为参数，在遍历该对象的过程中，如果发现任何布尔值为真的成员，函数就立刻返回 `True`，否则返回 `False`。 179 | 180 | 一个常见的使用场景如下所示： 181 | 182 | ```python 183 | def has_lucky_number(nums): 184 | """判断给定的列表中，是否存在能被 7 整除的数字""" 185 | return any(n % 7 == 0 for n in nums) 186 | ``` 187 | 188 | 调用示例： 189 | 190 | ```python 191 | >>> has_lucky_number([4, 8, 9]) 192 | False 193 | >>> has_lucky_number([4, 8, 21, 9]) 194 | True 195 | ``` 196 | 197 | 某日，需求变更了。函数不仅需要知道是否存在被 7 整除的数字，还得把这个数字找出来。代码该怎么改？`any(...)` 像是肯定没法再用了，不如写一个平平无奇的 `for` 循环吧。 198 | 199 | 但其实，如果你使用赋值表达式搭配上 `any` 函数的短路执行特性，下面这几行代码也可以达成使命： 200 | 201 | ```python 202 | def get_lucky_number(nums): 203 | """返回列表中能被 7 整除的数字，如没有则返回 None""" 204 | if any((ret := n) % 7 == 0 for n in nums): 205 | return ret 206 | return None 207 | ``` 208 | 209 | 调用示例： 210 | 211 | ```python 212 | >>> get_lucky_number([4, 8, 9]) 213 | >>> get_lucky_number([4, 8, 21, 9]) 214 | 21 215 | ``` 216 | 217 | 和之前相比，新代码最主要的修改在于将 `n` 替换成了 `(ret := n)`——一个有副作用的赋值表达式。在 `any` 函数进行循环遍历 `nums` 列表的过程中，当前被迭代的成员 `n` 会被赋到 `ret` 变量上，如其刚好满足条件，就会直接被当做结果返回。 218 | 219 | 借助赋值表达式的副作用，我们成功捕获了第一个满足条件的成员，只用一行代码就实现了需求。 220 | 221 | #### 4. 赋值表达式的限制 222 | 223 | 从外观上看，赋值表达式和赋值语句极为相似，仅多了一个冒号 `:`。但如果你继续深入，会发现它其实被施加了许多普通赋值语句所没有的限制。 224 | 225 | 比如，它在作为整句独立使用时，两边必须添加括号： 226 | 227 | ``` 228 | >>> x := 1 229 | SyntaxError: invalid syntax 230 | >>> (x := 1) 231 | 1 232 | ``` 233 | 234 | 此外，赋值表达式也无法直接操作对象属性（或字典的键）： 235 | 236 | ```python 237 | # 普通赋值语句 238 | >>> s.foo = 'bar' 239 | >>> d['foo'] = 'bar' 240 | 241 | # 赋值表达式无法做到 242 | >>> (s.foo := 'bar') 243 | SyntaxError: cannot use assignment expressions with attribute 244 | >>> (d['foo'] := 'bar') 245 | SyntaxError: cannot use assignment expressions with subscript 246 | ``` 247 | 248 | 诸如此类的限制，是语言设计者为避免人们滥用赋值表达式而为之。但即便有着这些限制，赋值表达式这个 Python 3.8 中增加的新语法，已然为人们在 Python 中“遣词造句”，带来了巨大的可能性和想象空间。 249 | 250 | > 如果你想了解更多关于”赋值表达式“的细节，建议阅读官方 PEP： [PEP 572 – Assignment Expressions](https://peps.python.org/pep-0572/)。 251 | 252 | ### 其他建议 253 | 254 | 下面是关于”赋值表达式“的两个使用建议。 255 | 256 | #### 1. “更紧凑”不等于“更好” 257 | 258 | 正如前面所展示的，我们可以像玩积木一样组合使用赋值表达式，写出更精炼、更紧凑的代码。但对于代码而言，“更紧凑”不能和“更好”画上等号。关于这点，我很喜欢 Tim Peters 举过的[一个简单例子](https://peps.python.org/pep-0572/#appendix-a-tim-peters-s-findings)。 259 | 260 | Tim Peters 说自己不喜欢“匆匆忙忙”的代码，讨厌将概念上无关的逻辑写到同一行代码里。比方说，与其像下面这样写： 261 | 262 | ```python 263 | i = j = count = nerrors = 0 264 | ``` 265 | 266 | 他更倾向于改成这样： 267 | 268 | ```python 269 | i = j = 0 270 | count = 0 271 | nerrors = 0 272 | ``` 273 | 274 | 第一种写法虽然紧凑，但其实忽视了一件重要的事：这几个变量分属 3 类不同用途（分别是循环索引值、个数和错误数量），它们只是碰巧都为 `0` 而已。将代码拆成 3 行以后，虽没那么紧凑，但概念上实际变得更清晰了。 275 | 276 | 在使用赋值表达式时，我们尤其需要避免掉进盲目追求“精炼”和“紧凑”的陷阱里，多多关注每行代码在逻辑上的联系，而不要整日盯着**字面意义上**的精简。 277 | 278 | #### 2. 宜少不宜多 279 | 280 | 赋值表达式是 Python 3.8 引入的新特性，已经发布 3 年有余。但就自身感受而言，除了在一些 Python 教程文章中，我在其他项目里极少见到它的身影。 281 | 282 | 人们很少使用赋值表达式，我猜主要出于两方面的原因。 283 | 284 | 其一，Python 3.8 仍是一个相对较新的版本，许多项目尚未完成版本升级。其二，赋值表达式本身非常灵活，适用场景非常多，使用起来难以把控尺度，因此许多开发者对其抱着较为警惕的态度。再加上它本身也不提供任何普通语句做不到的独特功能——不是雪中送炭，只是锦上添花——因此大家不愿尝鲜。 285 | 286 | 上面的第一类原因，随着时间的推移会慢慢得到解决。我们主要看第二类。 287 | 288 | 我认为，大部分开发者的担忧确实有一定道理，赋值表达式在将代码变得紧凑的同时，也带来了更高的理解成本和上手门槛。而且平心而论，一些用了赋值表达式的代码，真的会给我一种“*这么写是不是过于聪明了？*”的感觉。 289 | 290 | 拿之前的这段代码为例： 291 | 292 | ```python 293 | if any((ret := n) % 7 == 0 for n in nums): 294 | return ret 295 | ``` 296 | 297 | 如果是一个私人脚本，也许我会愿意把代码写成上面那样。但在多人参与的真实项目里，我目前可能更愿意用一段平平无奇的 `for` 循环替代它。很多时候，相比“聪明”的代码，“笨”代码才是我们更需要的东西，它们能为项目的参与者省去许多沟通和维护上的成本。 298 | 299 | 总体而言，关于是否应该在项目中使用赋值表达式，我的建议是： 300 | 301 | - 在分支语句的消除重复场景，使用赋值表达式 302 | - 在推导式的消除重复场景，使用赋值表达式 303 | - 其他情况下，优先使用普通赋值语句，哪怕这意味着更多代码和少量重复（比如“获取第一个满足条件的成员”场景） 304 | 305 | 希望以上的内容对你有所帮助。 306 | 307 | > 这篇文章属于“Python 工匠”系列，如果你喜欢它，也欢迎了解我的书[《Python工匠：案例、技巧与工程实践》\[试读\]](https://www.piglei.com/book/index.html) | [\[书评\]](https://book.douban.com/subject/35723705/)，其中有大量同样风格的 Python 编程进阶知识。 308 | -------------------------------------------------------------------------------- /zh_CN/2-if-else-block-secrets.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：编写条件分支代码的技巧 2 | 3 | ## 序言 4 | 5 | > 这是 “Python 工匠”系列的第 2 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 | 编写条件分支代码是编码过程中不可或缺的一部分。 8 | 9 | 如果用道路来做比喻，现实世界中的代码从来都不是一条笔直的高速公路，而更像是由无数个岔路口组成的某个市区地图。我们编码者就像是驾驶员，需要告诉我们的程序，下个路口需要往左还是往右。 10 | 11 | 编写优秀的条件分支代码非常重要，因为糟糕、复杂的分支处理非常容易让人困惑，从而降低代码质量。所以，这篇文章将会重点谈谈在 Python 中编写分支代码应该注意的地方。 12 | 13 | ### 内容目录 14 | 15 | - [Python 工匠：编写条件分支代码的技巧](#python-工匠编写条件分支代码的技巧) 16 | - [序言](#序言) 17 | - [内容目录](#内容目录) 18 | - [Python 里的分支代码](#python-里的分支代码) 19 | - [最佳实践](#最佳实践) 20 | - [1. 避免多层分支嵌套](#1-避免多层分支嵌套) 21 | - [2. 封装那些过于复杂的逻辑判断](#2-封装那些过于复杂的逻辑判断) 22 | - [3. 留意不同分支下的重复代码](#3-留意不同分支下的重复代码) 23 | - [4. 谨慎使用三元表达式](#4-谨慎使用三元表达式) 24 | - [常见技巧](#常见技巧) 25 | - [1. 使用“德摩根定律”](#1-使用德摩根定律) 26 | - [2. 自定义对象的“布尔真假”](#2-自定义对象的布尔真假) 27 | - [3. 在条件判断中使用 all() / any()](#3-在条件判断中使用-all--any) 28 | - [4. 使用 try/while/for 中 else 分支](#4-使用-trywhilefor-中-else-分支) 29 | - [常见陷阱](#常见陷阱) 30 | - [1. 与 None 值的比较](#1-与-none-值的比较) 31 | - [2. 留意 and 和 or 的运算优先级](#2-留意-and-和-or-的运算优先级) 32 | - [结语](#结语) 33 | - [注解](#注解) 34 | 35 | ### Python 里的分支代码 36 | 37 | Python 支持最为常见的 `if/else` 条件分支语句，不过它缺少在其他编程语言中常见的 `switch/case` 语句。 38 | 39 | 除此之外，Python 还为 `for/while` 循环以及 `try/except` 语句提供了 else 分支，在一些特殊的场景下，它们可以大显身手。 40 | 41 | 下面我会从 `最佳实践`、`常见技巧`、`常见陷阱` 三个方面讲一下如果编写优秀的条件分支代码。 42 | 43 | ## 最佳实践 44 | 45 | ### 1. 避免多层分支嵌套 46 | 47 | 如果这篇文章只能删减成一句话就结束，那么那句话一定是**“要竭尽所能的避免分支嵌套”**。 48 | 49 | 过深的分支嵌套是很多编程新手最容易犯的错误之一。假如有一位新手 JavaScript 程序员写了很多层分支嵌套，那么你可能会看到一层又一层的大括号：`if { if { if { ... }}}`。俗称 *“嵌套 if 地狱（Nested If Statement Hell）”*。 50 | 51 | 但是因为 Python 使用了缩进来代替 `{}`，所以过深的嵌套分支会产生比其他语言下更为严重的后果。比如过多的缩进层次很容易就会让代码超过 [PEP8](https://www.python.org/dev/peps/pep-0008/) 中规定的每行字数限制。让我们看看这段代码： 52 | 53 | ```python 54 | def buy_fruit(nerd, store): 55 | """去水果店买苹果 56 | 57 | - 先得看看店是不是在营业 58 | - 如果有苹果的话，就买 1 个 59 | - 如果钱不够，就回家取钱再来 60 | """ 61 | if store.is_open(): 62 | if store.has_stocks("apple"): 63 | if nerd.can_afford(store.price("apple", amount=1)): 64 | nerd.buy(store, "apple", amount=1) 65 | return 66 | else: 67 | nerd.go_home_and_get_money() 68 | return buy_fruit(nerd, store) 69 | else: 70 | raise MadAtNoFruit("no apple in store!") 71 | else: 72 | raise MadAtNoFruit("store is closed!") 73 | ``` 74 | 75 | 上面这段代码最大的问题，就是过于直接翻译了原始的条件分支要求，导致短短十几行代码包含了有三层嵌套分支。 76 | 77 | 这样的代码可读性和维护性都很差。不过我们可以用一个很简单的技巧：**“提前结束”** 来优化这段代码： 78 | 79 | ```python 80 | def buy_fruit(nerd, store): 81 | if not store.is_open(): 82 | raise MadAtNoFruit("store is closed!") 83 | 84 | if not store.has_stocks("apple"): 85 | raise MadAtNoFruit("no apple in store!") 86 | 87 | if nerd.can_afford(store.price("apple", amount=1)): 88 | nerd.buy(store, "apple", amount=1) 89 | return 90 | else: 91 | nerd.go_home_and_get_money() 92 | return buy_fruit(nerd, store) 93 | ``` 94 | 95 | “提前结束”指：**在函数内使用 `return` 或 `raise` 等语句提前在分支内结束函数。** 比如，在新的 `buy_fruit` 函数里，当分支条件不满足时，我们直接抛出异常，结束这段代码分支。这样的代码没有嵌套分支，更直接也更易读。 96 | 97 | ### 2. 封装那些过于复杂的逻辑判断 98 | 99 | 如果条件分支里的表达式过于复杂，出现了太多的 `not/and/or`，那么这段代码的可读性就会大打折扣，比如下面这段代码： 100 | 101 | ``` 102 | # 如果活动还在开放，并且活动剩余名额大于 10，为所有性别为女性，或者级别大于 3 103 | # 的活跃用户发放 10000 个金币 104 | if activity.is_active and activity.remaining > 10 and \ 105 | user.is_active and (user.sex == 'female' or user.level > 3): 106 | user.add_coins(10000) 107 | return 108 | ``` 109 | 110 | 对于这样的代码，我们可以考虑将具体的分支逻辑封装成函数或者方法，来达到简化代码的目的： 111 | 112 | ``` 113 | if activity.allow_new_user() and user.match_activity_condition(): 114 | user.add_coins(10000) 115 | return 116 | ``` 117 | 118 | 事实上，将代码改写后，之前的注释文字其实也可以去掉了。**因为后面这段代码已经达到了自说明的目的。** 至于具体的 *什么样的用户满足活动条件？* 这种问题，就应由具体的 `match_activity_condition()` 方法来回答了。 119 | 120 | > **Hint:** 恰当的封装不光直接改善了代码的可读性，事实上，如果上面的活动判断逻辑在代码中出现了不止一次的话，封装更是必须的。不然重复代码会极大的破坏这段逻辑的可维护性。 121 | 122 | ### 3. 留意不同分支下的重复代码 123 | 124 | 重复代码是代码质量的天敌，而条件分支语句又非常容易成为重复代码的重灾区。所以，当我们编写条件分支语句时，需要特别留意，不要生产不必要的重复代码。 125 | 126 | 让我们看下这个例子： 127 | 128 | ```python 129 | # 对于新用户，创建新的用户资料，否则更新旧资料 130 | if user.no_profile_exists: 131 | create_user_profile( 132 | username=user.username, 133 | email=user.email, 134 | age=user.age, 135 | address=user.address, 136 | # 对于新建用户，将用户的积分置为 0 137 | points=0, 138 | created=now(), 139 | ) 140 | else: 141 | update_user_profile( 142 | username=user.username, 143 | email=user.email, 144 | age=user.age, 145 | address=user.address, 146 | updated=now(), 147 | ) 148 | ``` 149 | 150 | 在上面的代码中，我们可以一眼看出，在不同的分支下，程序调用了不同的函数，做了不一样的事情。但是，因为那些重复代码的存在，**我们却很难简单的区分出，二者的不同点到底在哪。** 151 | 152 | 其实，得益于 Python 的动态特性，我们可以简单的改写一下上面的代码，让可读性可以得到显著的提升： 153 | 154 | ```python 155 | if user.no_profile_exists: 156 | profile_func = create_user_profile 157 | extra_args = {'points': 0, 'created': now()} 158 | else: 159 | profile_func = update_user_profile 160 | extra_args = {'updated': now()} 161 | 162 | profile_func( 163 | username=user.username, 164 | email=user.email, 165 | age=user.age, 166 | address=user.address, 167 | **extra_args 168 | ) 169 | ``` 170 | 171 | 当你编写分支代码时，请额外关注**由分支产生的重复代码块**，如果可以简单的消灭它们，那就不要迟疑。 172 | 173 | ### 4. 谨慎使用三元表达式 174 | 175 | 三元表达式是 Python 2.5 版本后才支持的语法。在那之前，Python 社区一度认为三元表达式没有必要，我们需要使用 `x and a or b` 的方式来模拟它。[[注]](#annot1) 176 | 177 | 事实是，在很多情况下，使用普通的 `if/else` 语句的代码可读性确实更好。盲目追求三元表达式很容易诱惑你写出复杂、可读性差的代码。 178 | 179 | 所以，请记得只用三元表达式处理简单的逻辑分支。 180 | 181 | ```python 182 | language = "python" if you.favor("dynamic") else "golang" 183 | ``` 184 | 185 | 对于绝大多数情况，还是使用普通的 `if/else` 语句吧。 186 | 187 | ## 常见技巧 188 | 189 | ### 1. 使用“德摩根定律” 190 | 191 | 在做分支判断时，我们有时候会写成这样的代码： 192 | 193 | ```python 194 | # 如果用户没有登录或者用户没有使用 chrome，拒绝提供服务 195 | if not user.has_logged_in or not user.is_from_chrome: 196 | return "our service is only available for chrome logged in user" 197 | ``` 198 | 199 | 第一眼看到代码时，是不是需要思考一会才能理解它想干嘛？这是因为上面的逻辑表达式里面出现了 2 个 `not` 和 1 个 `or`。而我们人类恰好不擅长处理过多的“否定”以及“或”这种逻辑关系。 200 | 201 | 这个时候，就该 [德摩根定律](https://zh.wikipedia.org/wiki/%E5%BE%B7%E6%91%A9%E6%A0%B9%E5%AE%9A%E5%BE%8B) 出场了。通俗的说，德摩根定律就是 `not A or not B` 等价于 `not (A and B)`。通过这样的转换，上面的代码可以改写成这样： 202 | 203 | ```python 204 | if not (user.has_logged_in and user.is_from_chrome): 205 | return "our service is only available for chrome logged in user" 206 | ``` 207 | 208 | 怎么样，代码是不是易读了很多？记住德摩根定律，很多时候它对于简化条件分支里的代码逻辑非常有用。 209 | 210 | ### 2. 自定义对象的“布尔真假” 211 | 212 | 我们常说，在 Python 里，“万物皆对象”。其实，不光“万物皆对象”，我们还可以利用很多魔法方法*（文档中称为：[user-defined method](https://docs.python.org/3/reference/datamodel.html)）*，来自定义对象的各种行为。我们可以用很多在别的语言里面无法做到、有些魔法的方式来影响代码的执行。 213 | 214 | 比如，Python 的所有对象都有自己的“布尔真假”： 215 | 216 | - 布尔值为假的对象：`None`, `0`, `False`, `[]`, `()`, `{}`, `set()`, `frozenset()`, ... ... 217 | - 布尔值为真的对象：非 `0` 的数值、`True`，非空的序列、元组，普通的用户类实例，... ... 218 | 219 | 通过内建函数 `bool()`，你可以很方便的查看某个对象的布尔真假。而 Python 进行条件分支判断时用到的也是这个值： 220 | 221 | ```python 222 | >>> bool(object()) 223 | True 224 | ``` 225 | 226 | 重点来了，虽然所有用户类实例的布尔值都是真。但是 Python 提供了改变这个行为的办法：**自定义类的 `__bool__` 魔法方法** *（在 Python 2.X 版本中为 `__nonzero__`）*。当类定义了 `__bool__` 方法后，它的返回值将会被当作类实例的布尔值。 227 | 228 | 另外，`__bool__` 不是影响实例布尔真假的唯一方法。如果类没有定义 `__bool__` 方法，Python 还会尝试调用 `__len__` 方法*（也就是对任何序列对象调用 `len` 函数）*，通过结果是否为 `0` 判断实例真假。 229 | 230 | 那么这个特性有什么用呢？看看下面这段代码： 231 | 232 | ```python 233 | class UserCollection(object): 234 | 235 | def __init__(self, users): 236 | self._users = users 237 | 238 | 239 | users = UserCollection([piglei, raymond]) 240 | 241 | if len(users._users) > 0: 242 | print("There's some users in collection!") 243 | ``` 244 | 245 | 上面的代码里，判断 `UserCollection` 是否有内容时用到了 `users._users` 的长度。其实，通过为 `UserCollection` 添加 `__len__` 魔法方法，上面的分支可以变得更简单： 246 | 247 | ```python 248 | class UserCollection: 249 | 250 | def __init__(self, users): 251 | self._users = users 252 | 253 | def __len__(self): 254 | return len(self._users) 255 | 256 | 257 | users = UserCollection([piglei, raymond]) 258 | 259 | # 定义了 __len__ 方法后，UserCollection 对象本身就可以被用于布尔判断了 260 | if users: 261 | print("There's some users in collection!") 262 | ``` 263 | 264 | 通过定义魔法方法 `__len__` 和 `__bool__` ，我们可以让类自己控制想要表现出的布尔真假值，让代码变得更 pythonic。 265 | 266 | ### 3. 在条件判断中使用 all() / any() 267 | 268 | `all()` 和 `any()` 两个函数非常适合在条件判断中使用。这两个函数接受一个可迭代对象，返回一个布尔值，其中： 269 | 270 | - `all(seq)`：仅当 `seq` 中所有对象都为布尔真时返回 `True`，否则返回 `False` 271 | - `any(seq)`：只要 `seq` 中任何一个对象为布尔真就返回 `True`，否则返回 `False` 272 | 273 | 假如我们有下面这段代码： 274 | 275 | ```python 276 | def all_numbers_gt_10(numbers): 277 | """仅当序列中所有数字大于 10 时，返回 True 278 | """ 279 | if not numbers: 280 | return False 281 | 282 | for n in numbers: 283 | if n <= 10: 284 | return False 285 | return True 286 | ``` 287 | 288 | 如果使用 `all()` 内建函数，再配合一个简单的生成器表达式，上面的代码可以写成这样： 289 | 290 | ```python 291 | def all_numbers_gt_10_2(numbers): 292 | return bool(numbers) and all(n > 10 for n in numbers) 293 | ``` 294 | 295 | 简单、高效，同时也没有损失可用性。 296 | 297 | ### 4. 使用 try/while/for 中 else 分支 298 | 299 | 让我们看看这个函数： 300 | 301 | ```python 302 | def do_stuff(): 303 | first_thing_successed = False 304 | try: 305 | do_the_first_thing() 306 | first_thing_successed = True 307 | except Exception as e: 308 | print("Error while calling do_some_thing") 309 | return 310 | 311 | # 仅当 first_thing 成功完成时，做第二件事 312 | if first_thing_successed: 313 | return do_the_second_thing() 314 | ``` 315 | 316 | 在函数 `do_stuff` 中，我们希望只有当 `do_the_first_thing()` 成功调用后*（也就是不抛出任何异常）*，才继续做第二个函数调用。为了做到这一点，我们需要定义一个额外的变量 `first_thing_successed` 来作为标记。 317 | 318 | 其实，我们可以用更简单的方法达到同样的效果： 319 | 320 | ```python 321 | def do_stuff(): 322 | try: 323 | do_the_first_thing() 324 | except Exception as e: 325 | print("Error while calling do_some_thing") 326 | return 327 | else: 328 | return do_the_second_thing() 329 | ``` 330 | 331 | 在 `try` 语句块最后追加上 `else` 分支后，分支下的`do_the_second_thing()` 便只会在 **try 下面的所有语句正常执行（也就是没有异常，没有 return、break 等）完成后执行**。 332 | 333 | 类似的，Python 里的 `for/while` 循环也支持添加 `else` 分支，它们表示：当循环使用的迭代对象被正常耗尽、或 while 循环使用的条件变量变为 False 后才执行 else 分支下的代码。 334 | 335 | ## 常见陷阱 336 | 337 | ### 1. 与 None 值的比较 338 | 339 | 在 Python 中，有两种比较变量的方法：`==` 和 `is`，二者在含义上有着根本的区别： 340 | 341 | - `==`：表示二者所指向的的**值**是否一致 342 | - `is`：表示二者是否指向内存中的同一份内容，也就是 `id(x)` 是否等于 `id(y)` 343 | 344 | `None` 在 Python 语言中是一个单例对象，如果你要判断某个变量是否为 None 时，记得使用 `is` 而不是 `==`，因为只有 `is` 才能在严格意义上表示某个变量是否是 None。 345 | 346 | 否则，可能出现下面这样的情况： 347 | 348 | ```python 349 | >>> class Foo(object): 350 | ... def __eq__(self, other): 351 | ... return True 352 | ... 353 | >>> foo = Foo() 354 | >>> foo == None 355 | True 356 | ``` 357 | 358 | 在上面代码中，Foo 这个类通过自定义 `__eq__` 魔法方法的方式，很容易就满足了 `== None` 这个条件。 359 | 360 | **所以，当你要判断某个变量是否为 None 时，请使用 `is` 而不是 `==`。** 361 | 362 | ### 2. 留意 and 和 or 的运算优先级 363 | 364 | 看看下面这两个表达式，猜猜它们的值一样吗？ 365 | 366 | ```python 367 | >>> (True or False) and False 368 | >>> True or False and False 369 | ``` 370 | 371 | 答案是：不一样，它们的值分别是 `False` 和 `True`，你猜对了吗？ 372 | 373 | 问题的关键在于：**`and` 运算符的优先级大于 `or`**。因此上面的第二个表达式在 Python 看来实际上是 `True or (False and False)`。所以结果是 `True` 而不是 `False`。 374 | 375 | 在编写包含多个 `and` 和 `or` 的表达式时，请额外注意 `and` 和 `or` 的运算优先级。即使执行优先级正好是你需要的那样，你也可以加上额外的括号来让代码更清晰。 376 | 377 | ## 结语 378 | 379 | 以上就是『Python 工匠』系列文章的第二篇。不知道文章的内容是否对你的胃口。 380 | 381 | 代码内的分支语句不可避免，我们在编写代码时，需要尤其注意它的可读性，避免对其他看到代码的人造成困扰。 382 | 383 | 看完文章的你，有没有什么想吐槽的？请留言告诉我吧。 384 | 385 | [>>>下一篇【3.使用数字与字符串的技巧】](3-tips-on-numbers-and-strings.md) 386 | 387 | [<<<上一篇【1.善用变量来改善代码质量】](1-using-variables-well.md) 388 | 389 | ## 注解 390 | 391 | 1. 事实上 `x and a or b` 不是总能给你正确的结果，只有当 a 与 b 的布尔值为真时，这个表达式才能正常工作，这是由逻辑运算的短路特性决定的。你可以在命令行中运行 `True and None or 0` 试试看，结果是 0 而非 None。 392 | 393 | > 文章更新记录： 394 | > 395 | > - 2018.04.08：在与 @geishu 的讨论后，调整了“运算优先符”使用的代码样例 396 | > - 2018.04.10：根据 @dongweiming 的建议，添加注解说明 "x and y or c" 表达式的陷阱 397 | 398 | -------------------------------------------------------------------------------- /zh_CN/3-tips-on-numbers-and-strings.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：使用数字与字符串的技巧 2 | 3 | 4 | ## 序言 5 | 6 | > 这是 “Python 工匠”系列的第 3 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 7 | 8 | 数字是几乎所有编程语言里最基本的数据类型，它是我们通过代码连接现实世界的基础。在 Python 里有三种数值类型：整型（int）、浮点型（float）和复数（complex）。绝大多数情况下，我们只需要和前两种打交道。 9 | 10 | 整型在 Python 中比较让人省心，因为它不区分有无符号并且永不溢出。但浮点型仍和绝大多数其他编程语言一样，依然有着精度问题，经常让很多刚进入编程世界大门的新人们感到困惑：["Why Are Floating Point Numbers Inaccurate?"](https://stackoverflow.com/questions/21895756/why-are-floating-point-numbers-inaccurate)。 11 | 12 | 相比数字，Python 里的字符串要复杂的多。要掌握它，你得先弄清楚 bytes 和 str 的区别。如果更不巧，你还是位 Python2 用户的话，光 unicode 和字符编码问题就够你喝上好几壶了 *（赶快迁移到 Python3 吧，就在今天！）*。 13 | 14 | 不过，上面提到的这些都不是这篇文章的主题，如果感兴趣，你可以在网上找到成堆的相关资料。在这篇文章里，我们将讨论一些 **更细微、更不常见** 的编程实践。来帮助你写出更好的 Python 代码。 15 | 16 | ### 内容目录 17 | 18 | - [Python 工匠：使用数字与字符串的技巧](#python-工匠使用数字与字符串的技巧) 19 | - [序言](#序言) 20 | - [内容目录](#内容目录) 21 | - [最佳实践](#最佳实践) 22 | - [1. 少写数字字面量](#1-少写数字字面量) 23 | - [使用 enum 枚举类型改善代码](#使用-enum-枚举类型改善代码) 24 | - [2. 别在裸字符串处理上走太远](#2-别在裸字符串处理上走太远) 25 | - [3. 不必预计算字面量表达式](#3-不必预计算字面量表达式) 26 | - [实用技巧](#实用技巧) 27 | - [1. 布尔值其实也是“数字”](#1-布尔值其实也是数字) 28 | - [2. 改善超长字符串的可读性](#2-改善超长字符串的可读性) 29 | - [当多级缩进里出现多行字符串时](#当多级缩进里出现多行字符串时) 30 | - [大数字也可以变得更加可读](#大数字也可以变得更加可读) 31 | - [3. 别忘了那些 “r” 开头的内建字符串函数](#3-别忘了那些-r-开头的内建字符串函数) 32 | - [4. 使用“无穷大” float("inf")](#4-使用无穷大-floatinf) 33 | - [常见误区](#常见误区) 34 | - [1. “value += 1” 并非线程安全](#1-value--1-并非线程安全) 35 | - [2. 字符串拼接并不慢](#2-字符串拼接并不慢) 36 | - [结语](#结语) 37 | 38 | ## 最佳实践 39 | 40 | ### 1. 少写数字字面量 41 | 42 | “数字字面量（integer literal）” 是指那些直接出现在代码里的数字。它们分布在代码里的各个角落，比如代码 `del users[0]` 里的 `0` 就是一个数字字面量。它们简单、实用，每个人每天都在写。**但是，当你的代码里不断重复出现一些特定字面量时，你的“代码质量告警灯”就应该亮起黄灯 🚥 了。** 43 | 44 | 举个例子，假如你刚加入一家心仪已久的新公司，同事转交给你的项目里有这么一个函数： 45 | 46 | ```python 47 | def mark_trip_as_featured(trip): 48 | """将某个旅程添加到推荐栏目 49 | """ 50 | if trip.source == 11: 51 | do_some_thing(trip) 52 | elif trip.source == 12: 53 | do_some_other_thing(trip) 54 | ... ... 55 | return 56 | ``` 57 | 58 | 这个函数做了什么事？你努力想搞懂它的意思，不过 `trip.source == 11` 是什么情况？那 `== 12` 呢？这两行代码很简单，没有用到任何魔法特性。但初次接触代码的你可能需要花费**一整个下午**，才能弄懂它们的含义。 59 | 60 | **问题就出在那几个数字字面量上。** 最初写下这个函数的人，可能是在公司成立之初加入的那位元老程序员。而他对那几个数字的含义非常清楚。但如果你是一位刚接触这段代码的新人，就完全是另外一码事了。 61 | 62 | #### 使用 enum 枚举类型改善代码 63 | 64 | 那么，怎么改善这段代码？最直接的方式，就是为这两个条件分支添加注释。不过在这里，“添加注释”显然不是提升代码可读性的最佳办法*（其实在绝大多数其他情况下都不是）*。我们需要用有意义的名称来代替这些字面量，而`枚举类型（enum）`用在这里最合适不过了。 65 | 66 | `enum` 是 Python 自 3.4 版本引入的内置模块，如果你使用的是更早的版本，可以通过 `pip install enum34` 来安装它。下面是使用 enum 的样例代码： 67 | 68 | ```python 69 | # -*- coding: utf-8 -*- 70 | from enum import IntEnum 71 | 72 | class TripSource(IntEnum): 73 | FROM_WEBSITE = 11 74 | FROM_IOS_CLIENT = 12 75 | 76 | 77 | def mark_trip_as_featured(trip): 78 | if trip.source == TripSource.FROM_WEBSITE: 79 | do_some_thing(trip) 80 | elif trip.source == TripSource.FROM_IOS_CLIENT: 81 | do_some_other_thing(trip) 82 | ... ... 83 | return 84 | ``` 85 | 86 | 将重复出现的数字字面量定义成枚举类型，不光可以改善代码的可读性，代码出现 Bug 的几率也会降低。 87 | 88 | 试想一下，如果你在某个分支判断时将 `11` 错打成了 `111` 会怎么样？我们时常会犯这种错，而这类错误在早期特别难被发现。将这些数字字面量全部放入枚举类型中可以比较好的规避这类问题。类似的，将字符串字面量改写成枚举也可以获得同样的好处。 89 | 90 | 使用枚举类型代替字面量的好处： 91 | 92 | - **提升代码可读性**：所有人都不需要记忆某个神奇的数字代表什么 93 | - **提升代码正确性**：减少打错数字或字母产生 bug 的可能性 94 | 95 | 当然，你完全没有必要把代码里的所有字面量都改成枚举类型。 **代码里出现的字面量，只要在它所处的上下文里面容易理解，就可以使用它。** 比如那些经常作为数字下标出现的 `0` 和 `-1` 就完全没有问题，因为所有人都知道它们的意思。 96 | 97 | ### 2. 别在裸字符串处理上走太远 98 | 99 | 什么是“裸字符串处理”？在这篇文章里，它指**只使用基本的加减乘除和循环、配合内置函数/方法来操作字符串，获得我们需要的结果。** 100 | 101 | 所有人都写过这样的代码。有时候我们需要拼接一大段发给用户的告警信息，有时我们需要构造一大段发送给数据库的 SQL 查询语句，就像下面这样： 102 | 103 | ```python 104 | def fetch_users(conn, min_level=None, gender=None, has_membership=False, sort_field="created"): 105 | """获取用户列表 106 | 107 | :param int min_level: 要求的最低用户级别，默认为所有级别 108 | :param int gender: 筛选用户性别，默认为所有性别 109 | :param int has_membership: 筛选所有会员/非会员用户，默认非会员 110 | :param str sort_field: 排序字段，默认为按 created "用户创建日期" 111 | :returns: 列表：[(User ID, User Name), ...] 112 | """ 113 | # 一种古老的 SQL 拼接技巧，使用 "WHERE 1=1" 来简化字符串拼接操作 114 | # 区分查询 params 来避免 SQL 注入问题 115 | statement = "SELECT id, name FROM users WHERE 1=1" 116 | params = [] 117 | if min_level is not None: 118 | statement += " AND level >= ?" 119 | params.append(min_level) 120 | if gender is not None: 121 | statement += " AND gender >= ?" 122 | params.append(gender) 123 | if has_membership: 124 | statement += " AND has_membership == true" 125 | else: 126 | statement += " AND has_membership == false" 127 | 128 | statement += " ORDER BY ?" 129 | params.append(sort_field) 130 | return list(conn.execute(statement, params)) 131 | ``` 132 | 133 | 我们之所以用这种方式拼接出需要的字符串 - *在这里是 SQL 语句* - 是因为这样做简单、直接，符合直觉。但是这样做最大的问题在于：**随着函数逻辑变得更复杂，这段拼接代码会变得容易出错、难以扩展。**事实上，上面这段 Demo 代码也只是仅仅做到**看上去**没有明显的 bug 而已 *（谁知道有没有其他隐藏问题）*。 134 | 135 | 其实，对于 SQL 语句这种结构化、有规则的字符串，用对象化的方式构建和编辑它才是更好的做法。下面这段代码用 [SQLAlchemy](https://www.sqlalchemy.org/) 模块完成了同样的功能： 136 | 137 | ```python 138 | def fetch_users_v2(conn, min_level=None, gender=None, has_membership=False, sort_field="created"): 139 | """获取用户列表 140 | """ 141 | query = select([users.c.id, users.c.name]) 142 | if min_level is not None: 143 | query = query.where(users.c.level >= min_level) 144 | if gender is not None: 145 | query = query.where(users.c.gender == gender) 146 | query = query.where(users.c.has_membership == has_membership).order_by(users.c[sort_field]) 147 | return list(conn.execute(query)) 148 | ``` 149 | 150 | 上面的 `fetch_users_v2` 函数更短也更好维护，而且根本不需要担心 SQL 注入问题。所以，当你的代码中出现复杂的裸字符串处理逻辑时，请试着用下面的方式替代它： 151 | 152 | `Q: 目标/源字符串是结构化的，遵循某种格式吗？` 153 | 154 | - 是：找找是否已经有开源的对象化模块操作它们，或是自己写一个 155 | - SQL：SQLAlchemy 156 | - XML：lxml 157 | - JSON、YAML ... 158 | - 否：尝试使用模板引擎而不是复杂字符串处理逻辑来达到目的 159 | - Jinja2 160 | - Mako 161 | - Mustache 162 | 163 | ### 3. 不必预计算字面量表达式 164 | 165 | 我们的代码里偶尔会出现一些比较复杂的数字，就像下面这样： 166 | 167 | ```python 168 | def f1(delta_seconds): 169 | # 如果时间已经过去了超过 11 天，不做任何事 170 | if delta_seconds > 950400: 171 | return 172 | ... 173 | ``` 174 | 175 | 话说在前头，上面的代码没有任何毛病。 176 | 177 | 首先，我们在小本子（当然，和我一样的聪明人会用 IPython）上算了算：`11天一共包含多少秒？`。然后再把结果 `950400` 这个神奇的数字填进我们的代码里，最后心满意足的在上面补上一行注释：告诉所有人这个神奇的数字是怎么来的。 178 | 179 | 我想问的是：*“为什么我们不直接把代码写成 `if delta_seconds < 11 * 24 * 3600:` 呢？”* 180 | 181 | **“性能”，答案一定会是“性能”**。我们都知道 Python 是一门~~（速度欠佳的）~~解释型语言，所以预先计算出 `950400` 正是因为我们不想让每次对函数 `f1` 的调用都带上这部分的计算开销。不过事实是：**即使我们把代码改成 `if delta_seconds < 11 * 24 * 3600:`，函数也不会多出任何额外的开销。** 182 | 183 | Python 代码在执行时会被解释器编译成字节码，而真相就藏在字节码里。让我们用 dis 模块看看： 184 | 185 | ```python 186 | def f1(delta_seconds): 187 | if delta_seconds < 11 * 24 * 3600: 188 | return 189 | 190 | import dis 191 | dis.dis(f1) 192 | 193 | # dis 执行结果 194 | 5 0 LOAD_FAST 0 (delta_seconds) 195 | 2 LOAD_CONST 1 (950400) 196 | 4 COMPARE_OP 0 (<) 197 | 6 POP_JUMP_IF_FALSE 12 198 | 199 | 6 8 LOAD_CONST 0 (None) 200 | 10 RETURN_VALUE 201 | >> 12 LOAD_CONST 0 (None) 202 | 14 RETURN_VALUE 203 | ``` 204 | 205 | 看见上面的 `2 LOAD_CONST 1 (950400)` 了吗？这表示 Python 解释器在将源码编译成成字节码时，会计算 `11 * 24 * 3600` 这段表达式，并用 `950400` 替换它。 206 | 207 | 所以，**当我们的代码中需要出现复杂计算的字面量时，请保留整个算式吧。它对性能没有任何影响，而且会增加代码的可读性。** 208 | 209 | > Hint：Python 解释器除了会预计算数值字面量表达式以外，还会对字符串、列表做类似的操作。一切都是为了性能。谁让你们老吐槽 Python 慢呢？ 210 | 211 | ## 实用技巧 212 | 213 | ### 1. 布尔值其实也是“数字” 214 | 215 | Python 里的两个布尔值 `True` 和 `False` 在绝大多数情况下都可以直接等价于 `1` 和 `0` 两个整数来使用，就像这样： 216 | 217 | ```python 218 | >>> True + 1 219 | 2 220 | >>> 1 / False 221 | Traceback (most recent call last): 222 | File "", line 1, in 223 | ZeroDivisionError: division by zero 224 | ``` 225 | 226 | 那么记住这点有什么用呢？首先，它们可以配合 `sum` 函数在需要计算总数时简化操作： 227 | 228 | ```python 229 | >>> l = [1, 2, 4, 5, 7] 230 | >>> sum(i % 2 == 0 for i in l) 231 | 2 232 | ``` 233 | 234 | 此外，如果将某个布尔值表达式作为列表的下标使用，可以实现类似三元表达式的目的： 235 | 236 | ```python 237 | # 类似的三元表达式："Javascript" if 2 > 1 else "Python" 238 | >>> ["Python", "Javascript"][2 > 1] 239 | 'Javascript' 240 | ``` 241 | 242 | ### 2. 改善超长字符串的可读性 243 | 244 | 单行代码的长度不宜太长。比如 PEP8 里就建议每行字符数不得超过 **79**。现实世界里，大部分人遵循的单行最大字符数在 79 到 119 之间。如果只是代码，这样的要求是比较容易达到的，但假设代码里需要出现一段超长的字符串呢？ 245 | 246 | 这时，除了使用斜杠 `\` 和加号 `+` 将长字符串拆分为好几段以外，还有一种更简单的办法：**使用括号将长字符串包起来，然后就可以随意折行了**： 247 | 248 | ```python 249 | s = ( 250 | "There is something really bad happened during the process. " 251 | "Please contact your administrator." 252 | ) 253 | print(s) 254 | 255 | 256 | def main(): 257 | logger.info( 258 | "There is something really bad happened during the process. " 259 | "Please contact your administrator." 260 | ) 261 | ``` 262 | 263 | #### 当多级缩进里出现多行字符串时 264 | 265 | 日常编码时，还有一种比较麻烦的情况。就是需要在已经有缩进层级的代码里，插入多行字符串字面量。因为多行字符串不能包含当前的缩进空格，所以，我们需要把代码写成这样： 266 | 267 | ```python 268 | def main(): 269 | if user.is_active: 270 | message = """Welcome, today's movie list: 271 | - Jaw (1975) 272 | - The Shining (1980) 273 | - Saw (2004)""" 274 | ``` 275 | 276 | 但是这样写会破坏整段代码的缩进视觉效果，显得非常突兀。要改善它有很多种办法，比如我们可以把这段多行字符串作为变量提取到模块的最外层。不过，如果在你的代码逻辑里更适合用字面量的话，你也可以用标准库 `textwrap` 来解决这个问题： 277 | 278 | ```python 279 | from textwrap import dedent 280 | 281 | def main(): 282 | if user.is_active: 283 | # dedent 将会缩进掉整段文字最左边的空字符串 284 | message = dedent("""\ 285 | Welcome, today's movie list: 286 | - Jaw (1975) 287 | - The Shining (1980) 288 | - Saw (2004)""") 289 | ``` 290 | 291 | #### 大数字也可以变得更加可读 292 | 293 | > 该小节内容由 [@laixintao](https://github.com/laixintao) 提供。 294 | 295 | 对那些特别大的数字，可以通过在中间添加下划线来提高可读性 296 | ([PEP515](https://www.python.org/dev/peps/pep-0515/)，需要 Python3.6+)。 297 | 298 | 比如： 299 | 300 | ```python 301 | >>> 10_000_000.0 # 以“千”为单位划分数字 302 | 10000000.0 303 | >>> 0xCAFE_F00D # 16进制数字同样有效，4个一组更易读 304 | 3405705229 305 | >>> 0b_0011_1111_0100_1110 # 二进制也有效 306 | 16206 307 | >>> int('0b_1111_0000', 2) # 处理字符串的时候也会正确处理下划线 308 | 240 309 | ``` 310 | 311 | ### 3. 别忘了那些 “r” 开头的内建字符串函数 312 | 313 | Python 的字符串有着非常多实用的内建方法，最常用的有 `.strip()`、`.split()` 等。这些内建方法里的大多数，处理起来的顺序都是从左往右。但是其中也包含了部分以 `r` 打头的**从右至左处理**的镜像方法。在处理特定逻辑时，使用它们可以让你事半功倍。 314 | 315 | 假设我们需要解析一些访问日志，日志格式为："{user_agent}" {content_length}： 316 | 317 | >>> log_line = '"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36" 47632' 318 | 319 | 320 | 如果使用 `.split()` 将日志拆分为 `(user_agent, content_length) `，我们需要这么写： 321 | 322 | ```python 323 | >>> l = log_line.split() 324 | >>> " ".join(l[:-1]), l[-1] 325 | ('"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36"', '47632') 326 | ``` 327 | 328 | 但是如果使用 `.rsplit()` 的话，处理逻辑就更直接了： 329 | 330 | ```python 331 | >>> log_line.rsplit(None, 1) 332 | ['"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36"', '47632'] 333 | ``` 334 | 335 | 336 | ### 4. 使用“无穷大” float("inf") 337 | 338 | 如果有人问你：*“Python 里什么数字最大/最小？”*。你应该怎么回答？有这样的东西存在吗？ 339 | 340 | 答案是：“有的，它们就是：`float("inf")` 和 `float("-inf")`”。它们俩分别对应着数学世界里的正负无穷大。当它们和任意数值进行比较时，满足这样的规律：`float("-inf") < 任意数值 < float("inf")`。 341 | 342 | 因为它们有着这样的特点，我们可以在某些场景用上它们： 343 | 344 | ```python 345 | # A. 根据年龄升序排序，没有提供年龄放在最后边 346 | >>> users = {"tom": 19, "jenny": 13, "jack": None, "andrew": 43} 347 | >>> sorted(users.keys(), key=lambda user: users.get(user) or float('inf')) 348 | ['jenny', 'tom', 'andrew', 'jack'] 349 | 350 | # B. 作为循环初始值，简化第一次判断逻辑 351 | >>> max_num = float('-inf') 352 | >>> # 找到列表中最大的数字 353 | >>> for i in [23, 71, 3, 21, 8]: 354 | ...: if i > max_num: 355 | ...: max_num = i 356 | ...: 357 | >>> max_num 358 | 71 359 | ``` 360 | 361 | ## 常见误区 362 | 363 | ### 1. “value += 1” 并非线程安全 364 | 365 | 当我们编写多线程程序时，经常需要处理复杂的共享变量和竞态等问题。 366 | 367 | “线程安全”，通常被用来形容 **某个行为或者某类数据结构，可以在多线程环境下被共享使用并产生预期内的结果。**一个典型的满足“线程安全”的模块就是 [queue 队列模块](https://docs.python.org/3/library/queue.html)。 368 | 369 | 而我们常做的 `value += 1` 操作，很容易被想当然的认为是“线程安全”的。因为它看上去就是一个原子操作 *（指一个最小的操作单位，执行途中不会插入任何其他操作）*。然而真相并非如此，虽然从 Python 代码上来看，`value += 1` 这个操作像是原子的。但它最终被 Python 解释器执行的时候，早就不再 *“原子”* 了。 370 | 371 | 我们可以用前面提到的 `dis` 模块来验证一下： 372 | 373 | ```python 374 | def incr(value): 375 | value += 1 376 | 377 | 378 | # 使用 dis 模块查看字节码 379 | import dis 380 | 381 | dis.dis(incr) 382 | 0 LOAD_FAST 0 (value) 383 | 2 LOAD_CONST 1 (1) 384 | 4 INPLACE_ADD 385 | 6 STORE_FAST 0 (value) 386 | 8 LOAD_CONST 0 (None) 387 | 10 RETURN_VALUE 388 | ``` 389 | 390 | 在上面输出结果中，可以看到这个简单的累加语句，会被编译成包括取值和保存在内的好几个不同步骤，而在多线程环境下，任意一个其他线程都有可能在其中某个步骤切入进来，阻碍你获得正确的结果。 391 | 392 | **因此，请不要凭借自己的直觉来判断某个行为是否“线程安全”，不然等程序在高并发环境下出现奇怪的 bug 时，你将为自己的直觉付出惨痛的代价。** 393 | 394 | ### 2. 字符串拼接并不慢 395 | 396 | 我刚接触 Python 不久时，在某个网站看到这样一个说法： *“Python 里的字符串是不可变的，所以每一次对字符串进行拼接都会生成一个新对象，导致新的内存分配，效率非常低”。* 我对此深信不疑。 397 | 398 | 所以，一直以来，我尽量都在避免使用 `+=` 的方式去拼接字符串，而是用 `"".join(str_list)` 之类的方式来替代。 399 | 400 | 但是，在某个偶然的机会下，我对 Python 的字符串拼接做了一次简单的性能测试后发现： **Python 的字符串拼接根本就不慢！** 在查阅了一些资料后，最终发现了真相。 401 | 402 | Python 的字符串拼接在 2.2 以及之前的版本确实很慢，和我最早看到的说法行为一致。但是因为这个操作太常用了，所以之后的版本里专门针对它做了性能优化。大大提升了执行效率。 403 | 404 | 如今使用 `+=` 的方式来拼接字符串，效率已经非常接近 `"".join(str_list)` 了。所以，该拼接时就拼接吧，不必担心任何性能问题。 405 | 406 | > Hint: 如果你想了解更详细的相关内容，可以读一下这篇文章：[Python - Efficient String Concatenation in Python (2016 edition) - smcl](http://blog.mclemon.io/python-efficient-string-concatenation-in-python-2016-edition) 407 | 408 | ## 结语 409 | 410 | 以上就是『Python 工匠』系列文章的第三篇，内容比较零碎。由于篇幅原因，一些常用的操作比如字符串格式化等，文章里并没有涵盖到。以后有机会再写吧。 411 | 412 | 让我们最后再总结一下要点： 413 | 414 | - 编写代码时，请考虑阅读者的感受，不要出现太多神奇的字面量 415 | - 当操作结构化字符串时，使用对象化模块比直接处理更有优势 416 | - dis 模块非常有用，请多多使用它验证你的猜测 417 | - 多线程环境下的编码非常复杂，要足够谨慎，不要相信自己的直觉 418 | - Python 语言的更新非常快，不要被别人的经验所左右 419 | 420 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 421 | 422 | [>>>下一篇【4.容器的门道】](4-mastering-container-types.md) 423 | 424 | [<<<上一篇【2.编写条件分支代码的技巧】](2-if-else-block-secrets.md) 425 | 426 | 427 | -------------------------------------------------------------------------------- /zh_CN/4-mastering-container-types.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：容器的门道 2 | 3 | ## 序言 4 | 5 | > 这是 “Python 工匠”系列的第 4 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 |
9 | 图片来源: "The Humble Mason Jar" by Chiot's Run - 非商业性使用 2.0 通用
10 |
11 | 12 | “容器”这两个字很少被 Python 技术文章提起。一看到“容器”，大家想到的多是那头蓝色小鲸鱼：*Docker*，但这篇文章和它没有任何关系。本文里的容器，是 Python 中的一个抽象概念，是对**专门用来装其他对象的数据类型**的统称。 13 | 14 | 在 Python 中，有四类最常见的内建容器类型：`列表（list）`、`元组（tuple）`、`字典（dict）`、`集合（set）`。通过单独或是组合使用它们，可以高效地完成很多事情。 15 | 16 | Python 语言自身的内部实现细节也与这些容器类型息息相关。比如 Python 的类实例属性、全局变量 `globals()` 等就都是通过字典类型来存储的。 17 | 18 | 在这篇文章里，我首先会从容器类型的定义出发，尝试总结出一些日常编码的最佳实践。之后再围绕各个容器类型提供的特殊机能，分享一些编程的小技巧。 19 | 20 | ### 内容目录 21 | 22 | - [Python 工匠：容器的门道](#python-工匠容器的门道) 23 | - [序言](#序言) 24 | - [内容目录](#内容目录) 25 | - [当我们谈论容器时，我们在谈些什么？](#当我们谈论容器时我们在谈些什么) 26 | - [底层看容器](#底层看容器) 27 | - [写更快的代码](#写更快的代码) 28 | - [1. 避免频繁扩充列表/创建新列表](#1-避免频繁扩充列表创建新列表) 29 | - [2. 在列表头部操作多的场景使用 deque 模块](#2-在列表头部操作多的场景使用-deque-模块) 30 | - [3. 使用集合/字典来判断成员是否存在](#3-使用集合字典来判断成员是否存在) 31 | - [高层看容器](#高层看容器) 32 | - [写扩展性更好的代码](#写扩展性更好的代码) 33 | - [面向容器接口编程](#面向容器接口编程) 34 | - [常用技巧](#常用技巧) 35 | - [1. 使用元组改善分支代码](#1-使用元组改善分支代码) 36 | - [2. 在更多地方使用动态解包](#2-在更多地方使用动态解包) 37 | - [3. 使用 next() 函数](#3-使用-next-函数) 38 | - [4. 使用有序字典来去重](#4-使用有序字典来去重) 39 | - [常见误区](#常见误区) 40 | - [1. 当心那些已经枯竭的迭代器](#1-当心那些已经枯竭的迭代器) 41 | - [2. 别在循环体内修改被迭代对象](#2-别在循环体内修改被迭代对象) 42 | - [总结](#总结) 43 | - [系列其他文章](#系列其他文章) 44 | - [注解](#注解) 45 | 46 | ### 当我们谈论容器时，我们在谈些什么？ 47 | 48 | 我在前面给了“容器”一个简单的定义：*专门用来装其他对象的就是容器*。但这个定义太宽泛了，无法对我们的日常编程产生什么指导价值。要真正掌握 Python 里的容器，需要分别从两个层面入手： 49 | 50 | - **底层实现**：内置容器类型使用了什么数据结构？某项操作如何工作？ 51 | - **高层抽象**：什么决定了某个对象是不是容器？哪些行为定义了容器？ 52 | 53 | 下面，让我们一起站在这两个不同的层面上，重新认识容器。 54 | 55 | ## 底层看容器 56 | 57 | Python 是一门高级编程语言，**它所提供的内置容器类型，都是经过高度封装和抽象后的结果**。和“链表”、“红黑树”、“哈希表”这些名字相比，所有 Python 内建类型的名字，都只描述了这个类型的功能特点，其他人完全没法只通过这些名字了解它们的哪怕一丁点内部细节。 58 | 59 | 这是 Python 编程语言的优势之一。相比 C 语言这类更接近计算机底层的编程语言，Python 重新设计并实现了对编程者更友好的内置容器类型，屏蔽掉了内存管理等额外工作，为我们提供了更好的开发体验。 60 | 61 | 但如果这是 Python 语言的优势的话，为什么我们还要费劲去了解容器类型的实现细节呢？答案是：**关注细节可以帮助我们编写出更快的代码。** 62 | 63 | ### 写更快的代码 64 | 65 | #### 1. 避免频繁扩充列表/创建新列表 66 | 67 | 所有的内建容器类型都不限制容量。如果你愿意，你可以把递增的数字不断塞进一个空列表，最终撑爆整台机器的内存。 68 | 69 | 在 Python 语言的实现细节里，列表的内存是按需分配的[[注1]](#annot1)，当某个列表当前拥有的内存不够时，便会触发内存扩容逻辑。而分配内存是一项昂贵的操作。虽然大部分情况下，它不会对你的程序性能产生什么严重的影响。但是当你处理的数据量特别大时，很容易因为内存分配拖累整个程序的性能。 70 | 71 | 还好，Python 早就意识到了这个问题，并提供了官方的问题解决指引，那就是：**“变懒”**。 72 | 73 | 如何解释“变懒”？`range()` 函数的进化是一个非常好的例子。 74 | 75 | 在 Python 2 中，如果你调用 `range(100000000)`，需要等待好几秒才能拿到结果，因为它需要返回一个巨大的列表，花费了非常多的时间在内存分配与计算上。但在 Python 3 中，同样的调用马上就能拿到结果。因为函数返回的不再是列表，而是一个类型为 `range` 的懒惰对象，只有在你迭代它、或是对它进行切片时，它才会返回真正的数字给你。 76 | 77 | **所以说，为了提高性能，内建函数 `range` “变懒”了。** 而为了避免过于频繁的内存分配，在日常编码中，我们的函数同样也需要变懒，这包括： 78 | 79 | - 更多的使用 `yield` 关键字，返回生成器对象 80 | - 尽量使用生成器表达式替代列表推导表达式 81 | - 生成器表达式：`(i for i in range(100))` 👍 82 | - 列表推导表达式：`[i for i in range(100)]` 83 | - 尽量使用模块提供的懒惰对象： 84 | - 使用 `re.finditer` 替代 `re.findall` 85 | - 直接使用可迭代的文件对象： `for line in fp`，而不是 `for line in fp.readlines()` 86 | 87 | #### 2. 在列表头部操作多的场景使用 deque 模块 88 | 89 | 列表是基于数组结构（Array）实现的，当你在列表的头部插入新成员（`list.insert(0, item)`）时，它后面的所有其他成员都需要被移动，操作的时间复杂度是 `O(n)`。这导致在列表的头部插入成员远比在尾部追加（`list.append(item)` 时间复杂度为 `O(1)`）要慢。 90 | 91 | 如果你的代码需要执行很多次这类操作，请考虑使用 [collections.deque](https://docs.python.org/3.7/library/collections.html#collections.deque) 类型来替代列表。因为 deque 是基于双端队列实现的，无论是在头部还是尾部追加元素，时间复杂度都是 `O(1)`。 92 | 93 | #### 3. 使用集合/字典来判断成员是否存在 94 | 95 | 当你需要判断成员是否存在于某个容器时，用集合比列表更合适。因为 `item in [...]` 操作的时间复杂度是 `O(n)`，而 `item in {...}` 的时间复杂度是 `O(1)`。这是因为字典与集合都是基于哈希表（Hash Table）数据结构实现的。 96 | 97 | ```python 98 | # 这个例子不是特别恰当，因为当目标集合特别小时，使用集合还是列表对效率的影响微乎其微 99 | # 但这不是重点 :) 100 | VALID_NAMES = ["piglei", "raymond", "bojack", "caroline"] 101 | 102 | # 转换为集合类型专门用于成员判断 103 | VALID_NAMES_SET = set(VALID_NAMES) 104 | 105 | 106 | def validate_name(name): 107 | if name not in VALID_NAMES_SET: 108 | # 此处使用了 Python 3.6 添加的 f-strings 特性 109 | raise ValueError(f"{name} is not a valid name!") 110 | ``` 111 | 112 | > Hint: 强烈建议阅读 [TimeComplexity - Python Wiki](https://wiki.python.org/moin/TimeComplexity)，了解更多关于常见容器类型的时间复杂度相关内容。 113 | > 114 | > 如果你对字典的实现细节感兴趣，也强烈建议观看 Raymond Hettinger 的演讲 [Modern Dictionaries(YouTube)](https://www.youtube.com/watch?v=p33CVV29OG8&t=1403s) 115 | 116 | ## 高层看容器 117 | 118 | Python 是一门“[鸭子类型](https://en.wikipedia.org/wiki/Duck_typing)”语言：*“当看到一只鸟走起来像鸭子、游泳起来像鸭子、叫起来也像鸭子，那么这只鸟就可以被称为鸭子。”* 所以，当我们说某个对象是什么类型时，在根本上其实指的是： **这个对象满足了该类型的特定接口规范，可以被当成这个类型来使用。** 而对于所有内置容器类型来说，同样如此。 119 | 120 | 打开位于 [collections](https://docs.python.org/3.7/library/collections.html) 模块下的 [abc](https://docs.python.org/3/library/collections.abc.html)*（“抽象类 Abstract Base Classes”的首字母缩写）* 子模块，可以找到所有与容器相关的接口（抽象类）[[注2]](#annot2)定义。让我们分别看看那些内建容器类型都满足了什么接口： 121 | 122 | - **列表（list）**：满足 `Iterable`、`Sequence`、`MutableSequence` 等接口 123 | - **元组（tuple）**：满足 `Iterable`、`Sequence` 124 | - **字典（dict）**：满足 `Iterable`、`Mapping`、`MutableMapping` [[注3]](#annot3) 125 | - **集合（set）**：满足 `Iterable`、`Set`、`MutableSet` [[注4]](#annot4) 126 | 127 | 每个内置容器类型，其实就是满足了多个接口定义的组合实体。比如所有的容器类型都满足 `“可被迭代的”（Iterable`） 这个接口，这意味着它们都是“可被迭代”的。但是反过来，不是所有“可被迭代”的对象都是容器。就像字符串虽然可以被迭代，但我们通常不会把它当做“容器”来看待。 128 | 129 | 了解这个事实后，我们将**在 Python 里重新认识**面向对象编程中最重要的原则之一：**面向接口而非具体实现来编程。** 130 | 131 | 让我们通过一个例子，看看如何理解 Python 里的“面向接口编程”。 132 | 133 | ### 写扩展性更好的代码 134 | 135 | 某日，我们接到一个需求：*有一个列表，里面装着很多用户评论，为了在页面正常展示，需要将所有超过一定长度的评论用省略号替代*。 136 | 137 | 这个需求很好做，很快我们就写出了第一个版本的代码： 138 | 139 | ```python 140 | # 注：为了加强示例代码的说明性，本文中的部分代码片段使用了Python 3.5 141 | # 版本添加的 Type Hinting 特性 142 | 143 | def add_ellipsis(comments: typing.List[str], max_length: int = 12): 144 | """如果评论列表里的内容超过 max_length，剩下的字符用省略号代替 145 | """ 146 | index = 0 147 | for comment in comments: 148 | comment = comment.strip() 149 | if len(comment) > max_length: 150 | comments[index] = comment[:max_length] + '...' 151 | index += 1 152 | return comments 153 | 154 | 155 | comments = [ 156 | "Implementation note", 157 | "Changed", 158 | "ABC for generator", 159 | ] 160 | print("\n".join(add_ellipsis(comments))) 161 | # OUTPUT: 162 | # Implementati... 163 | # Changed 164 | # ABC for gene... 165 | ``` 166 | 167 | 上面的代码里，`add_ellipsis` 函数接收一个列表作为参数，然后遍历它，替换掉需要修改的成员。这一切看上去很合理，因为我们接到的最原始需求就是：“有一个 **列表**，里面...”。**但如果有一天，我们拿到的评论不再是被继续装在列表里，而是在不可变的元组里呢？** 168 | 169 | 那样的话，现有的函数设计就会逼迫我们写出 `add_ellipsis(list(comments))` 这种即慢又难看的代码了。😨 170 | 171 | #### 面向容器接口编程 172 | 173 | 我们需要改进函数来避免这个问题。因为 `add_ellipsis` 函数强依赖了列表类型，所以当参数类型变为元组时，现在的函数就不再适用了*（原因：给 `comments[index]` 赋值的地方会抛出 `TypeError` 异常）。* 如何改善这部分的设计？秘诀就是：**让函数依赖“可迭代对象”这个抽象概念，而非实体列表类型。** 174 | 175 | 使用生成器特性，函数可以被改成这样： 176 | 177 | ```python 178 | def add_ellipsis_gen(comments: typing.Iterable[str], max_length: int = 12): 179 | """如果可迭代评论里的内容超过 max_length，剩下的字符用省略号代替 180 | """ 181 | for comment in comments: 182 | comment = comment.strip() 183 | if len(comment) > max_length: 184 | yield comment[:max_length] + '...' 185 | else: 186 | yield comment 187 | 188 | 189 | print("\n".join(add_ellipsis_gen(comments))) 190 | ``` 191 | 192 | 在新函数里，我们将依赖的参数类型从列表改成了可迭代的抽象类。这样做有很多好处，一个最明显的就是：无论评论是来自列表、元组或是某个文件，新函数都可以轻松满足： 193 | 194 | ```python 195 | # 处理放在元组里的评论 196 | comments = ("Implementation note", "Changed", "ABC for generator") 197 | print("\n".join(add_ellipsis_gen(comments))) 198 | 199 | # 处理放在文件里的评论 200 | with open("comments") as fp: 201 | for comment in add_ellipsis_gen(fp): 202 | print(comment) 203 | ``` 204 | 205 | 将依赖由某个具体的容器类型改为抽象接口后，函数的适用面变得更广了。除此之外，新函数在执行效率等方面也都更有优势。现在让我们再回到之前的问题。**从高层来看，什么定义了容器？** 206 | 207 | 答案是： **各个容器类型实现的接口协议定义了容器。** 不同的容器类型在我们的眼里，应该是 `是否可以迭代`、`是否可以修改`、`有没有长度` 等各种特性的组合。我们需要在编写相关代码时，**更多的关注容器的抽象属性，而非容器类型本身**，这样可以帮助我们写出更优雅、扩展性更好的代码。 208 | 209 | > Hint：在 [itertools](https://docs.python.org/3/library/itertools.html) 与 [more-itertools](https://pypi.org/project/more-itertools/) 模块里可以找到更多关于处理可迭代对象的宝藏。 210 | 211 | ## 常用技巧 212 | 213 | ### 1. 使用元组改善分支代码 214 | 215 | 有时，我们的代码里会出现超过三个分支的 `if/else` 。就像下面这样： 216 | 217 | ```python 218 | import time 219 | 220 | 221 | def from_now(ts): 222 | """接收一个过去的时间戳，返回距离当前时间的相对时间文字描述 223 | """ 224 | now = time.time() 225 | seconds_delta = int(now - ts) 226 | if seconds_delta < 1: 227 | return "less than 1 second ago" 228 | elif seconds_delta < 60: 229 | return "{} seconds ago".format(seconds_delta) 230 | elif seconds_delta < 3600: 231 | return "{} minutes ago".format(seconds_delta // 60) 232 | elif seconds_delta < 3600 * 24: 233 | return "{} hours ago".format(seconds_delta // 3600) 234 | else: 235 | return "{} days ago".format(seconds_delta // (3600 * 24)) 236 | 237 | 238 | now = time.time() 239 | print(from_now(now)) 240 | print(from_now(now - 24)) 241 | print(from_now(now - 600)) 242 | print(from_now(now - 7500)) 243 | print(from_now(now - 87500)) 244 | # OUTPUT: 245 | # less than 1 second ago 246 | # 24 seconds ago 247 | # 10 minutes ago 248 | # 2 hours ago 249 | # 1 days ago 250 | ``` 251 | 252 | 上面这个函数挑不出太多毛病，很多很多人都会写出类似的代码。但是，如果你仔细观察它，可以在分支代码部分找到一些明显的“**边界**”。 比如，当函数判断某个时间是否应该用“秒数”展示时，用到了 `60`。而判断是否应该用分钟时，用到了 `3600`。 253 | 254 | **从边界提炼规律是优化这段代码的关键。** 如果我们将所有的这些边界放在一个有序元组中，然后配合二分查找模块 [bisect](https://docs.python.org/3.7/library/bisect.html)。整个函数的控制流就能被大大简化： 255 | 256 | ```python 257 | import bisect 258 | 259 | 260 | # BREAKPOINTS 必须是已经排好序的，不然无法进行二分查找 261 | BREAKPOINTS = (1, 60, 3600, 3600 * 24) 262 | TMPLS = ( 263 | # unit, template 264 | (1, "less than 1 second ago"), 265 | (1, "{units} seconds ago"), 266 | (60, "{units} minutes ago"), 267 | (3600, "{units} hours ago"), 268 | (3600 * 24, "{units} days ago"), 269 | ) 270 | 271 | 272 | def from_now(ts): 273 | """接收一个过去的时间戳，返回距离当前时间的相对时间文字描述 274 | """ 275 | seconds_delta = int(time.time() - ts) 276 | unit, tmpl = TMPLS[bisect.bisect(BREAKPOINTS, seconds_delta)] 277 | return tmpl.format(units=seconds_delta // unit) 278 | ``` 279 | 280 | 除了用元组可以优化过多的 `if/else` 分支外，有些情况下字典也能被用来做同样的事情。关键在于从现有代码找到重复的逻辑与规律，并多多尝试。 281 | 282 | ### 2. 在更多地方使用动态解包 283 | 284 | 动态解包操作是指使用 `*` 或 `**` 运算符将可迭代对象“解开”的行为，在 Python 2 时代，这个操作只能被用在函数参数部分，并且对出现顺序和数量都有非常严格的要求，使用场景非常单一。 285 | 286 | ```python 287 | def calc(a, b, multiplier=1): 288 | return (a + b) * multiplier 289 | 290 | 291 | # Python2 中只支持在函数参数部分进行动态解包 292 | print calc(*[1, 2], **{"multiplier": 10}) 293 | # OUTPUT: 30 294 | ``` 295 | 296 | 不过，Python 3 尤其是 3.5 版本后，`*` 和 `**` 的使用场景被大大扩充了。举个例子，在 Python 2 中，如果我们需要合并两个字典，需要这么做： 297 | 298 | ```python 299 | def merge_dict(d1, d2): 300 | # 因为字典是可被修改的对象，为了避免修改原对象，此处需要复制一个 d1 的浅拷贝 301 | result = d1.copy() 302 | result.update(d2) 303 | return result 304 | 305 | user = merge_dict({"name": "piglei"}, {"movies": ["Fight Club"]}) 306 | ``` 307 | 308 | 但是在 Python 3.5 以后的版本，你可以直接用 `**` 运算符来快速完成字典的合并操作： 309 | 310 | ``` 311 | user = {**{"name": "piglei"}, **{"movies": ["Fight Club"]}} 312 | ``` 313 | 314 | 除此之外，你还可以在普通赋值语句中使用 `*` 运算符来动态地解包可迭代对象。如果你想详细了解相关内容，可以阅读下面推荐的 PEP。 315 | 316 | > Hint：推进动态解包场景扩充的两个 PEP： 317 | > 318 | > - [PEP 3132 -- Extended Iterable Unpacking | Python.org](https://www.python.org/dev/peps/pep-3132/) 319 | > - [PEP 448 -- Additional Unpacking Generalizations | Python.org](https://www.python.org/dev/peps/pep-0448/) 320 | 321 | ### 3. 使用 next() 函数 322 | 323 | `next()` 是一个非常实用的内建函数，它接收一个迭代器作为参数，然后返回该迭代器的下一个元素。使用它配合生成器表达式，可以高效的实现 *“从列表中查找第一个满足条件的成员”* 之类的需求。 324 | 325 | ```python 326 | numbers = [3, 7, 8, 2, 21] 327 | # 获取并 **立即返回** 列表里的第一个偶数 328 | print(next(i for i in numbers if i % 2 == 0)) 329 | # OUTPUT: 8 330 | ``` 331 | 332 | ### 4. 使用有序字典来去重 333 | 334 | 字典和集合的结构特点保证了它们的成员不会重复，所以它们经常被用来去重。但是，使用它们俩去重后的结果会丢失原有列表的顺序。这是由底层数据结构“哈希表（Hash Table）”的特点决定的。 335 | 336 | ```python 337 | >>> l = [10, 2, 3, 21, 10, 3] 338 | # 去重但是丢失了顺序 339 | >>> set(l) 340 | {3, 10, 2, 21} 341 | ``` 342 | 343 | 如果既需要去重又必须保留顺序怎么办？我们可以使用 `collections.OrderedDict` 模块: 344 | 345 | ```python 346 | >>> from collections import OrderedDict 347 | >>> list(OrderedDict.fromkeys(l).keys()) 348 | [10, 2, 3, 21] 349 | ``` 350 | 351 | > Hint: 在 Python 3.6 中，默认的字典类型修改了实现方式，已经变成有序的了。并且在 Python 3.7 中，该功能已经从 **语言的实现细节** 变成了为 **可依赖的正式语言特性**。 352 | > 353 | > 但是我觉得让整个 Python 社区习惯这一点还需要一些时间，毕竟目前“字典是无序的”还是被印在无数本 Python 书上。所以，我仍然建议在一切需要有序字典的地方使用 OrderedDict。 354 | 355 | ## 常见误区 356 | 357 | ### 1. 当心那些已经枯竭的迭代器 358 | 359 | 在文章前面，我们提到了使用“懒惰”生成器的种种好处。但是，所有事物都有它的两面性。生成器的最大的缺点之一就是：**它会枯竭**。当你完整遍历过它们后，之后的重复遍历就不能拿到任何新内容了。 360 | 361 | ```python 362 | numbers = [1, 2, 3] 363 | numbers = (i * 2 for i in numbers) 364 | 365 | # 第一次循环会输出 2, 4, 6 366 | for number in numbers: 367 | print(number) 368 | 369 | # 这次循环什么都不会输出，因为迭代器已经枯竭了 370 | for number in numbers: 371 | print(number) 372 | ``` 373 | 374 | 而且不光是生成器表达式，Python 3 里的 map、filter 内建函数也都有一样的特点。忽视这个特点很容易导致代码中出现一些难以察觉的 Bug。 375 | 376 | Instagram 就在项目从 Python 2 到 Python 3 的迁移过程中碰到了这个问题。它们在 PyCon 2017 上分享了对付这个问题的故事。访问文章 [Instagram 在 PyCon 2017 的演讲摘要](https://www.piglei.com/articles/instagram-pycon-2017/)，搜索“迭代器”可以查看详细内容。 377 | 378 | ### 2. 别在循环体内修改被迭代对象 379 | 380 | 这是一个很多 Python 初学者会犯的错误。比如，我们需要一个函数来删掉列表里的所有偶数： 381 | 382 | ```python 383 | def remove_even(numbers): 384 | """去掉列表里所有的偶数 385 | """ 386 | for i, number in enumerate(numbers): 387 | if number % 2 == 0: 388 | # 有问题的代码 389 | del numbers[i] 390 | 391 | 392 | numbers = [1, 2, 7, 4, 8, 11] 393 | remove_even(numbers) 394 | print(numbers) 395 | # OUTPUT: [1, 7, 8, 11] 396 | ``` 397 | 398 | 注意到结果里那个多出来的 “8” 了吗？当你在遍历一个列表的同时修改它，就会出现这样的事情。因为被迭代的对象 `numbers` 在循环过程中被修改了。**遍历的下标在不断增长，而列表本身的长度同时又在不断缩减。这样就会导致列表里的一些成员其实根本就没有被遍历到。** 399 | 400 | 所以对于这类操作，请使用一个新的空列表保存结果，或者利用 `yield` 返回一个生成器。而不是修改被迭代的列表或是字典对象本身。 401 | 402 | ## 总结 403 | 404 | 在这篇文章中，我们首先从“容器类型”的定义出发，在底层和高层两个层面探讨了容器类型。之后遵循系列文章传统，提供了一些编写容器相关代码时的技巧。 405 | 406 | 让我们最后再总结一下要点： 407 | 408 | - 了解容器类型的底层实现，可以帮助你写出性能更好的代码 409 | - 提炼需求里的抽象概念，面向接口而非实现编程 410 | - 多使用“懒惰”的对象，少生成“迫切”的列表 411 | - 使用元组和字典可以简化分支代码结构 412 | - 使用 `next()` 函数配合迭代器可以高效完成很多事情，但是也需要注意“枯竭”问题 413 | - collections、itertools 模块里有非常多有用的工具，快去看看吧！ 414 | 415 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 416 | 417 | [>>>下一篇【5.让函数返回结果的技巧】](5-function-returning-tips.md) 418 | 419 | [<<<上一篇【3.使用数字与字符串的技巧】](3-tips-on-numbers-and-strings.md) 420 | 421 | ## 系列其他文章 422 | 423 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 424 | - [Python 工匠：善用变量改善代码质量](https://www.piglei.com/articles/python-using-variables-well/) 425 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 426 | - [Python 工匠：使用数字与字符串的技巧](https://www.piglei.com/articles/tips-on-numbers-and-strings/) 427 | 428 | ## 注解 429 | 430 | 1. Python 这门语言除了 CPython 外，还有许许多多的其他版本实现。如无特别说明，本文以及 “Python 工匠” 系列里出现的所有 Python 都特指 Python 的 C 语言实现 CPython 431 | 2. Python 里没有类似其他编程语言里的“Interface 接口”类型，只有类似的“抽象类”概念。为了表达方便，后面的内容均统一使用“接口”来替代“抽象类”。 432 | 3. 有没有只实现了 Mapping 但又不是 MutableMapping 的类型？试试 [MappingProxyType({})](https://docs.python.org/3/library/types.html#types.MappingProxyType) 433 | 4. 有没有只实现了 Set 但又不是 MutableSet 的类型？试试 [frozenset()](https://docs.python.org/3/library/stdtypes.html#frozenset) 434 | -------------------------------------------------------------------------------- /zh_CN/5-function-returning-tips.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：让函数返回结果的技巧 2 | 3 | ## 序言 4 | 5 | > 这是 “Python 工匠”系列的第 5 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 毫无疑问，函数是 Python 语言里最重要的概念之一。在编程时，我们将真实世界里的大问题分解为小问题，然后通过一个个函数交出答案。函数既是重复代码的克星，也是对抗代码复杂度的最佳武器。 12 | 13 | 如同大部分故事都会有结局，绝大多数函数也都是以**返回结果**作为结束。函数返回结果的手法，决定了调用它时的体验。所以，了解如何优雅的让函数返回结果，是编写好函数的必备知识。 14 | 15 | ### Python 的函数返回方式 16 | 17 | Python 函数通过调用 `return` 语句来返回结果。使用 `return value` 可以返回单个值，用 `return value1, value2` 则能让函数同时返回多个值。 18 | 19 | 如果一个函数体内没有任何 `return` 语句，那么这个函数的返回值默认为 `None`。除了通过 `return` 语句返回内容，在函数内还可以使用抛出异常 *（raise Exception）* 的方式来“返回结果”。 20 | 21 | 接下来，我将列举一些与函数返回相关的常用编程建议。 22 | 23 | ### 内容目录 24 | 25 | - [Python 工匠：让函数返回结果的技巧](#python-工匠让函数返回结果的技巧) 26 | - [序言](#序言) 27 | - [Python 的函数返回方式](#python-的函数返回方式) 28 | - [内容目录](#内容目录) 29 | - [编程建议](#编程建议) 30 | - [1. 单个函数不要返回多种类型](#1-单个函数不要返回多种类型) 31 | - [2. 使用 partial 构造新函数](#2-使用-partial-构造新函数) 32 | - [3. 抛出异常，而不是返回结果与错误](#3-抛出异常而不是返回结果与错误) 33 | - [4. 谨慎使用 None 返回值](#4-谨慎使用-none-返回值) 34 | - [1. 作为操作类函数的默认返回值](#1-作为操作类函数的默认返回值) 35 | - [2. 作为某些“意料之中”的可能没有的值](#2-作为某些意料之中的可能没有的值) 36 | - [3. 作为调用失败时代表“错误结果”的值](#3-作为调用失败时代表错误结果的值) 37 | - [5. 合理使用“空对象模式”](#5-合理使用空对象模式) 38 | - [6. 使用生成器函数代替返回列表](#6-使用生成器函数代替返回列表) 39 | - [7. 限制递归的使用](#7-限制递归的使用) 40 | - [总结](#总结) 41 | - [附录](#附录) 42 | 43 | ## 编程建议 44 | 45 | ### 1. 单个函数不要返回多种类型 46 | 47 | Python 语言非常灵活，我们能用它轻松完成一些在其他语言里很难做到的事情。比如：*让一个函数同时返回不同类型的结果。* 从而实现一种看起来非常实用的“多功能函数”。 48 | 49 | 就像下面这样： 50 | 51 | ```python 52 | def get_users(user_id=None): 53 | if user_id is not None: 54 | return User.get(user_id) 55 | else: 56 | return User.filter(is_active=True) 57 | 58 | 59 | # 返回单个用户 60 | get_users(user_id=1) 61 | # 返回多个用户 62 | get_users() 63 | ``` 64 | 65 | 当我们需要获取单个用户时，就传递 `user_id` 参数，否则就不传参数拿到所有活跃用户列表。一切都由一个函数 `get_users` 来搞定。这样的设计似乎很合理。 66 | 67 | 然而在函数的世界里，以编写具备“多功能”的瑞士军刀型函数为荣不是一件好事。这是因为好的函数一定是 [“单一职责（Single responsibility）”](https://en.wikipedia.org/wiki/Single_responsibility_principle) 的。**单一职责意味着一个函数只做好一件事，目的明确。** 这样的函数也更不容易在未来因为需求变更而被修改。 68 | 69 | 而返回多种类型的函数一定是违反“单一职责”原则的，**好的函数应该总是提供稳定的返回值，把调用方的处理成本降到最低。** 像上面的例子，我们应该编写两个独立的函数 `get_user_by_id(user_id)`、`get_active_users()` 来替代。 70 | 71 | ### 2. 使用 partial 构造新函数 72 | 73 | 假设这么一个场景，在你的代码里有一个参数很多的函数 `A`，适用性很强。而另一个函数 `B` 则是完全通过调用 `A` 来完成工作，是一种类似快捷方式的存在。 74 | 75 | 比方在这个例子里， `double` 函数就是完全通过 `multiply` 来完成计算的： 76 | 77 | ```python 78 | def multiply(x, y): 79 | return x * y 80 | 81 | 82 | def double(value): 83 | # 返回另一个函数调用结果 84 | return multiply(2, value) 85 | ``` 86 | 87 | 对于上面这种场景，我们可以使用 `functools` 模块里的 [`partial()`](https://docs.python.org/3.6/library/functools.html#functools.partial) 函数来简化它。 88 | 89 | `partial(func, *args, **kwargs)` 基于传入的函数与可变（位置/关键字）参数来构造一个新函数。**所有对新函数的调用，都会在合并了当前调用参数与构造参数后，代理给原始函数处理。** 90 | 91 | 利用 `partial` 函数，上面的 `double` 函数定义可以被修改为单行表达式，更简洁也更直接。 92 | 93 | ```python 94 | import functools 95 | 96 | double = functools.partial(multiply, 2) 97 | ``` 98 | 99 | > 建议阅读：[partial 函数官方文档](https://docs.python.org/3.6/library/functools.html#functools.partial) 100 | 101 | ### 3. 抛出异常，而不是返回结果与错误 102 | 103 | 我在前面提过，Python 里的函数可以返回多个值。基于这个能力，我们可以编写一类特殊的函数：**同时返回结果与错误信息的函数。** 104 | 105 | ```python 106 | def create_item(name): 107 | if len(name) > MAX_LENGTH_OF_NAME: 108 | return None, 'name of item is too long' 109 | if len(CURRENT_ITEMS) > MAX_ITEMS_QUOTA: 110 | return None, 'items is full' 111 | return Item(name=name), '' 112 | 113 | 114 | def create_from_input(): 115 | name = input() 116 | item, err_msg = create_item(name) 117 | if err_msg: 118 | print(f'create item failed: {err_msg}') 119 | else: 120 | print(f'item<{name}> created') 121 | ``` 122 | 123 | 在示例中，`create_item` 函数的作用是创建新的 Item 对象。同时，为了在出错时给调用方提供错误详情，它利用了多返回值特性，把错误信息作为第二个结果返回。 124 | 125 | 乍看上去，这样的做法很自然。尤其是对那些有 `Go` 语言编程经验的人来说更是如此。但是在 Python 世界里，这并非解决此类问题的最佳办法。因为这种做法会增加调用方进行错误处理的成本，尤其是当很多函数都遵循这个规范而且存在多层调用时。 126 | 127 | Python 具备完善的*异常（Exception）*机制，并且在某种程度上鼓励我们使用异常（[官方文档关于 EAFP 的说明](https://docs.python.org/3/glossary.html#term-eafp)）。所以，**使用异常来进行错误流程处理才是更地道的做法。** 128 | 129 | 引入自定义异常后，上面的代码可以被改写成这样： 130 | 131 | ```python 132 | class CreateItemError(Exception): 133 | """创建 Item 失败时抛出的异常""" 134 | 135 | def create_item(name): 136 | """创建一个新的 Item 137 | 138 | :raises: 当无法创建时抛出 CreateItemError 139 | """ 140 | if len(name) > MAX_LENGTH_OF_NAME: 141 | raise CreateItemError('name of item is too long') 142 | if len(CURRENT_ITEMS) > MAX_ITEMS_QUOTA: 143 | raise CreateItemError('items is full') 144 | return Item(name=name) 145 | 146 | 147 | def create_for_input(): 148 | name = input() 149 | try: 150 | item = create_item(name) 151 | except CreateItemError as e: 152 | print(f'create item failed: {e}') 153 | else: 154 | print(f'item<{name}> created') 155 | 156 | ``` 157 | 158 | 使用“抛出异常”替代“返回 (结果, 错误信息)”后，整个错误流程处理乍看上去变化不大，但实际上有着非常多不同，一些细节： 159 | 160 | - 新版本函数拥有更稳定的返回值类型，它永远只会返回 `Item` 类型或是抛出异常 161 | - 虽然我在这里鼓励使用异常，但“异常”总是会无法避免的让人 **感到惊讶**，所以，最好在函数文档里说明可能抛出的异常类型 162 | - 异常不同于返回值，它在被捕获前会不断往调用栈上层汇报。所以 `create_item` 的一级调用方完全可以省略异常处理，交由上层处理。这个特点给了我们更多的灵活性，但同时也带来了更大的风险。 163 | 164 | > Hint：如何在编程语言里处理错误，是一个至今仍然存在争议的主题。比如像上面不推荐的多返回值方式，正是缺乏异常的 Go 语言中最核心的错误处理机制。另外，即使是异常机制本身，不同编程语言之间也存在着差别。 165 | > 166 | > 异常，或是不异常，都是由语言设计者进行多方取舍后的结果，更多时候不存在绝对性的优劣之分。**但是，单就 Python 语言而言，使用异常来表达错误无疑是更符合 Python 哲学，更应该受到推崇的。** 167 | 168 | ### 4. 谨慎使用 None 返回值 169 | 170 | `None` 值通常被用来表示 **“某个应该存在但是缺失的东西”**，它在 Python 里是独一无二的存在。很多编程语言里都有与 None 类似的设计，比如 JavaScript 里的 `null`、Go 里的 `nil` 等。因为 None 所拥有的独特 *虚无* 气质，它经常被作为函数返回值使用。 171 | 172 | 当我们使用 None 作为函数返回值时，通常是下面 3 种情况。 173 | 174 | #### 1. 作为操作类函数的默认返回值 175 | 176 | 当某个操作类函数不需要任何返回值时，通常就会返回 None。同时，None 也是不带任何 `return` 语句函数的默认返回值。 177 | 178 | 对于这种函数，使用 None 是没有任何问题的，标准库里的 `list.append()`、`os.chdir()` 均属此类。 179 | 180 | #### 2. 作为某些“意料之中”的可能没有的值 181 | 182 | 有一些函数，它们的目的通常是去尝试性的做某件事情。视情况不同，最终可能有结果，也可能没有结果。**而对调用方来说，“没有结果”完全是意料之中的事情**。对这类函数来说，使用 None 作为“没结果”时的返回值也是合理的。 183 | 184 | 在 Python 标准库里，正则表达式模块 `re` 下的 `re.search`、`re.match` 函数均属于此类，这两个函数在可以找到匹配结果时返回 `re.Match` 对象，找不到时则返回 `None`。 185 | 186 | #### 3. 作为调用失败时代表“错误结果”的值 187 | 188 | 有时，`None` 也会经常被我们用来作为函数调用失败时的默认返回值，比如下面这个函数： 189 | 190 | ```python 191 | def create_user_from_name(username): 192 | """通过用户名创建一个 User 实例""" 193 | if validate_username(username): 194 | return User.from_username(username) 195 | else: 196 | return None 197 | 198 | 199 | user = create_user_from_name(username) 200 | if user: 201 | user.do_something() 202 | ``` 203 | 204 | 当 username 不合法时，函数 `create_user_from_name` 将会返回 None。但在这个场景下，这样做其实并不好。 205 | 206 | 不过你也许会觉得这个函数完全合情合理，甚至你会觉得它和我们提到的上一个“没有结果”时的用法非常相似。那么如何区分这两种不同情形呢？关键在于：**函数签名（名称与参数）与 None 返回值之间是否存在一种“意料之中”的暗示。** 207 | 208 | 让我解释一下，每当你让函数返回 None 值时，请**仔细阅读函数名**，然后问自己一个问题：*假如我是该函数的使用者，从这个名字来看，“拿不到任何结果”是否是该函数名称含义里的一部分？* 209 | 210 | 分别用这两个函数来举例： 211 | 212 | - `re.search()`：从函数名来看，`search`，代表着从目标字符串里去**搜索**匹配结果，而搜索行为，一向是可能有也可能没有结果的，所以该函数适合返回 None 213 | - `create_user_from_name()`：从函数名来看，代表基于一个名字来构建用户，并不能读出一种`可能返回、可能不返回`的含义。所以不适合返回 None 214 | 215 | 对于那些不能从函数名里读出 None 值暗示的函数来说，有两种修改方式。第一种，如果你坚持使用 None 返回值，那么请修改函数的名称。比如可以将函数 `create_user_from_name()` 改名为 `create_user_or_none()`。 216 | 217 | 第二种方式则更常见的多：用抛出异常 *（raise Exception）* 来代替 None 返回值。因为，如果返回不了正常结果并非函数意义里的一部分，这就代表着函数出现了 *“意料以外的状况”*，而这正是 **Exceptions 异常** 所掌管的领域。 218 | 219 | 使用异常改写后的例子： 220 | 221 | ```python 222 | class UnableToCreateUser(Exception): 223 | """当无法创建用户时抛出""" 224 | 225 | 226 | def create_user_from_name(username): 227 | """通过用户名创建一个 User 实例 228 | 229 | :raises: 当无法创建用户时抛出 UnableToCreateUser 230 | """ 231 | if validate_username(username): 232 | return User.from_username(username) 233 | else: 234 | raise UnableToCreateUser(f'unable to create user from {username}') 235 | 236 | 237 | try: 238 | user = create_user_from_name(username) 239 | except UnableToCreateUser: 240 | # Error handling 241 | else: 242 | user.do_something() 243 | ``` 244 | 245 | 与 None 返回值相比，抛出异常除了拥有我们在上个场景提到的那些特点外，还有一个额外的优势：**可以在异常信息里提供出现意料之外结果的原因**，这是只返回一个 None 值做不到的。 246 | 247 | ### 5. 合理使用“空对象模式” 248 | 249 | 我在前面提到函数可以用 `None` 值或异常来返回错误结果，但这两种方式都有一个共同的缺点。那就是所有需要使用函数返回值的地方，都必须加上一个 `if` 或 `try/except` 防御语句，来判断结果是否正常。 250 | 251 | 让我们看一个可运行的完整示例： 252 | 253 | ```python 254 | import decimal 255 | 256 | 257 | class CreateAccountError(Exception): 258 | """Unable to create a account error""" 259 | 260 | 261 | class Account: 262 | """一个虚拟的银行账号""" 263 | 264 | def __init__(self, username, balance): 265 | self.username = username 266 | self.balance = balance 267 | 268 | @classmethod 269 | def from_string(cls, s): 270 | """从字符串初始化一个账号""" 271 | try: 272 | username, balance = s.split() 273 | balance = decimal.Decimal(float(balance)) 274 | except ValueError: 275 | raise CreateAccountError('input must follow pattern "{ACCOUNT_NAME} {BALANCE}"') 276 | 277 | if balance < 0: 278 | raise CreateAccountError('balance can not be negative') 279 | return cls(username=username, balance=balance) 280 | 281 | 282 | def caculate_total_balance(accounts_data): 283 | """计算所有账号的总余额 284 | """ 285 | result = 0 286 | for account_string in accounts_data: 287 | try: 288 | user = Account.from_string(account_string) 289 | except CreateAccountError: 290 | pass 291 | else: 292 | result += user.balance 293 | return result 294 | 295 | 296 | accounts_data = [ 297 | 'piglei 96.5', 298 | 'cotton 21', 299 | 'invalid_data', 300 | 'roland $invalid_balance', 301 | 'alfred -3', 302 | ] 303 | 304 | print(caculate_total_balance(accounts_data)) 305 | ``` 306 | 307 | 在这个例子里，每当我们调用 `Account.from_string` 时，都必须使用 `try/except` 来捕获可能发生的异常。如果项目里需要调用很多次该函数，这部分工作就变得非常繁琐了。针对这种情况，可以使用[“空对象模式（Null object pattern）”](https://en.wikipedia.org/wiki/Null_object_pattern)来改善这个控制流。 308 | 309 | Martin Fowler 在他的经典著作[《重构》](https://martinfowler.com/books/refactoring.html) 中用一个章节详细说明过这个模式。简单来说，**就是使用一个符合正常结果接口的“空类型”来替代空值返回/抛出异常，以此来降低调用方处理结果的成本。** 310 | 311 | 引入“空对象模式”后，上面的示例可以被修改成这样： 312 | 313 | ```python 314 | class Account: 315 | # def __init__ 已省略... ... 316 | 317 | @classmethod 318 | def from_string(cls, s): 319 | """从字符串初始化一个账号 320 | 321 | :returns: 如果输入合法，返回 Account object，否则返回 NullAccount 322 | """ 323 | try: 324 | username, balance = s.split() 325 | balance = decimal.Decimal(float(balance)) 326 | except ValueError: 327 | return NullAccount() 328 | 329 | if balance < 0: 330 | return NullAccount() 331 | return cls(username=username, balance=balance) 332 | 333 | 334 | class NullAccount: 335 | username = '' 336 | balance = 0 337 | 338 | @classmethod 339 | def from_string(cls, s): 340 | raise NotImplementedError 341 | ``` 342 | 343 | 在新版代码里，我定义了 `NullAccount` 这个新类型，用来作为 `from_string` 失败时的错误结果返回。这样修改后的最大变化体现在 `caculate_total_balance` 部分： 344 | 345 | ```python 346 | def caculate_total_balance(accounts_data): 347 | """计算所有账号的总余额 348 | """ 349 | return sum(Account.from_string(s).balance for s in accounts_data) 350 | ``` 351 | 352 | 调整之后，调用方不必再显式使用 try 语句来处理错误，而是可以假设 `Account.from_string` 函数总是会返回一个合法的 Account 对象，从而大大简化整个计算逻辑。 353 | 354 | > Hint：在 Python 世界里，“空对象模式”并不少见，比如大名鼎鼎的 Django 框架里的 [AnonymousUser](https://docs.djangoproject.com/en/2.1/ref/contrib/auth/#anonymoususer-object) 就是一个典型的 null object。 355 | 356 | ### 6. 使用生成器函数代替返回列表 357 | 358 | 在函数里返回列表特别常见，通常，我们会先初始化一个列表 `results = []`，然后在循环体内使用 `results.append(item)` 函数填充它，最后在函数的末尾返回。 359 | 360 | 对于这类模式，我们可以用生成器函数来简化它。粗暴点说，就是用 `yield item` 替代 `append` 语句。使用生成器的函数通常更简洁、也更具通用性。 361 | 362 | ```python 363 | def foo_func(items): 364 | for item in items: 365 | # ... 处理 item 后直接使用 yield 返回 366 | yield item 367 | ``` 368 | 369 | 我在 [系列第 4 篇文章“容器的门道”](https://www.piglei.com/articles/mastering-container-types/) 里详细分析过这个模式，更多细节可以访问文章，搜索 “写扩展性更好的代码” 查看。 370 | 371 | ### 7. 限制递归的使用 372 | 373 | 当函数返回自身调用时，也就是 `递归` 发生时。递归是一种在特定场景下非常有用的编程技巧，但坏消息是：Python 语言对递归支持的非常有限。 374 | 375 | 这份“有限的支持”体现在很多方面。首先，Python 语言不支持[“尾递归优化”](https://en.wikipedia.org/wiki/Tail_call)。另外 Python 对最大递归层级数也有着严格的限制。 376 | 377 | 所以我建议：**尽量少写递归**。如果你想用递归解决问题，先想想它是不是能方便的用循环来替代。如果答案是肯定的，那么就用循环来改写吧。如果迫不得已，一定需要使用递归时，请考虑下面几个点： 378 | 379 | - 函数输入数据规模是否稳定，是否一定不会超过 `sys.getrecursionlimit()` 规定的最大层数限制 380 | - 是否可以通过使用类似 [functools.lru_cache](https://docs.python.org/3/library/functools.html#functools.lru_cache) 的缓存工具函数来降低递归层数 381 | 382 | ## 总结 383 | 384 | 在这篇文章中，我虚拟了一些与 Python 函数返回有关的场景，并针对每个场景提供了我的优化建议。最后再总结一下要点： 385 | 386 | - 让函数拥有稳定的返回值，一个函数只做好一件事 387 | - 使用 `functools.partial` 定义快捷函数 388 | - 抛出异常也是返回结果的一种方式，使用它来替代返回错误信息 389 | - 函数是否适合返回 None，由函数签名的“含义”所决定 390 | - 使用“空对象模式”可以简化调用方的错误处理逻辑 391 | - 多使用生成器函数，尽量用循环替代递归 392 | 393 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 394 | 395 | [>>>下一篇【6.异常处理的三个好习惯】](6-three-rituals-of-exceptions-handling.md) 396 | 397 | [<<<上一篇【4.容器的门道】](4-mastering-container-types.md) 398 | 399 | ## 附录 400 | 401 | - 题图来源: Dominik Scythe on Unsplash 402 | - 更多系列文章地址： 403 | 404 | 系列其他文章： 405 | 406 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 407 | - [Python 工匠：善用变量改善代码质量](https://www.piglei.com/articles/python-using-variables-well/) 408 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 409 | - [Python 工匠：使用数字与字符串的技巧](https://www.piglei.com/articles/tips-on-numbers-and-strings/) 410 | -------------------------------------------------------------------------------- /zh_CN/6-three-rituals-of-exceptions-handling.md: -------------------------------------------------------------------------------- 1 | # Python 工匠： 异常处理的三个好习惯 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 6 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 如果你用 Python 编程，那么你就无法避开异常，因为异常在这门语言里无处不在。打个比方，当你在脚本执行时按 `ctrl+c` 退出，解释器就会产生一个 `KeyboardInterrupt` 异常。而 `KeyError`、`ValueError`、`TypeError` 等更是日常编程里随处可见的老朋友。 12 | 13 | 异常处理工作由“捕获”和“抛出”两部分组成。“捕获”指的是使用 `try ... except` 包裹特定语句，妥当的完成错误流程处理。而恰当的使用 `raise` 主动“抛出”异常，更是优雅代码里必不可少的组成部分。 14 | 15 | 在这篇文章里，我会分享与异常处理相关的 3 个好习惯。继续阅读前，我希望你已经了解了下面这些知识点： 16 | 17 | - 异常的基本语法与用法*（建议阅读官方文档 [“Errors and Exceptions”](https://docs.python.org/3.6/tutorial/errors.html)）* 18 | - 为什么要使用异常代替错误返回*（建议阅读[《让函数返回结果的技巧》](https://www.piglei.com/articles/function-returning-tips/)）* 19 | - 为什么在写 Python 时鼓励使用异常 *（建议阅读 [“Write Cleaner Python: Use Exceptions”](https://jeffknupp.com/blog/2013/02/06/write-cleaner-python-use-exceptions/)）* 20 | 21 | ## 三个好习惯 22 | 23 | ### 1. 只做最精确的异常捕获 24 | 25 | 假如你不够了解异常机制，就难免会对它有一种天然恐惧感。你可能会觉得：*异常是一种不好的东西，好的程序就应该捕获所有的异常，让一切都平平稳稳的运行。* 而抱着这种想法写出的代码，里面通常会出现大段含糊的异常捕获逻辑。 26 | 27 | 让我们用一段可执行脚本作为样例： 28 | 29 | ```python 30 | # -*- coding: utf-8 -*- 31 | import requests 32 | import re 33 | 34 | 35 | def save_website_title(url, filename): 36 | """获取某个地址的网页标题，然后将其写入到文件中 37 | 38 | :returns: 如果成功保存，返回 True，否则打印错误，返回 False 39 | """ 40 | try: 41 | resp = requests.get(url) 42 | obj = re.search(r'(.*)', resp.text) 43 | if not obj: 44 | print('save failed: title tag not found in page content') 45 | return False 46 | 47 | title = obj.grop(1) 48 | with open(filename, 'w') as fp: 49 | fp.write(title) 50 | return True 51 | except Exception: 52 | print(f'save failed: unable to save title of {url} to {filename}') 53 | return False 54 | 55 | 56 | def main(): 57 | save_website_title('https://www.qq.com', 'qq_title.txt') 58 | 59 | 60 | if __name__ == '__main__': 61 | main() 62 | ``` 63 | 64 | 脚本里的 `save_website_title` 函数做了好几件事情。它首先通过网络获取网页内容，然后利用正则匹配出标题，最后将标题写在本地文件里。而这里有两个步骤很容易出错：**网络请求** 与 **本地文件操作**。所以在代码里，我们用一个大大的 `try ... except` 语句块，将这几个步骤都包裹了起来。**安全第一** ⛑。 65 | 66 | 那么，这段看上去简洁易懂的代码，里面藏着什么问题呢？ 67 | 68 | 如果你旁边刚好有一台安装了 Python 的电脑，那么你可以试着跑一遍上面的脚本。你会发现，上面的代码是不能成功执行的。而且你还会发现，无论你如何修改网址和目标文件的值，程序仍然会报错 *“save failed: unable to...”*。为什么呢？ 69 | 70 | 问题就藏在这个硕大无比的 `try ... except` 语句块里。假如你把眼睛贴近屏幕，非常仔细的检查这段代码。你会发现在编写函数时，我犯了一个**小错误**，我把获取正则匹配串的方法错打成了 `obj.grop(1)`，少了一个 'u'（`obj.group(1)`）。 71 | 72 | 但正是因为那个过于庞大、含糊的异常捕获，这个由打错方法名导致的原本该被抛出的 `AttributeError` 却被吞噬了。从而给我们的 debug 过程增加了不必要的麻烦。 73 | 74 | 异常捕获的目的，不是去捕获尽可能多的异常。假如我们从一开始就坚持：**只做最精准的异常捕获**。那么这样的问题就根本不会发生，精准捕获包括： 75 | 76 | - 永远只捕获那些可能会抛出异常的语句块 77 | - 尽量只捕获精确的异常类型，而不是模糊的 `Exception` 78 | 79 | 依照这个原则，我们的样例应该被改成这样： 80 | 81 | ```python 82 | from requests.exceptions import RequestException 83 | 84 | 85 | def save_website_title(url, filename): 86 | try: 87 | resp = requests.get(url) 88 | except RequestException as e: 89 | print(f'save failed: unable to get page content: {e}') 90 | return False 91 | 92 | # 这段正则操作本身就是不应该抛出异常的，所以我们没必要使用 try 语句块 93 | # 假如 group 被误打成了 grop 也没关系，程序马上就会通过 AttributeError 来 94 | # 告诉我们。 95 | obj = re.search(r'(.*)', resp.text) 96 | if not obj: 97 | print('save failed: title tag not found in page content') 98 | return False 99 | title = obj.group(1) 100 | 101 | try: 102 | with open(filename, 'w') as fp: 103 | fp.write(title) 104 | except IOError as e: 105 | print(f'save failed: unable to write to file {filename}: {e}') 106 | return False 107 | else: 108 | return True 109 | ``` 110 | 111 | ### 2. 别让异常破坏抽象一致性 112 | 113 | 大约四五年前，当时的我正在开发某移动应用的后端 API 项目。如果你也有过开发后端 API 的经验，那么你一定知道，这样的系统都需要制定一套 **“API 错误码规范”**，来为客户端处理调用错误时提供方便。 114 | 115 | 一个错误码返回大概长这个样子： 116 | 117 | ```javascript 118 | // HTTP Status Code: 400 119 | // Content-Type: application/json 120 | { 121 | "code": "UNABLE_TO_UPVOTE_YOUR_OWN_REPLY", 122 | "detail": "你不能推荐自己的回复" 123 | } 124 | ``` 125 | 126 | 在制定好错误码规范后，接下来的任务就是如何实现它。当时的项目使用了 Django 框架，而 Django 的错误页面正是使用了异常机制实现的。打个比方，如果你想让一个请求返回 404 状态码，那么只要在该请求处理过程中执行 `raise Http404` 即可。 127 | 128 | 所以，我们很自然的从 Django 获得了灵感。首先，我们在项目内定义了错误码异常类：`APIErrorCode`。然后依据“错误码规范”，写了很多继承该类的错误码。当需要返回错误信息给用户时，只需要做一次 `raise` 就能搞定。 129 | 130 | ```python 131 | raise error_codes.UNABLE_TO_UPVOTE 132 | raise error_codes.USER_HAS_BEEN_BANNED 133 | ... ... 134 | ``` 135 | 136 | 毫无意外，所有人都很喜欢用这种方式来返回错误码。因为它用起来非常方便，无论调用栈多深，只要你想给用户返回错误码，调用 `raise error_codes.ANY_THING` 就好。 137 | 138 | 随着时间推移，项目也变得越来越庞大，抛出 `APIErrorCode` 的地方也越来越多。有一天，我正准备复用一个底层图片处理函数时，突然碰到了一个问题。 139 | 140 | 我看到了一段让我非常纠结的代码： 141 | 142 | ```python 143 | # 在某个处理图像的模块内部 144 | # /util/image/processor.py 145 | def process_image(...): 146 | try: 147 | image = Image.open(fp) 148 | except Exception: 149 | # 说明（非项目原注释）：该异常将会被 Django 的中间件捕获，往前端返回 150 | # "上传的图片格式有误" 信息 151 | raise error_codes.INVALID_IMAGE_UPLOADED 152 | ... ... 153 | ``` 154 | 155 | `process_image` 函数会尝试解析一个文件对象，如果该对象不能被作为图片正常打开，就抛出 `error_codes.INVALID_IMAGE_UPLOADED （APIErrorCode 子类）` 异常，从而给调用方返回错误代码 JSON。 156 | 157 | 让我给你从头理理这段代码。最初编写 `process_image` 时，我虽然把它放在了 `util.image` 模块里，但当时调这个函数的地方就只有 *“处理用户上传图片的 POST 请求”* 而已。为了偷懒，我让函数直接抛出 `APIErrorCode` 异常来完成了错误处理工作。 158 | 159 | 再来说当时的问题。那时我需要写一个在后台运行的批处理图片脚本，而它刚好可以复用 `process_image` 函数所实现的功能。但这时不对劲的事情出现了，如果我想复用该函数，那么： 160 | 161 | - 我必须去捕获一个名为 `INVALID_IMAGE_UPLOADED` 的异常 162 | - **哪怕我的图片根本就不是来自于用户上传** 163 | - 我必须引入 `APIErrorCode` 异常类作为依赖来捕获异常 164 | - **哪怕我的脚本和 Django API 根本没有任何关系** 165 | 166 | **这就是异常类抽象层级不一致导致的结果**。`APIErrorCode` 异常类的意义，在于表达一种能够直接被终端用户（人）识别并消费的“错误代码”。**它在整个项目里，属于最高层的抽象之一**。但是出于方便，我们却在底层模块里引入并抛出了它。这打破了 `image.processor` 模块的抽象一致性，影响了它的可复用性和可维护性。 167 | 168 | 这类情况属于“模块抛出了**高于**所属抽象层级的异常”。避免这类错误需要注意以下几点： 169 | 170 | - 让模块只抛出与当前抽象层级一致的异常 171 | - 比如 `image.processer` 模块应该抛出自己封装的 `ImageOpenError` 异常 172 | - 在必要的地方进行异常包装与转换 173 | - 比如，应该在贴近高层抽象（视图 View 函数）的地方，将图像处理模块的 `ImageOpenError` 低级异常包装转换为 `APIErrorCode` 高级异常 174 | 175 | 修改后的代码： 176 | 177 | ```python 178 | # /util/image/processor.py 179 | class ImageOpenError(Exception): 180 | pass 181 | 182 | 183 | def process_image(...): 184 | try: 185 | image = Image.open(fp) 186 | except Exception as e: 187 | raise ImageOpenError(exc=e) 188 | ... ... 189 | 190 | # /app/views.py 191 | def foo_view_function(request): 192 | try: 193 | process_image(fp) 194 | except ImageOpenError: 195 | raise error_codes.INVALID_IMAGE_UPLOADED 196 | ``` 197 | 198 | 除了应该避免抛出**高于**当前抽象级别的异常外，我们同样应该避免泄露**低于**当前抽象级别的异常。 199 | 200 | 如果你用过 `requests` 模块，你可能已经发现它请求页面出错时所抛出的异常，并不是它在底层所使用的 `urllib3` 模块的原始异常，而是通过 `requests.exceptions` 包装过一次的异常。 201 | 202 | ```python 203 | >>> try: 204 | ... requests.get('https://www.invalid-host-foo.com') 205 | ... except Exception as e: 206 | ... print(type(e)) 207 | ... 208 | 209 | ``` 210 | 211 | 这样做同样是为了保证异常类的抽象一致性。因为 urllib3 模块是 requests 模块依赖的底层实现细节，而这个细节有可能在未来版本发生变动。所以必须对它抛出的异常进行恰当的包装，避免未来的底层变更对 `requests` 用户端错误处理逻辑产生影响。 212 | 213 | ### 3. 异常处理不应该喧宾夺主 214 | 215 | 在前面我们提到异常捕获要精准、抽象级别要一致。但在现实世界中，如果你严格遵循这些流程，那么很有可能会碰上另外一个问题：**异常处理逻辑太多，以至于扰乱了代码核心逻辑**。具体表现就是，代码里充斥着大量的 `try`、`except`、`raise` 语句，让核心逻辑变得难以辨识。 216 | 217 | 让我们看一段例子： 218 | 219 | ```python 220 | def upload_avatar(request): 221 | """用户上传新头像""" 222 | try: 223 | avatar_file = request.FILES['avatar'] 224 | except KeyError: 225 | raise error_codes.AVATAR_FILE_NOT_PROVIDED 226 | 227 | try: 228 | resized_avatar_file = resize_avatar(avatar_file) 229 | except FileTooLargeError as e: 230 | raise error_codes.AVATAR_FILE_TOO_LARGE 231 | except ResizeAvatarError as e: 232 | raise error_codes.AVATAR_FILE_INVALID 233 | 234 | try: 235 | request.user.avatar = resized_avatar_file 236 | request.user.save() 237 | except Exception: 238 | raise error_codes.INTERNAL_SERVER_ERROR 239 | return HttpResponse({}) 240 | ``` 241 | 242 | 这是一个处理用户上传头像的视图函数。这个函数内做了三件事情，并且针对每件事都做了异常捕获。如果做某件事时发生了异常，就返回对用户友好的错误到前端。 243 | 244 | 这样的处理流程纵然合理，但是显然代码里的异常处理逻辑有点“喧宾夺主”了。一眼看过去全是代码缩进，很难提炼出代码的核心逻辑。 245 | 246 | 早在 2.5 版本时，Python 语言就已经提供了对付这类场景的工具：“上下文管理器（context manager）”。上下文管理器是一种配合 `with` 语句使用的特殊 Python 对象，通过它，可以让异常处理工作变得更方便。 247 | 248 | 那么，如何利用上下文管理器来改善我们的异常处理流程呢？让我们直接看代码吧。 249 | 250 | ```python 251 | class raise_api_error: 252 | """captures specified exception and raise ApiErrorCode instead 253 | 254 | :raises: AttributeError if code_name is not valid 255 | """ 256 | def __init__(self, captures, code_name): 257 | self.captures = captures 258 | self.code = getattr(error_codes, code_name) 259 | 260 | def __enter__(self): 261 | # 该方法将在进入上下文时调用 262 | return self 263 | 264 | def __exit__(self, exc_type, exc_val, exc_tb): 265 | # 该方法将在退出上下文时调用 266 | # exc_type, exc_val, exc_tb 分别表示该上下文内抛出的 267 | # 异常类型、异常值、错误栈 268 | if exc_type is None: 269 | return False 270 | 271 | if exc_type == self.captures: 272 | raise self.code from exc_val 273 | return False 274 | ``` 275 | 276 | 在上面的代码里，我们定义了一个名为 `raise_api_error` 的上下文管理器，它在进入上下文时什么也不做。但是在退出上下文时，会判断当前上下文中是否抛出了类型为 `self.captures` 的异常，如果有，就用 `APIErrorCode` 异常类替代它。 277 | 278 | 使用该上下文管理器后，整个函数可以变得更清晰简洁： 279 | 280 | ```python 281 | def upload_avatar(request): 282 | """用户上传新头像""" 283 | with raise_api_error(KeyError, 'AVATAR_FILE_NOT_PROVIDED'): 284 | avatar_file = request.FILES['avatar'] 285 | 286 | with raise_api_error(ResizeAvatarError, 'AVATAR_FILE_INVALID'),\ 287 | raise_api_error(FileTooLargeError, 'AVATAR_FILE_TOO_LARGE'): 288 | resized_avatar_file = resize_avatar(avatar_file) 289 | 290 | with raise_api_error(Exception, 'INTERNAL_SERVER_ERROR'): 291 | request.user.avatar = resized_avatar_file 292 | request.user.save() 293 | return HttpResponse({}) 294 | ``` 295 | 296 | > Hint：建议阅读 [PEP 343 -- The "with" Statement | Python.org](https://www.python.org/dev/peps/pep-0343/)，了解与上下文管理器有关的更多知识。 297 | > 298 | > 模块 [contextlib](https://docs.python.org/3/library/contextlib.html) 也提供了非常多与编写上下文管理器相关的工具函数与样例。 299 | 300 | ## 总结 301 | 302 | 在这篇文章中，我分享了与异常处理相关的三个建议。最后再总结一下要点： 303 | 304 | - 只捕获可能会抛出异常的语句，避免含糊的捕获逻辑 305 | - 保持模块异常类的抽象一致性，必要时对底层异常类进行包装 306 | - 使用“上下文管理器”可以简化重复的异常处理逻辑 307 | 308 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 309 | 310 | [>>>下一篇【7.编写地道循环的两个建议】](7-two-tips-on-loop-writing.md) 311 | 312 | [<<<上一篇【5.让函数返回结果的技巧】](5-function-returning-tips.md) 313 | 314 | ## 附录 315 | 316 | - 题图来源: Photo by Bernard Hermant on Unsplash 317 | - 更多系列文章地址： 318 | 319 | 系列其他文章： 320 | 321 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 322 | - [Python 工匠：善用变量改善代码质量](https://www.piglei.com/articles/python-using-variables-well/) 323 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 324 | - [Python 工匠：让程序返回结果的技巧](https://www.piglei.com/articles/function-returning-tips/) 325 | -------------------------------------------------------------------------------- /zh_CN/7-two-tips-on-loop-writing.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：编写地道循环的两个建议 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 7 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 循环是一种常用的程序控制结构。我们常说，机器相比人类的最大优点之一，就是机器可以不眠不休的重复做某件事情，但人却不行。而**“循环”**，则是实现让机器不断重复工作的关键概念。 12 | 13 | 在循环语法方面，Python 表现的即传统又不传统。它虽然抛弃了常见的 `for (init; condition; incrment)` 三段式结构，但还是选择了 `for` 和 `while` 这两个经典的关键字来表达循环。绝大多数情况下，我们的循环需求都可以用 `for in ` 来满足，`while ` 相比之下用的则更少些。 14 | 15 | 虽然循环的语法很简单，但是要写好它确并不容易。在这篇文章里，我们将探讨什么是“地道”的循环代码，以及如何编写它们。 16 | 17 | ## 什么是“地道”的循环？ 18 | 19 | “地道”这个词，通常被用来形容某人做某件事情时，非常符合当地传统，做的非常好。打个比方，你去参加一个朋友聚会，同桌的有一位广东人，对方一开口，句句都是标准京腔、完美儿化音。那你可以对她说：“您的北京话说的真**地道**”。 20 | 21 | 既然“地道”这个词形容的经常是口音、做菜的口味这类实实在在的东西，那“地道”的循环代码又是什么意思呢？让我拿一个经典的例子来解释一下。 22 | 23 | 如果你去问一位刚学习 Python 一个月的人：“*如何在遍历一个列表的同时获取当前下标？*”。他可能会交出这样的代码： 24 | 25 | ```python 26 | index = 0 27 | for name in names: 28 | print(index, name) 29 | index += 1 30 | ``` 31 | 32 | 上面的循环虽然没错，但它确一点都不“地道”。一个拥有三年 Python 开发经验的人会说，代码应该这么写： 33 | 34 | ```python 35 | for i, name in enumerate(names): 36 | print(i, name) 37 | ``` 38 | 39 | [`enumerate()`](https://docs.python.org/3/library/functions.html#enumerate) 是 Python 的一个内置函数，它接收一个“可迭代”对象作为参数，然后返回一个不断生成 `(当前下标, 当前元素)` 的新可迭代对象。这个场景使用它最适合不过。 40 | 41 | 所以，在上面的例子里，我们会认为第二段循环代码比第一段更“地道”。因为它用更直观的代码，更聪明的完成了工作。 42 | 43 | ### enumerate() 所代表的编程思路 44 | 45 | 不过，判断某段循环代码是否地道，并不仅仅是以知道或不知道某个内置方法作为标准。我们可以从上面的例子挖掘出更深层的东西。 46 | 47 | 如你所见，Python 的 `for` 循环只有 `for in ` 这一种结构，而结构里的前半部分 - *赋值给 item* - 没有太多花样可玩。所以后半部分的 **可迭代对象** 是我们唯一能够大做文章的东西。而以 `enumerate()` 函数为代表的 *“修饰函数”*，刚好提供了一种思路：**通过修饰可迭代对象来优化循环本身。** 48 | 49 | 这就引出了我的第一个建议。 50 | 51 | ## 建议1：使用函数修饰被迭代对象来优化循环 52 | 53 | 使用修饰函数处理可迭代对象，可以在各种方面影响循环代码。而要找到合适的例子来演示这个方法，并不用去太远，内置模块 [itertools](https://docs.python.org/3.6/library/itertools.html) 就是一个绝佳的例子。 54 | 55 | 简单来说，itertools 是一个包含很多面向可迭代对象的工具函数集。我在之前的系列文章[《容器的门道》](https://www.piglei.com/articles/mastering-container-types/)里提到过它。 56 | 57 | 如果要学习 itertools，那么 [Python 官方文档](https://docs.python.org/3.6/library/itertools.html) 是你的首选，里面有非常详细的模块相关资料。但在这篇文章里，侧重点将和官方文档稍有不同。我会通过一些常见的代码场景，来详细解释它是如何改善循环代码的。 58 | 59 | ### 1. 使用 product 扁平化多层嵌套循环 60 | 61 | 虽然我们都知道*“扁平的代码比嵌套的好”*。但有时针对某类需求，似乎一定得写多层嵌套循环才行。比如下面这段： 62 | 63 | ```python 64 | def find_twelve(num_list1, num_list2, num_list3): 65 | """从 3 个数字列表中，寻找是否存在和为 12 的 3 个数 66 | """ 67 | for num1 in num_list1: 68 | for num2 in num_list2: 69 | for num3 in num_list3: 70 | if num1 + num2 + num3 == 12: 71 | return num1, num2, num3 72 | ``` 73 | 74 | 对于这种需要嵌套遍历多个对象的多层循环代码，我们可以使用 [product()](https://docs.python.org/3.6/library/itertools.html#itertools.product) 函数来优化它。`product()` 可以接收多个可迭代对象，然后根据它们的笛卡尔积不断生成结果。 75 | 76 | ```python 77 | from itertools import product 78 | 79 | 80 | def find_twelve_v2(num_list1, num_list2, num_list3): 81 | for num1, num2, num3 in product(num_list1, num_list2, num_list3): 82 | if num1 + num2 + num3 == 12: 83 | return num1, num2, num3 84 | ``` 85 | 86 | 相比之前的代码，使用 `product()` 的函数只用了一层 for 循环就完成了任务，代码变得更精炼了。 87 | 88 | ### 2. 使用 islice 实现循环内隔行处理 89 | 90 | 有一份包含 Reddit 帖子标题的外部数据文件，里面的内容格式是这样的： 91 | 92 | ``` 93 | python-guide: Python best practices guidebook, written for humans. 94 | --- 95 | Python 2 Death Clock 96 | --- 97 | Run any Python Script with an Alexa Voice Command 98 | --- 99 | <... ...> 100 | ``` 101 | 102 | 可能是为了美观，在这份文件里的每两个标题之间，都有一个 `"---"` 分隔符。现在，我们需要获取文件里所有的标题列表，所以在遍历文件内容的过程中，必须跳过这些无意义的分隔符。 103 | 104 | 参考之前对 `enumerate()` 函数的了解，我们可以通过在循环内加一段基于当前循环序号的 `if` 判断来做到这一点： 105 | 106 | ```python 107 | def parse_titles(filename): 108 | """从隔行数据文件中读取 reddit 主题名称 109 | """ 110 | with open(filename, 'r') as fp: 111 | for i, line in enumerate(fp): 112 | # 跳过无意义的 '---' 分隔符 113 | if i % 2 == 0: 114 | yield line.strip() 115 | ``` 116 | 117 | 但对于这类在循环内进行隔行处理的需求来说，如果使用 itertools 里的 [islice()](https://docs.python.org/3.6/library/itertools.html#itertools.islice) 函数修饰被循环对象，可以让循环体代码变得更简单直接。 118 | 119 | `islice(seq, start, end, step)` 函数和数组切片操作*（ list[start:stop:step] ）*有着几乎一模一样的参数。如果需要在循环内部进行隔行处理的话，只要设置第三个递进步长参数 step 值为 2 即可*（默认为 1）*。 120 | 121 | ```python 122 | from itertools import islice 123 | 124 | def parse_titles_v2(filename): 125 | with open(filename, 'r') as fp: 126 | # 设置 step=2，跳过无意义的 '---' 分隔符 127 | for line in islice(fp, 0, None, 2): 128 | yield line.strip() 129 | ``` 130 | 131 | ### 3. 使用 takewhile 替代 break 语句 132 | 133 | 有时，我们需要在每次循环开始时，判断循环是否需要提前结束。比如下面这样： 134 | 135 | ```python 136 | for user in users: 137 | # 当第一个不合格的用户出现后，不再进行后面的处理 138 | if not is_qualified(user): 139 | break 140 | 141 | # 进行处理 ... ... 142 | ``` 143 | 144 | 对于这类需要提前中断的循环，我们可以使用 [takewhile()](https://docs.python.org/3.6/library/itertools.html#itertools.takewhile) 函数来简化它。`takewhile(predicate, iterable)` 会在迭代 `iterable` 的过程中不断使用当前对象作为参数调用 `predicate` 函数并测试返回结果，如果函数返回值为真，则生成当前对象，循环继续。否则立即中断当前循环。 145 | 146 | 使用 `takewhile` 的代码样例： 147 | 148 | ``` 149 | from itertools import takewhile 150 | 151 | for user in takewhile(is_qualified, users): 152 | # 进行处理 ... ... 153 | ``` 154 | 155 | itertools 里面还有一些其他有意思的工具函数，他们都可以用来和循环搭配使用，比如使用 chain 函数扁平化双层嵌套循环、使用 zip_longest 函数一次同时循环多个对象等等。 156 | 157 | 篇幅有限，我在这里不再一一介绍。如果有兴趣，可以自行去官方文档详细了解。 158 | 159 | ### 4. 使用生成器编写自己的修饰函数 160 | 161 | 除了 itertools 提供的那些函数外，我们还可以非常方便的使用生成器来定义自己的循环修饰函数。 162 | 163 | 让我们拿一个简单的函数举例： 164 | 165 | ```python 166 | def sum_even_only(numbers): 167 | """对 numbers 里面所有的偶数求和""" 168 | result = 0 169 | for num in numbers: 170 | if num % 2 == 0: 171 | result += num 172 | return result 173 | ``` 174 | 175 | 在上面的函数里，循环体内为了过滤掉所有奇数，引入了一条额外的 `if` 判断语句。如果要简化循环体内容，我们可以定义一个生成器函数来专门进行偶数过滤： 176 | 177 | ```python 178 | def even_only(numbers): 179 | for num in numbers: 180 | if num % 2 == 0: 181 | yield num 182 | 183 | 184 | def sum_even_only_v2(numbers): 185 | """对 numbers 里面所有的偶数求和""" 186 | result = 0 187 | for num in even_only(numbers): 188 | result += num 189 | return result 190 | ``` 191 | 192 | 将 `numbers` 变量使用 `even_only` 函数装饰后，`sum_even_only_v2` 函数内部便不用继续关注“偶数过滤”逻辑了，只需要简单完成求和即可。 193 | 194 | > Hint：当然，上面的这个函数其实并不实用。在现实世界里，这种简单需求最适合直接用生成器/列表表达式搞定：`sum(num for num in numbers if num % 2 == 0)` 195 | 196 | ## 建议2：按职责拆解循环体内复杂代码块 197 | 198 | 我一直觉得循环是一个比较神奇的东西，每当你写下一个新的循环代码块，就好像开辟了一片黑魔法阵，阵内的所有内容都会开始无休止的重复执行。 199 | 200 | 但我同时发现，这片黑魔法阵除了能带来好处，**它还会引诱你不断往阵内塞入越来越多的代码，包括过滤掉无效元素、预处理数据、打印日志等等。甚至一些原本不属于同一抽象的内容，也会被塞入到同一片黑魔法阵内。** 201 | 202 | 你可能会觉得这一切理所当然，我们就是迫切需要阵内的魔法效果。如果不把这一大堆逻辑塞满到循环体内，还能把它们放哪去呢？ 203 | 204 | 让我们来看看下面这个业务场景。在网站中，有一个每 30 天执行一次的周期脚本，它的任务是是查询过去 30 天内，在每周末特定时间段登录过的用户，然后为其发送奖励积分。 205 | 206 | 代码如下： 207 | 208 | ```python 209 | import time 210 | import datetime 211 | 212 | 213 | def award_active_users_in_last_30days(): 214 | """获取所有在过去 30 天周末晚上 8 点到 10 点登录过的用户，为其发送奖励积分 215 | """ 216 | days = 30 217 | for days_delta in range(days): 218 | dt = datetime.date.today() - datetime.timedelta(days=days_delta) 219 | # 5: Saturday, 6: Sunday 220 | if dt.weekday() not in (5, 6): 221 | continue 222 | 223 | time_start = datetime.datetime(dt.year, dt.month, dt.day, 20, 0) 224 | time_end = datetime.datetime(dt.year, dt.month, dt.day, 23, 0) 225 | 226 | # 转换为 unix 时间戳，之后的 ORM 查询需要 227 | ts_start = time.mktime(time_start.timetuple()) 228 | ts_end = time.mktime(time_end.timetuple()) 229 | 230 | # 查询用户并挨个发送 1000 奖励积分 231 | for record in LoginRecord.filter_by_range(ts_start, ts_end): 232 | # 这里可以添加复杂逻辑 233 | send_awarding_points(record.user_id, 1000) 234 | ``` 235 | 236 | 上面这个函数主要由两层循环构成。外层循环的职责，主要是获取过去 30 天内符合要求的时间，并将其转换为 UNIX 时间戳。之后由内层循环使用这两个时间戳进行积分发送。 237 | 238 | 如之前所说，外层循环所开辟的黑魔法阵内被塞的满满当当。但通过观察后，我们可以发现 **整个循环体其实是由两个完全无关的任务构成的：“挑选日期与准备时间戳” 以及 “发送奖励积分”**。 239 | 240 | ### 复杂循环体如何应对新需求 241 | 242 | 这样的代码有什么坏处呢？让我来告诉你。 243 | 244 | 某日，产品找过来说，有一些用户周末半夜不睡觉，还在刷我们的网站，我们得给他们发通知让他们以后早点睡觉。于是新需求出现了：**“给过去 30 天内在周末凌晨 3 点到 5 点登录过的用户发送一条通知”**。 245 | 246 | 新问题也随之而来。敏锐如你，肯定一眼可以发现，这个新需求在用户筛选部分的要求，和之前的需求非常非常相似。但是，如果你再打开之前那团循环体看看，你会发现代码根本没法复用，因为在循环内部，不同的逻辑完全被 **耦合** 在一起了。☹️ 247 | 248 | 在计算机的世界里，我们经常用**“耦合”**这个词来表示事物之间的关联关系。上面的例子中，*“挑选时间”*和*“发送积分”*这两件事情身处同一个循环体内，建立了非常强的耦合关系。 249 | 250 | 为了更好的进行代码复用，我们需要把函数里的*“挑选时间”*部分从循环体中解耦出来。而我们的老朋友，**“生成器函数”** 是进行这项工作的不二之选。 251 | 252 | ### 使用生成器函数解耦循环体 253 | 254 | 要把 *“挑选时间”* 部分从循环内解耦出来，我们需要定义新的生成器函数 `gen_weekend_ts_ranges()`，专门用来生成需要的 UNIX 时间戳： 255 | 256 | ```python 257 | def gen_weekend_ts_ranges(days_ago, hour_start, hour_end): 258 | """生成过去一段时间内周六日特定时间段范围，并以 UNIX 时间戳返回 259 | """ 260 | for days_delta in range(days_ago): 261 | dt = datetime.date.today() - datetime.timedelta(days=days_delta) 262 | # 5: Saturday, 6: Sunday 263 | if dt.weekday() not in (5, 6): 264 | continue 265 | 266 | time_start = datetime.datetime(dt.year, dt.month, dt.day, hour_start, 0) 267 | time_end = datetime.datetime(dt.year, dt.month, dt.day, hour_end, 0) 268 | 269 | # 转换为 unix 时间戳，之后的 ORM 查询需要 270 | ts_start = time.mktime(time_start.timetuple()) 271 | ts_end = time.mktime(time_end.timetuple()) 272 | yield ts_start, ts_end 273 | ``` 274 | 275 | 有了这个生成器函数后，旧需求“发送奖励积分”和新需求“发送通知”，就都可以在循环体内复用它来完成任务了： 276 | 277 | ```python 278 | def award_active_users_in_last_30days_v2(): 279 | """发送奖励积分""" 280 | for ts_start, ts_end in gen_weekend_ts_ranges(30, hour_start=20, hour_end=23): 281 | for record in LoginRecord.filter_by_range(ts_start, ts_end): 282 | send_awarding_points(record.user_id, 1000) 283 | 284 | 285 | def notify_nonsleep_users_in_last_30days(): 286 | """发送通知""" 287 | for ts_start, ts_end in gen_weekend_ts_ranges(30, hour_start=3, hour_end=6): 288 | for record in LoginRecord.filter_by_range(ts_start, ts_end): 289 | notify_user(record.user_id, 'You should sleep more') 290 | ``` 291 | 292 | ## 总结 293 | 294 | 在这篇文章里，我们首先简单解释了“地道”循环代码的定义。然后提出了第一个建议：使用修饰函数来改善循环。之后我虚拟了一个业务场景，描述了按职责拆解循环内代码的重要性。 295 | 296 | 一些要点总结： 297 | 298 | - 使用函数修饰被循环对象本身，可以改善循环体内的代码 299 | - itertools 里面有很多工具函数都可以用来改善循环 300 | - 使用生成器函数可以轻松定义自己的修饰函数 301 | - 循环内部，是一个极易发生“代码膨胀”的场地 302 | - 请使用生成器函数将循环内不同职责的代码块解耦出来，获得更好的灵活性 303 | 304 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 305 | 306 | [>>>下一篇【8.使用装饰器的技巧】](8-tips-on-decorators.md) 307 | 308 | [<<<上一篇【6.异常处理的三个好习惯】](6-three-rituals-of-exceptions-handling.md) 309 | 310 | ## 附录 311 | 312 | - 题图来源: Photo by Lai man nung on Unsplash 313 | - 更多系列文章地址： 314 | 315 | 系列其他文章： 316 | 317 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 318 | - [Python 工匠：容器的门道](https://www.piglei.com/articles/mastering-container-types/) 319 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 320 | - [Python 工匠：异常处理的三个好习惯](https://www.piglei.com/articles/three-rituals-of-exceptions-handling/) 321 | -------------------------------------------------------------------------------- /zh_CN/8-tips-on-decorators.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：使用装饰器的技巧 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 8 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 装饰器 *(Decorator)* 是 Python 里的一种特殊工具，它为我们提供了一种在函数外部修改函数的灵活能力。它有点像一顶画着独一无二 `@` 符号的神奇帽子，只要将它戴在函数头顶上，就能悄无声息的改变函数本身的行为。 12 | 13 | 你可能已经和装饰器打过不少交道了。在做面向对象编程时，我们就经常会用到 `@staticmethod` 和 `@classmethod` 两个内置装饰器。此外，如果你接触过 [click](https://click.palletsprojects.com/en/7.x/) 模块，就更不会对装饰器感到陌生。click 最为人所称道的参数定义接口 `@click.option(...)` 就是利用装饰器实现的。 14 | 15 | 除了用装饰器，我们也经常需要自己写一些装饰器。在这篇文章里，我将从 `最佳实践` 和 `常见错误` 两个方面，来与你分享有关装饰器的一些小知识。 16 | 17 | ## 最佳实践 18 | 19 | ### 1. 尝试用类来实现装饰器 20 | 21 | 绝大多数装饰器都是基于函数和 [闭包](https://en.wikipedia.org/wiki/Closure_(computer_programming)) 实现的，但这并非制造装饰器的唯一方式。事实上，Python 对某个对象是否能通过装饰器（`@decorator`）形式使用只有一个要求：**decorator 必须是一个“可被调用（callable）的对象**。 22 | 23 | ```python 24 | # 使用 callable 可以检测某个对象是否“可被调用” 25 | >>> def foo(): pass 26 | ... 27 | >>> type(foo) 28 | 29 | >>> callable(foo) 30 | True 31 | ``` 32 | 33 | 函数自然是“可被调用”的对象。但除了函数外，我们也可以让任何一个类实例变得“可被调用”（callable）。办法很简单，只要自定义类的 `__call__` 魔法方法即可。 34 | 35 | ```python 36 | class Foo: 37 | def __call__(self): 38 | print("Hello, __call___") 39 | 40 | foo = Foo() 41 | 42 | # OUTPUT: True 43 | print(callable(foo)) 44 | # 调用 foo 实例 45 | # OUTPUT: Hello, __call__ 46 | foo() 47 | ``` 48 | 49 | 基于这个特性，我们可以很方便的使用类来实现装饰器。 50 | 51 | 下面这段代码，会定义一个名为 `@delay(duration)` 的装饰器，使用它装饰过的函数在每次执行前，都会等待额外的 `duration` 秒。同时，我们也希望为用户提供无需等待马上执行的 `eager_call` 接口。 52 | 53 | ```python 54 | import time 55 | import functools 56 | 57 | 58 | class DelayFunc: 59 | def __init__(self, duration, func): 60 | self.duration = duration 61 | self.func = func 62 | 63 | def __call__(self, *args, **kwargs): 64 | print(f'Wait for {self.duration} seconds...') 65 | time.sleep(self.duration) 66 | return self.func(*args, **kwargs) 67 | 68 | def eager_call(self, *args, **kwargs): 69 | print('Call without delay') 70 | return self.func(*args, **kwargs) 71 | 72 | 73 | def delay(duration): 74 | """装饰器：推迟某个函数的执行。同时提供 .eager_call 方法立即执行 75 | """ 76 | # 此处为了避免定义额外函数，直接使用 functools.partial 帮助构造 77 | # DelayFunc 实例 78 | return functools.partial(DelayFunc, duration) 79 | ``` 80 | 81 | 如何使用装饰器的样例代码： 82 | 83 | ```python 84 | @delay(duration=2) 85 | def add(a, b): 86 | return a + b 87 | 88 | 89 | # 这次调用将会延迟 2 秒 90 | add(1, 2) 91 | # 这次调用将会立即执行 92 | add.eager_call(1, 2) 93 | ``` 94 | 95 | `@delay(duration)` 就是一个基于类来实现的装饰器。当然，如果你非常熟悉 Python 里的函数和闭包，上面的 `delay` 装饰器其实也完全可以只用函数来实现。所以，为什么我们要用类来做这件事呢？ 96 | 97 | 与纯函数相比，我觉得使用类实现的装饰器在**特定场景**下有几个优势： 98 | 99 | - 实现有状态的装饰器时，操作类属性比操作闭包内变量更符合直觉、不易出错 100 | - 实现为函数扩充接口的装饰器时，使用类包装函数，比直接为函数对象追加属性更易于维护 101 | - 更容易实现一个同时兼容装饰器与上下文管理器协议的对象（参考 [unitest.mock.patch](https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch)） 102 | 103 | ### 2. 使用 wrapt 模块编写更扁平的装饰器 104 | 105 | 在写装饰器的过程中，你有没有碰到过什么不爽的事情？不管你有没有，反正我有。我经常在写代码的时候，被下面两件事情搞得特别难受： 106 | 107 | 1. 实现带参数的装饰器时，层层嵌套的函数代码特别难写、难读 108 | 2. 因为函数和类方法的不同，为前者写的装饰器经常没法直接套用在后者上 109 | 110 | 比如，在下面的例子里，我实现了一个生成随机数并注入为函数参数的装饰器。 111 | 112 | ```python 113 | import random 114 | 115 | 116 | def provide_number(min_num, max_num): 117 | """装饰器：随机生成一个在 [min_num, max_num] 范围的整数，追加为函数的第一个位置参数 118 | """ 119 | def wrapper(func): 120 | def decorated(*args, **kwargs): 121 | num = random.randint(min_num, max_num) 122 | # 将 num 作为第一个参数追加后调用函数 123 | return func(num, *args, **kwargs) 124 | return decorated 125 | return wrapper 126 | 127 | 128 | 129 | @provide_number(1, 100) 130 | def print_random_number(num): 131 | print(num) 132 | 133 | # 输出 1-100 的随机整数 134 | # OUTPUT: 72 135 | print_random_number() 136 | ``` 137 | 138 | `@provide_number` 装饰器功能看上去很不错，但它有着我在前面提到的两个问题：**嵌套层级深、无法在类方法上使用。** 如果直接用它去装饰类方法，会出现下面的情况： 139 | 140 | ``` 141 | class Foo: 142 | @provide_number(1, 100) 143 | def print_random_number(self, num): 144 | print(num) 145 | 146 | # OUTPUT: <__main__.Foo object at 0x104047278> 147 | Foo().print_random_number() 148 | ``` 149 | 150 | `Foo` 类实例中的 `print_random_number` 方法将会输出类实例 `self` ，而不是我们期望的随机数 `num`。 151 | 152 | 之所以会出现这个结果，是因为类方法 *（method）* 和函数 *（function）* 二者在工作机制上有着细微不同。如果要修复这个问题，`provider_number` 装饰器在修改类方法的位置参数时，必须聪明的跳过藏在 `*args` 里面的类实例 `self` 变量，才能正确的将 `num` 作为第一个参数注入。 153 | 154 | 这时，就应该是 [wrapt](https://pypi.org/project/wrapt/) 模块闪亮登场的时候了。`wrapt` 模块是一个专门帮助你编写装饰器的工具库。利用它，我们可以非常方便的改造 `provide_number` 装饰器，完美解决*“嵌套层级深”*和*“无法通用”*两个问题， 155 | 156 | ```python 157 | import wrapt 158 | 159 | def provide_number(min_num, max_num): 160 | @wrapt.decorator 161 | def wrapper(wrapped, instance, args, kwargs): 162 | # 参数含义： 163 | # 164 | # - wrapped：被装饰的函数或类方法 165 | # - instance： 166 | # - 如果被装饰者为普通类方法，该值为类实例 167 | # - 如果被装饰者为 classmethod 类方法，该值为类 168 | # - 如果被装饰者为类/函数/静态方法，该值为 None 169 | # 170 | # - args：调用时的位置参数（注意没有 * 符号） 171 | # - kwargs：调用时的关键字参数（注意没有 ** 符号） 172 | # 173 | num = random.randint(min_num, max_num) 174 | # 无需关注 wrapped 是类方法或普通函数，直接在头部追加参数 175 | args = (num,) + args 176 | return wrapped(*args, **kwargs) 177 | return wrapper 178 | 179 | <... 应用装饰器部分代码省略 ...> 180 | 181 | # OUTPUT: 48 182 | Foo().print_random_number() 183 | ``` 184 | 185 | 使用 `wrapt` 模块编写的装饰器，相比原来拥有下面这些优势： 186 | 187 | - 嵌套层级少：使用 `@wrapt.decorator` 可以将两层嵌套减少为一层 188 | - 更简单：处理位置与关键字参数时，可以忽略类实例等特殊情况 189 | - 更灵活：针对 `instance` 值进行条件判断后，更容易让装饰器变得通用 190 | 191 | ## 常见错误 192 | 193 | ### 1. “装饰器”并不是“装饰器模式” 194 | 195 | [“设计模式”](https://en.wikipedia.org/wiki/Software_design_pattern)是一个在计算机世界里鼎鼎大名的词。假如你是一名 Java 程序员，而你一点设计模式都不懂，那么我打赌你找工作的面试过程一定会度过的相当艰难。 196 | 197 | 但写 Python 时，我们极少谈起“设计模式”。虽然 Python 也是一门支持面向对象的编程语言，但它的 [鸭子类型](https://en.wikipedia.org/wiki/Duck_typing) 设计以及出色的动态特性决定了，大部分设计模式对我们来说并不是必需品。所以，很多 Python 程序员在工作很长一段时间后，可能并没有真正应用过几种设计模式。 198 | 199 | 不过 [*“装饰器模式（Decorator Pattern）”*](https://en.wikipedia.org/wiki/Decorator_pattern) 是个例外。因为 Python 的“装饰器”和“装饰器模式”有着一模一样的名字，我不止一次听到有人把它们俩当成一回事，认为使用“装饰器”就是在实践“装饰器模式”。但事实上，**它们是两个完全不同的东西。** 200 | 201 | “装饰器模式”是一个完全基于“面向对象”衍生出的编程手法。它拥有几个关键组成：**一个统一的接口定义**、**若干个遵循该接口的类**、**类与类之间一层一层的包装**。最终由它们共同形成一种 *“装饰”* 的效果。 202 | 203 | 而 Python 里的“装饰器”和“面向对象”没有任何直接联系，**它完全可以只是发生在函数和函数间的把戏**。事实上，“装饰器”并没有提供某种无法替代的功能，它仅仅就是一颗[“语法糖”](https://en.wikipedia.org/wiki/Syntactic_sugar)而已。下面这段使用了装饰器的代码： 204 | 205 | ```python 206 | @log_time 207 | @cache_result 208 | def foo(): pass 209 | ``` 210 | 211 | 基本完全等同于下面这样： 212 | 213 | ```python 214 | def foo(): pass 215 | 216 | foo = log_time(cache_result(foo)) 217 | ``` 218 | 219 | **装饰器最大的功劳，在于让我们在某些特定场景时，可以写出更符合直觉、易于阅读的代码**。它只是一颗“糖”，并不是某个面向对象领域的复杂编程模式。 220 | 221 | > Hint: 在 Python 官网上有一个 [实现了装饰器模式的例子](https://wiki.python.org/moin/DecoratorPattern)，你可以读读这个例子来更好的了解它。 222 | 223 | ### 2. 记得用 functools.wraps() 装饰内层函数 224 | 225 | 下面是一个简单的装饰器，专门用来打印函数调用耗时： 226 | 227 | ```python 228 | import time 229 | 230 | 231 | def timer(wrapped): 232 | """装饰器：记录并打印函数耗时""" 233 | def decorated(*args, **kwargs): 234 | st = time.time() 235 | ret = wrapped(*args, **kwargs) 236 | print('execution take: {} seconds'.format(time.time() - st)) 237 | return ret 238 | return decorated 239 | 240 | 241 | @timer 242 | def random_sleep(): 243 | """随机睡眠一小会""" 244 | time.sleep(random.random()) 245 | ``` 246 | 247 | `timer` 装饰器虽然没有错误，但是使用它装饰函数后，函数的原始签名就会被破坏。也就是说你再也没办法正确拿到 `random_sleep` 函数的名称、文档内容了，所有签名都会变成内层函数 `decorated` 的值： 248 | 249 | ```python 250 | print(random_sleep.__name__) 251 | # 输出 'decorated' 252 | print(random_sleep.__doc__) 253 | # 输出 None 254 | ``` 255 | 256 | 这虽然只是个小问题，但在某些时候也可能会导致难以察觉的 bug。幸运的是，标准库 `functools` 为它提供了解决方案，你只需要在定义装饰器时，用另外一个装饰器再装饰一下内层 `decorated` 函数就行。 257 | 258 | 听上去有点绕，但其实就是新增一行代码而已： 259 | 260 | ```python 261 | def timer(wrapped): 262 | # 将 wrapper 函数的真实签名赋值到 decorated 上 263 | @functools.wraps(wrapped) 264 | def decorated(*args, **kwargs): 265 | # <...> 已省略 266 | return decorated 267 | ``` 268 | 269 | 这样处理后，`timer` 装饰器就不会影响它所装饰的函数了。 270 | 271 | ```python 272 | print(random_sleep.__name__) 273 | # 输出 'random_sleep' 274 | print(random_sleep.__doc__) 275 | # 输出 '随机睡眠一小会' 276 | ``` 277 | 278 | ### 3. 修改外层变量时记得使用 nonlocal 279 | 280 | 装饰器是对函数对象的一个高级应用。在编写装饰器的过程中，你会经常碰到内层函数需要修改外层函数变量的情况。就像下面这个装饰器一样： 281 | 282 | ```python 283 | import functools 284 | 285 | def counter(func): 286 | """装饰器：记录并打印调用次数""" 287 | count = 0 288 | @functools.wraps(func) 289 | def decorated(*args, **kwargs): 290 | # 次数累加 291 | count += 1 292 | print(f"Count: {count}") 293 | return func(*args, **kwargs) 294 | return decorated 295 | 296 | @counter 297 | def foo(): 298 | pass 299 | 300 | foo() 301 | ``` 302 | 303 | 为了统计函数调用次数，我们需要在 `decorated` 函数内部修改外层函数定义的 `count` 变量的值。但是，上面这段代码是有问题的，在执行它时解释器会报错: 304 | 305 | ```raw 306 | Traceback (most recent call last): 307 | File "counter.py", line 22, in 308 | foo() 309 | File "counter.py", line 11, in decorated 310 | count += 1 311 | UnboundLocalError: local variable 'count' referenced before assignment 312 | ``` 313 | 314 | 这个错误是由 `counter` 与 `decorated` 函数互相嵌套的作用域引起的。 315 | 316 | 当解释器执行到 `count += 1` 时，并不知道 `count` 是一个在外层作用域定义的变量，它把 `count` 当做一个局部变量，并在当前作用域内查找。最终却没有找到有关 `count` 变量的任何定义，然后抛出错误。 317 | 318 | 为了解决这个问题，我们需要通过 `nonlocal` 关键字告诉解释器：**“count 变量并不属于当前的 local 作用域，去外面找找吧”**，之前的错误就可以得到解决。 319 | 320 | ```python 321 | def decorated(*args, **kwargs): 322 | nonlocal count 323 | count += 1 324 | # <... 已省略 ...> 325 | ``` 326 | 327 | > Hint：如果要了解更多有关 nonlocal 关键字的历史，可以查阅 [PEP-3104](https://www.python.org/dev/peps/pep-3104/) 328 | 329 | ## 总结 330 | 331 | 在这篇文章里，我与你分享了有关装饰器的一些技巧与小知识。 332 | 333 | 一些要点总结： 334 | 335 | - 一切 callable 的对象都可以被用来实现装饰器 336 | - 混合使用函数与类，可以更好的实现装饰器 337 | - wrapt 模块很有用，用它可以帮助我们用更简单的代码写出复杂装饰器 338 | - “装饰器”只是语法糖，它不是“装饰器模式” 339 | - 装饰器会改变函数的原始签名，你需要 `functools.wraps` 340 | - 在内层函数修改外层函数的变量时，需要使用 `nonlocal` 关键字 341 | 342 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 343 | 344 | [>>>下一篇【9.一个关于模块的小故事】](9-a-story-on-cyclic-imports.md) 345 | 346 | [<<<上一篇【7.编写地道循环的两个建议】](7-two-tips-on-loop-writing.md) 347 | 348 | ## 附录 349 | 350 | - 题图来源: Photo by Clem Onojeghuo on Unsplash 351 | - 更多系列文章地址： 352 | 353 | 系列其他文章： 354 | 355 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 356 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 357 | - [Python 工匠：异常处理的三个好习惯](https://www.piglei.com/articles/three-rituals-of-exceptions-handling/) 358 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 359 | -------------------------------------------------------------------------------- /zh_CN/9-a-story-on-cyclic-imports.md: -------------------------------------------------------------------------------- 1 | # Python 工匠：一个关于模块的小故事 2 | 3 | ## 前言 4 | 5 | > 这是 “Python 工匠”系列的第 9 篇文章。[[查看系列所有文章]](https://github.com/piglei/one-python-craftsman) 6 | 7 |
8 | 9 |
10 | 11 | 模块（Module）是我们用来组织 Python 代码的基本单位。很多功能强大的复杂站点，都由成百上千个独立模块共同组成。 12 | 13 | 虽然模块有着不可替代的用处，但它有时也会给我们带来麻烦。比如，当你接手一个新项目后，刚展开项目目录。第一眼就看到了攀枝错节、难以理解的模块结构，那你肯定会想： *“这项目也太难搞了。”* 😂 14 | 15 | 在这篇文章里，我准备了一个和模块有关的小故事与你分享。 16 | 17 | ## 一个关于模块的小故事 18 | 19 | 小 R 是一个刚从学校毕业的计算机专业学生。半个月前，他面试进了一家互联网公司做 Python 开发，负责一个与用户活动积分有关的小项目。项目的主要功能是查询站点活跃用户，并为他们发送有关活动积分的通知： *“亲爱的用户，您好，您当前的活动积分为 x”*。 20 | 21 | 项目主要由 `notify_users.py` 脚本和 `fancy_site` 包组成，结构与各文件内容如下： 22 | 23 | ```text 24 | ├── fancy_site 25 | │   ├── __init__.py 26 | │   ├── marketing.py # 与市场活动有关的内容 27 | │   └── users.py # 与用户有关的内容 28 | └── notify_users.py # 脚本：发送积分通知 29 | ``` 30 | 31 | 文件 `notify_users.py`： 32 | 33 | ```python 34 | from fancy_site.users import list_active_users 35 | from fancy_site.marketing import query_user_points 36 | 37 | 38 | def main(): 39 | """获取所有的活跃用户，将积分情况发送给他们""" 40 | users = list_active_users() 41 | points = query_user_points(users) 42 | for user in users: 43 | user.add_notification(... ...) 44 | # <... 已省略 ...> 45 | ``` 46 | 47 | 文件 `fancy_site/users.py`： 48 | 49 | ```python 50 | from typing import List 51 | 52 | 53 | class User: 54 | # <... 已省略 ...> 55 | 56 | def add_notification(self, message: str): 57 | """为用户发送新通知""" 58 | pass 59 | 60 | 61 | def list_active_users() -> List[User]: 62 | """查询所有活跃用户""" 63 | pass 64 | ``` 65 | 66 | 文件：`fancy_site/marketing.py`： 67 | 68 | ```python 69 | from typing import List 70 | from .users import User 71 | 72 | 73 | def query_user_points(users: List[User]) -> List[int]: 74 | """批量查询用户活动积分""" 75 | 76 | 77 | def send_sms(phone_number: str, message: str): 78 | """为某手机号发送短信""" 79 | ``` 80 | 81 | 只要在项目目录下执行 `python notify_user.py`，就能实现给所有活跃用户发送通知。 82 | 83 | ### 需求变更 84 | 85 | 但有一天，产品经理找过来说，光给用户发站内信通知还不够，容易被用户忽略。除了站内信以外，我们还需要同时给用户推送一条短信通知。 86 | 87 | 琢磨了五秒钟后，小 R 跟产品经理说：*“这个需求可以做！”*。毕竟给手机号发送短信的 `send_sms()` 函数早就已经有人写好了。他只要先给 `add_notification` 方法添加一个可选参数 `enable_sms=False`，当传值为 `True` 时调用 `fancy_site.marketing` 模块里的 `send_sms` 函数就行。 88 | 89 | 一切听上去根本没有什么难度可言，十分钟后，小 R 就把 `user.py` 改成了下面这样： 90 | 91 | ```python 92 | # 导入 send_sms 模块的发送短信函数 93 | from .marketing import send_sms 94 | 95 | 96 | class User: 97 | # <...> 相关初始化代码已省略 98 | 99 | def add_notification(self, message: str, enable_sms=False): 100 | """为用户添加新通知""" 101 | if enable_sms: 102 | send_sms(user.mobile_number, ... ...) 103 | ``` 104 | 105 | 但是，当他修改完代码，再次执行 `notify_users.py` 脚本时，程序却报错了： 106 | 107 | ```raw 108 | Traceback (most recent call last): 109 | File "notify_users.py", line 2, in 110 | from fancy_site.users import list_active_users 111 | File .../fancy_site/users.py", line 3, in 112 | from .marketing import send_sms 113 | File ".../fancy_site/marketing.py", line 3, in 114 | from .users import User 115 | ImportError: cannot import name 'User' from 'fancy_site.users' (.../fancy_site/users.py) 116 | ``` 117 | 118 | 错误信息说，无法从 `fancy_site.users` 模块导入 `User` 对象。 119 | 120 | ### 解决环形依赖问题 121 | 122 | 小 R 仔细分析了一下错误，发现错误是因为 `users` 与 `marketing` 模块之间产生的环形依赖关系导致的。 123 | 124 | 当程序在 `notify_users.py` 文件导入 `fancy_site.users` 模块时，`users` 模块发现自己需要从 `marketing` 模块那里导入 `send_sms` 函数。而解释器在加载 `marketing` 模块的过程中，又反过来发现自己需要依赖 `users` 模块里面的 `User` 对象。 125 | 126 | 如此一来，整个模块依赖关系成为了环状，程序自然也就没法执行下去了。 127 | 128 | ![modules_before](https://www.piglei.com/static/uploaded/2019/05/modules_before.png) 129 | 130 | 不过，没有什么问题能够难倒一个可以正常访问 Google 的程序员。小 R 随便上网一搜，发现这样的问题很好解决。因为 Python 的 import 语句非常灵活，他只需要 **把在 users 模块内导入 send_sms 函数的语句挪到 `add_notification` 方法内，延缓 import 语句的执行就行啦。** 131 | 132 | ```python 133 | class User: 134 | # <...> 相关初始化代码已省略 135 | 136 | def add_notification(self, message: str, send_sms=False): 137 | """为用户添加新通知""" 138 | # 延缓 import 语句执行 139 | from .marketing import send_sms 140 | ``` 141 | 142 | 改动一行代码后，大功告成。小 R 简单测试后，发现一切正常，然后把代码推送了上去。不过小 R 还没来得及为自己点个赞，意料之外的事情发生了。 143 | 144 | 这段明明几乎完美的代码改动在 **Code Review** 的时候被审计人小 C 拒绝了。 145 | 146 | ### 小 C 的疑问 147 | 148 | 小 R 的同事小 C 是一名有着多年经验的 Python 程序员，他对小 R 说：“使用延迟 import，虽然可以马上解决包导入问题。但这个小问题背后隐藏了更多的信息。比如，**你有没有想过 send_sms 函数，是不是已经不适合放在 marketing 模块里了？”** 149 | 150 | 被小 C 这么一问，聪明的小 R 马上意识到了问题所在。要在 `users` 模块内发送短信，重点不在于用延迟导入解决环形依赖。而是要以此为契机，**发现当前模块间依赖关系的不合理，拆分/合并模块，创建新的分层与抽象，最终消除环形依赖。** 151 | 152 | 认识清楚问题后，他很快提交了新的代码修改。在新代码中，他创建了一个专门负责通知与消息类的工具模块 `msg_utils`，然后把 `send_sms` 函数挪到了里面。之后 `users` 模块内就可以毫无困难的从 `msg_utils` 模块中导入 `send_sms` 函数了。 153 | 154 | ```python 155 | from .msg_utils import send_sms 156 | ``` 157 | 158 | 新的模块依赖关系如下图所示： 159 | 160 | ![modules_afte](https://www.piglei.com/static/uploaded/2019/05/modules_after.png) 161 | 162 | 在新的模块结构中，整个项目被整齐的分为三层，模块间的依赖关系也变得只有**单向流动**。之前在函数内部 `import` 的“延迟导入”技巧，自然也就没有用武之地了。 163 | 164 | 小 R 修改后的代码获得了大家的认可，很快就被合并到了主分支。故事暂告一段落，那么这个故事告诉了我们什么道理呢？ 165 | 166 | ## 总结 167 | 168 | 模块间的循环依赖是一个在大型 Python 项目中很常见的问题，越复杂的项目越容易碰到这个问题。当我们在参与这些项目时，**如果对模块结构、分层、抽象缺少应有的重视。那么项目很容易就会慢慢变得复杂无比、难以维护。** 169 | 170 | 所以，合理的模块结构与分层非常重要。它可以大大降低开发人员的心智负担和项目维护成本。这也是我为什么要和你分享这个简单故事的原因。“在函数内延迟 import” 的做法当然没有错，但我们更应该关注的是：**整个项目内的模块依赖关系与分层是否合理。** 171 | 172 | 最后，让我们再尝试从 小 R 的故事里强行总结出几个道理吧： 173 | 174 | - 合理的模块结构与分层可以降低项目的开发维护成本 175 | - 合理的模块结构不是一成不变的，应该随着项目发展调整 176 | - 遇到问题时，不要选**“简单但有缺陷”**的那个方案，要选**“麻烦但正确”**的那个 177 | - 整个项目内的模块间依赖关系流向，应该是单向的，不能有环形依赖存在 178 | 179 | 看完文章的你，有没有什么想吐槽的？请留言或者在 [项目 Github Issues](https://github.com/piglei/one-python-craftsman) 告诉我吧。 180 | 181 | [>>>下一篇【10.做一个精通规则的玩家】](10-a-good-player-know-the-rules.md) 182 | 183 | [<<<上一篇【8.使用装饰器的技巧】](8-tips-on-decorators.md) 184 | 185 | ## 附录 186 | 187 | - 题图来源: Photo by Ricardo Gomez Angel on Unsplash 188 | - 更多系列文章地址： 189 | 190 | 系列其他文章： 191 | 192 | - [所有文章索引 [Github]](https://github.com/piglei/one-python-craftsman) 193 | - [Python 工匠：编写条件分支代码的技巧](https://www.piglei.com/articles/python-else-block-secrets/) 194 | - [Python 工匠：异常处理的三个好习惯](https://www.piglei.com/articles/three-rituals-of-exceptions-handling/) 195 | - [Python 工匠：编写地道循环的两个建议](https://www.piglei.com/articles/two-tips-on-loop-writing/) 196 | --------------------------------------------------------------------------------