開源 Python 項目詳細指南
作者以 SciTime 項目（一個對算法訓練時間進行估計的包）的發布為例，詳細解釋了發布的每個步驟。
注意：本文假設你在 GitHub 上已經有一個想要打包和發布的項目。
第 0 步：獲取項目許可證
在做其他事之前，由于你的項目要開源，因此應該有一個許可證。獲取哪種許可證取決于項目包的使用方式。開源項目中一些常見許可證有 MIT 或 BSD。
要在項目中添加許可證，只需參照以下鏈接中的步驟，將 LICENSE 文件添加到項目庫中的根目錄即可：https://help.github.com/en/articles/adding-a-license-to-a-repository
第 1 步：讓你的代碼準備就緒
要將項目進行打包，你需要做一些預備工作：
- 讓你的項目結構正確就位。通常情況下，項目庫的根目錄包含一個以項目名稱命名的文件夾，項目的核心代碼應該位于此文件夾中。在這個文件夾之外是運行和構建包（測試、文檔等）所需的其他代碼。
- 核心文件夾應包括一個（或多個）模塊和一個 __init__.py 文件，該文件包含你希望讓終端用戶訪問的類/函數。此文件還可以包含包的版本，以便于終端用戶訪問。
- 理想情況下，應使用 logging 包來設置合理的日志記錄系統（而不是用 prints 輸出）。
- 理想情況下，應將你的核心代碼分配到一個或多個類中。
- from .estimate import Estimator
以__init__.py 為例，如果 Estimator 是終端用戶將會訪問的類（該類在 estimate.py 文件中定義）
- import logging
- class LogMixin(object):
- @property
- def logger(self):
- name = . .join([self.__module__, self.__class__.__name__])
- FORMAT = %(name)s:%(levelname)s:%(message)s
- logging.basicConfig(format=FORMAT, level=logging.DEBUG)
- logger = logging.getLogger(name)
- return logger
以日志系統為例：LogMixin 類可以在其他任何類中使用
第 2 步：使用打包工具創建 setup.py
在你的項目有了一套結構之后，你應該在項目庫的根目錄下添加 setup.py 文件。這有助于所有發布和版本維護過程的自動化。以下是 setup.py 的例子（源代碼：https://github.com/nathan-toubiana/scitime/blob/master/setup.py）。
- from setuptools import setup
- from os import path
- DIR = path.dirname(path.abspath(__file__))
- INSTALL_PACKAGES = open(path.join(DIR, requirements.txt )).read().splitlines()
- with open(path.join(DIR, README.md )) as f:
- README = f.read()
- setup(
- name= scitime ,
- packages=[ scitime ],
- description="Training time estimator for scikit-learn algorithms",
- long_description=README,
- long_description_content_type= text/markdown ,
- install_requires=INSTALL_PACKAGES,
- version= 0.0.2 ,
- url= http://github.com/nathan-toubiana/scitime ,
- author= Gabriel Lerner & Nathan Toubiana ,
- author_email= toubiana.nathan@gmail.com ,
- keywords=[ machine-learning , scikit-learn , training-time ],
- tests_require=[
- pytest ,
- pytest-cov ,
- pytest-sugar
- ],
- package_data={
- # include json and pkl files
- : [ *.json , models/*.pkl , models/*.json ],
- },
- include_package_data=True,
- python_requires= >=3
- )
setup.py 文件的示例
幾點注意事項：
- 如果你的包有依賴項，處理這些依賴項的簡單方法是在配置文件中通過 install_requires 參數來添加依賴項（如果列表很長，你可以像之前那樣指向一個 requirement.txt 文件）。
- 如果你希望在任何人安裝包時（從項目庫中）下載元數據，則應通過 package_data 參數來添加這些元數據。
- 有關 setup() 函數的更多信息，請參見：https://setuptools.readthedocs.io/en/latest/setuptools.html
注意：第 3 步到第 6 步是可選的（但強烈推薦），但是如果你現在馬上想發布你的包，可以直接跳到第 7 步。
第 3 步：設置本地測試和檢查測試覆蓋率
此時還沒有完成，你的項目還應該有單元測試。盡管有許多框架能幫助你做到，但一種簡單的方法是使用 pytest。所有測試都應該放在一個專用的文件夾中（例如名為 tests/或 testing 的文件夾）。在這個文件夾中放置你需要的所有測試文件，以便盡可能多地包含你的核心代碼。下面是一個如何編寫單元測試的示例。這里還有一個 SciTime 的測試文件。
一旦就位，你就可以通過在項目庫的根目錄運行 python -m pytest 在本地進行測試。
創建測試后，你還應該能估算覆蓋率。這一點很重要，因為你希望盡可能多地測試項目中的代碼量（以減少意外的 bug）。
很多框架也可以用于計算覆蓋率，對于 SciTime，我們使用了 codecov。你可以通過創建.codecov.yml 文件來決定允許的最小覆蓋率閾值，還可以通過創建.coveragerc 文件來決定要在覆蓋率分析中包含哪些文件。
- comment: false
- coverage:
- status:
- project:
- default:
- target: auto
- threshold: 10%
- patch:
- default:
- target: auto
- threshold: 10%
.codecov.yml 文件示例
- [run]
- branch = True
- source = scitime
- include = */scitime/*
- omit =
- */_data.py
- */setup.py
.coveragerc 文件示例
第 4 步：標準化語法和代碼風格
你還需要確保你的代碼遵循 PEP8 準則（即具有標準樣式并且語法正確）。同樣，有很多工具可以幫助你解決。這里我們用了 flake8。
第 5 步：創建一個合理的文檔
現在你的項目已經測試過了，結構也很好了，是時候添加一個合理的文檔。首先是要有一個好的 readme 文件，它會在你的 Github 項目庫的根目錄上顯示。完成后，加上以下幾點會更好：
- Pull 請求和 issue 模板：當創建新的 Pull 請求或 issue 時，這些文件可以根據你的需求給你的描述提供模板。
- Pull 請求創建步驟：https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository
- issue 創建步驟：https://help.github.com/en/articles/manually-creating-a-single-issue-template-for-your-repository
- Pull 請求模板：https://github.com/nathan-toubiana/scitime/blob/master/.github/PULL_REQUEST_TEMPLATE.md
- issue 模板：https://github.com/nathan-toubiana/scitime/tree/master/.github/ISSUE_TEMPLATE
- 貢獻指南（contribution guide）。應該在貢獻指南中簡單地說明你希望外部用戶如何協助你改進這個包。Scitime 的貢獻指南參見：https://github.com/nathan-toubiana/scitime/blob/master/.github/CONTRIBUTING.md。
- 準則，Scitime 的準則參見：https://github.com/nathan-toubiana/scitime/blob/master/.github/CODE_OF_CONDUCT.md
- 標簽和說明（見下面的截圖）
- readme 文件中的標簽（推薦一篇如何使用標簽的好文章：https://medium.freecodecamp.org/how-to-use-badges-to-stop-feeling-like-a-noob-d4e6600d37d2）。
由于 readme 文件應該相當綜合，因此通常會有一個更詳細的文檔。你可以用 sphinx 來完成，然后在 readthedocs 上管理文檔。與文檔相關的文件通常放在 docs/文件夾中。sphinx 和 readthedocs 相關教程：https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html。
包含標簽和說明的項目庫示例
第 6 步：創建持續集成
此時，你的項目離發布就緒不遠了。但是，在每次提交之后，必須更新文檔、運行測試以及檢查樣式和覆蓋率似乎有點難以應付。幸運的是，持續集成（CI）可以幫助你完成。你可以在每次提交之后使用 GitHub 的 webhook 來自動執行所有的這些操作。以下是我們在 SciTime 中使用的一套 CI 工具：
- 對于運行測試，我們使用了 travis ci 和 appveyor（用于 Windows 平臺上的測試）。對于 Travis CI，除了在項目庫上設置 webhook 之外，你還必須創建一個.travis.yml 文件，在該文件中，你不僅可以運行測試，還可以上傳更新的覆蓋率輸出以及檢查樣式和格式。通過創建 appveyor.yml 文件，appveyor 也可以這樣做。
- codecov 和 readthdocs 也有專用的 webhook
- language: python
- python:
- - "3.6"
- # command to install dependencies
- install:
- - pip install -r requirements.txt
- - pip install flake8
- - pip install pytest-cov
- - pip install codecov
- # command to run tests
- script:
- - python -m pytest --cov=scitime
- - ./build_tools/flake_diff.sh
- after_success:
- - codecov
.travis.yml 文件的示例：請注意，每次提交，測試都需要與檢查測試覆蓋率一起進行。但還有一個 flake8 檢查（邏輯則在 flake_diff.sh 文件中定義：https://github.com/nathan-toubiana/scitime/blob/master/build_tools/flake_diff.sh）
- environment:
- matrix:
- - PYTHON: "C:\Python36-x64"
- install:
- # We need wheel installed to build wheels
- - "%PYTHON%\python.exe -m pip install -r requirements.txt"
- - "%PYTHON%\python.exe -m pip install pytest==3.2.1"
- build: off
- test_script:
- - "%PYTHON%\python.exe -m pytest"
appveyor.yml 文件示例：這里我們只運行測試。
這將使更新項目庫的整個過程更加容易。
集成 webhook 的提交歷史記錄示例
第 7 步：創建你的第一個 release 和 publication
此時，你即將發布的包應與以下類似：
- your_package/
- __init__.py
- your_module.py
- docs/
- tests/
- setup.py
- travis.yml
- appveyor.yml
- .coveragerc
- .codecov.yml
- README.md
- LICENSE
- .github/
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- PULL_REQUEST_TEMPLATE.md
- ISSUE_TEMPLATE/
現在可以發布了！首先要做的是在 GitHub 上創建你的第一個 release——這是為了在給定的時間點跟蹤項目的狀態，每次版本更改時都需要創建新的 release。創建步驟：https://help.github.com/en/articles/creating-releases。
完成后，唯一要做的就是發布包。發布 python 包最常見的平臺是 PyPI 和 Conda。以下我們將描述如何用兩者發布：
- 對于 PyPI，首先需要創建一個帳戶，然后用 twine 執行一些步驟：https://realpython.com/pypi-publish-python-package/。這應該相當簡單，而且 Pypi 還提供了一個可以在實際部署之前使用的測試環境。PyPI 總體上包括創建源代碼（python setup.py sdist）并使用 twine（twine upload dist/*）來上傳。完成后，應該有一個與你的包對應的 PyPI 頁面，并且任何人都應該能夠通過運行 pip 命令來安裝你的包。
- 對于 Conda，我們推薦通過 conda forge 來發布你的包，conda forge 是一個社區，幫助你通過 conda 渠道發布和維護包。你可以按照以下步驟將包添加到社區：https://conda-forge.org/#add_recipe，然后你會被添加到 conda forge Github 組織中，并能夠非常輕松地維護你的包，然后任何人都可以通過運行 conda 命令來安裝你的包。
完成！
現在，你的包應該已經發出去，并且任何人都可以使用了！雖然大部分工作都完成了，但是你仍然需要維護你的項目，你需要進行一些更新：這大體上意味著每次進行重大更改時都要更改版本，創建新的 release，并再次執行第 7 步。
