目 录

第Ⅰ部分  基本概念

第1章  Python打包的含义与目的 3

1.1  软件打包的准确定义 4

1.1.1  实现自动化打包的标准化 5

1.1.2  发布软件包的内容 6

1.1.3  共享软件面临的挑战 8

1.2  打包的作用 8

1.2.1  通过打包实现内聚和封装 9

1.2.2  促进代码所有权的明确化 11

1.2.3  实现与使用解耦 12

1.2.4  通过组合小软件包填补角色空缺 14

1.3  小结 15

第2章  为打包开发做准备 17

2.1  管理Python虚拟环境 18

2.2  小结 23

第3章  最小Python软件包的剖析 25

3.1  Python构建工作流 26

3.2  创建软件包元数据 31

3.2.1  所需的核心元数据 31

3.2.2  可选的核心元数据 34

3.2.3  指定许可证 37

3.3  控制源代码和文件发现 39

3.4  在软件包中包含非Python文件 43

3.5  小结 45

第Ⅱ部分  创建可行的软件包

第4章  处理软件包依赖项、入口点和扩展 49

4.1  车辆漂移计算软件包 50

4.2  为Python创建C扩展 52

4.2.1  创建C扩展源代码 53

4.2.2  将Cython集成到Python软件包构建中 54

4.2.3  安装并配置C扩展程序 56

4.2.4  二进制wheel发布文件的构建目标 58

4.2.5  指定所需的Python版本 59

4.3  通过Python软件包提供命令行工具 60

4.4  指定Python软件包的依赖项 63

4.5  小结 67

第5章  构建和维护测试套件 69

5.1  集成测试设置 70

5.1.1  pytest测试框架 70

5.1.2  测量测试覆盖率 74

5.1.3  提高测试覆盖率 81

5.2  解决测试乏味问题 85

5.2.1  解决重复性、数据驱动型测试问题 85

5.2.2  解决软件包频繁安装的问题 87

5.2.3  配置测试环境 92

5.2.4  更快、更安全的测试技巧 95

5.3  小结 100

第6章  自动化代码质量工具 101

6.1  tox环境的真正威力 102

6.1.1  创建非默认tox环境  103

6.1.2  跨tox环境管理依赖项 104

6.2  分析类型安全 109

6.2.1  为类型检查创建一个tox环境 110

6.2.2  配置mypy 112

6.3  为代码格式化创建tox环境 114

6.4  为linting创建一个tox环境 118

6.5  小结 122

第Ⅲ部分  让软件包走进公众视野

第7章  通过持续集成实现工作自动化 125

7.1  持续集成工作流 126

7.2  使用GitHub Actions进行持续集成 127

7.2.1  高级GitHub Actions工作流 128

7.2.2  理解GitHub Actions术语 130

7.2.3  启动GitHub Actions工作流配置 131

7.3  将手动任务转换为GitHub Actions工作流  135

7.3.1  使用构建矩阵多次运行作业 138

7.3.2  构建适用于各种平台的Python软件包发布版 141

7.4  发布软件包 144

7.5  小结 153

第8章  编写和维护文档 155

8.1  关于文档的简单思考 156

8.2  使用Sphinx创建文档 158

8.2.1  在开发过程中自动刷新文档 163

8.2.2  自动提取代码文档 164

8.3  将文档发布到Read the Docs 173

8.4  文档编制最佳实践 184

8.4.1  记录文档内容 185

8.4.2  重链接轻重复 185

8.4.3  使用一致的、同频的语言 186

8.4.4  避免知识假设，创造语境 187

8.4.5  营造趣味视感和连贯的结构 188

8.4.6  为文档赋能 188

8.5  小结 189

第9章  保持软件包的持续更新与活力 191

9.1  选择软件包版本控制策略 192

9.1.1  直接依赖和间接依赖 192

9.1.2  Python依赖项规范和依赖项地狱 196

9.1.3  语义版本和日历版本 198

9.2  充分利用GitHub 200

9.2.1  GitHub依赖项图 201

9.2.2  利用Dependabot减少安全漏洞 202

9.3  阈值测试覆盖率 207

9.4  使用pyupgrade更新Python语法 209

9.5  使用预提交钩子减少返工 210

9.6  小结 213

第Ⅳ部分  路漫漫其修远兮

第10章  扩展和巩固实践 217

10.1  为未来软件包创建项目模板 218

10.1.1  创建cookiecutter配置 219

10.1.2  从现有项目中提取cookiecutter模板 224

10.2  使用命名空间软件包 228

10.3  在组织内扩展软件包 232

10.4  小结 235

第11章  建设社区 237

11.1  README需要提出价值主张 238

11.2  为不同用户类型提供支持文档 240

11.3  建立、提供和执行行为准则 242

11.4  传达项目的路线图、状态和更改 244

11.4.1  使用GitHub项目进行看板管理 244

11.4.2  使用GitHub标签跟踪单个任务的状态 245

11.4.3  在日志中跟踪高级别的更改 247

11.5  使用问题模板收集信息 249

11.6  吾将上下而求索 252

11.7  小结 252

附录A  安装asdf和python-launcher 253

A.1  安装asdf 254

A.2  安装python-launcher 257

附录B  安装pipx、build、tox、pre-commit和cookiecutter 261

B.1  安装pipx 261

B.2  安装build 262

B.3  安装tox 263

B.4  安装pre-commit 263

B.5  安装cookiecutter 264