Python 打包與發布 Publishing Python Packages: Test, Share, and Automate Your Projects

Dane Hilard是一位專註於使用Python開發Web應用的資深技術專家。Dane Hillard現任ITHAKA（一家致力於高等教育領域的非營利組織）的技術架構師。他經驗豐富，曾為支持數百萬用戶的JSTOR研究平臺構建應用架構。目前，他還對安全、松耦合系統和形式化方法感興趣。

目 錄

 

第Ⅰ部分  基本概念

第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