這 12 個步驟能確保成功發布。
你寫了一個 Python 庫。自己覺著這太棒了!如果讓人們能夠輕鬆使用它不是很優雅麼?這有一個需要考慮的清單,以及在開源 Python 庫時要採取的具體步驟。
將程式碼放在 GitHub 上,這裡有很多開源專案,並且人們很容易提交拉取請求。
選擇一個開源許可證。一般來說 MIT 許可證是一個挺好的寬容許可證。如果你有特定要求,Creative Common 的選擇許可證可以指導你完成其它選擇。最重要的是,在選擇許可證時要記住三條規則:
將一個名為 README.rst
的檔案(使用 ReStructured Text 格式化)放在專案樹的頂層。
GitHub 將像 Markdown 一樣渲染 ReStructured Text,而 ReST 在 Python 的文件生態系統中的表現更好。
寫測試。這對你來說沒有用處。但對於想要編寫避免破壞相關功能的修補程式的人來說,它非常有用。
測試可幫助共同作業者進行共同作業。
通常情況下,如果可以用 pytest 執行就最好了。還有其他測試工具 —— 但很少有理由去使用它們。
使用 linter 制定樣式:PyLint、Flake8 或者帶上 --check
的 Black 。除非你使用 Black,否則請確保在一個檔案中指定設定選項,並簽入到版本控制系統中。
使用 docstrings 來記錄模組、函數、類和方法。
你可以使用幾種樣式。我更喜歡 Google 風格的 docstrings,但 ReST docstrings 也是一種選擇。
Sphinx 可以同時處理 Google 風格和 ReST 的 docstrings,以將零散的文件整合為 API 文件。
使用 Sphinx。(閱讀我們這篇文章。)教學很有用,但同樣重要的是要指明這是什麼、它有什麼好處、它有什麼壞處、以及任何特殊的考慮因素。
使用 tox 或 nox 自動執行測試和 linter,並構建文件。這些工具支援“依賴矩陣”。這些矩陣往往會快速增長,但你可以嘗試針對合理的樣本進行測試,例如 Python 版本、依賴項版本以及可能安裝的可選依賴項。
使用 setuptools 工具。寫一個 setup.py
和一個 setup.cfg
。如果同時支援 Python 2 和 3,請在 setup.cfg
中指定 universal 格式的 wheel。
tox 或 nox 應該做的一件事是構建 wheel 並對已安裝的 wheel 進行測試。
避免使用 C 擴充套件。如果出於效能或系結的原因一定需要它們,請將它們放在單獨的包中。正確打包 C 擴充套件可以寫一篇新的文章。這裡有很多問題!
使用公共持續工具。TravisCI 和 CircleCI 為開源專案提供免費套餐。將 GitHub 或其他倉庫設定為在合併拉請求之前需要先通過檢查,那麼你就不必擔心在程式碼評審中告知使用者修復測試或樣式。
使用 SemVer 或 CalVer。有許多工具可以幫助你管理版本:incremental、bumpversion 和 setuptools_scm 等都是 PyPI 上的包,都可以幫助你管理版本。
通過執行 tox 或 nox 並使用 twine 將檔案上傳到 PyPI 上發布。你可以通過在 DevPI 中“測試上傳”。