[[434539]]

 作者以 SciTime 項(xiàng)目（一個(gè)對(duì)算法訓(xùn)練時(shí)間進(jìn)行估計(jì)的包）的發(fā)布為例，詳細(xì)解釋了發(fā)布的每個(gè)步驟。

注意：本文假設(shè)你在 GitHub 上已經(jīng)有一個(gè)想要打包和發(fā)布的項(xiàng)目。

第 0 步：獲取項(xiàng)目許可證

在做其他事之前，由于你的項(xiàng)目要開(kāi)源，因此應(yīng)該有一個(gè)許可證。獲取哪種許可證取決于項(xiàng)目包的使用方式。開(kāi)源項(xiàng)目中一些常見(jiàn)許可證有 MIT 或 BSD。

要在項(xiàng)目中添加許可證，只需參照以下鏈接中的步驟，將 LICENSE 文件添加到項(xiàng)目庫(kù)中的根目錄即可：https://help.github.com/en/articles/adding-a-license-to-a-repository

第 1 步：讓你的代碼準(zhǔn)備就緒

要將項(xiàng)目進(jìn)行打包，你需要做一些預(yù)備工作：

• 讓你的項(xiàng)目結(jié)構(gòu)正確就位。通常情況下，項(xiàng)目庫(kù)的根目錄包含一個(gè)以項(xiàng)目名稱命名的文件夾，項(xiàng)目的核心代碼應(yīng)該位于此文件夾中。在這個(gè)文件夾之外是運(yùn)行和構(gòu)建包（測(cè)試、文檔等）所需的其他代碼。
•  核心文件夾應(yīng)包括一個(gè)（或多個(gè)）模塊和一個(gè) __init__.py 文件，該文件包含你希望讓終端用戶訪問(wèn)的類/函數(shù)。此文件還可以包含包的版本，以便于終端用戶訪問(wèn)。
•  理想情況下，應(yīng)使用 logging 包來(lái)設(shè)置合理的日志記錄系統(tǒng)（而不是用 prints 輸出）。
•  理想情況下，應(yīng)將你的核心代碼分配到一個(gè)或多個(gè)類中。 

from .estimate import Estimator 

以__init__.py 為例，如果 Estimator 是終端用戶將會(huì)訪問(wèn)的類（該類在 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 

以日志系統(tǒng)為例：LogMixin 類可以在其他任何類中使用

第 2 步：使用打包工具創(chuàng)建 setup.py

在你的項(xiàng)目有了一套結(jié)構(gòu)之后，你應(yīng)該在項(xiàng)目庫(kù)的根目錄下添加 setup.py 文件。這有助于所有發(fā)布和版本維護(hù)過(guò)程的自動(dòng)化。以下是 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 文件的示例

幾點(diǎn)注意事項(xiàng)：

•  如果你的包有依賴項(xiàng)，處理這些依賴項(xiàng)的簡(jiǎn)單方法是在配置文件中通過(guò) install_requires 參數(shù)來(lái)添加依賴項(xiàng)（如果列表很長(zhǎng)，你可以像之前那樣指向一個(gè) requirement.txt 文件）。
•  如果你希望在任何人安裝包時(shí)（從項(xiàng)目庫(kù)中）下載元數(shù)據(jù)，則應(yīng)通過(guò) package_data 參數(shù)來(lái)添加這些元數(shù)據(jù)。
•  有關(guān) setup() 函數(shù)的更多信息，請(qǐng)參見(jiàn)：https://setuptools.readthedocs.io/en/latest/setuptools.html

注意：第 3 步到第 6 步是可選的（但強(qiáng)烈推薦），但是如果你現(xiàn)在馬上想發(fā)布你的包，可以直接跳到第 7 步。

第 3 步：設(shè)置本地測(cè)試和檢查測(cè)試覆蓋率

此時(shí)還沒(méi)有完成，你的項(xiàng)目還應(yīng)該有單元測(cè)試。盡管有許多框架能幫助你做到，但一種簡(jiǎn)單的方法是使用 pytest。所有測(cè)試都應(yīng)該放在一個(gè)專用的文件夾中（例如名為 tests/或 testing 的文件夾）。在這個(gè)文件夾中放置你需要的所有測(cè)試文件，以便盡可能多地包含你的核心代碼。下面是一個(gè)如何編寫(xiě)單元測(cè)試的示例。這里還有一個(gè) SciTime 的測(cè)試文件。

一旦就位，你就可以通過(guò)在項(xiàng)目庫(kù)的根目錄運(yùn)行 python -m pytest 在本地進(jìn)行測(cè)試。

創(chuàng)建測(cè)試后，你還應(yīng)該能估算覆蓋率。這一點(diǎn)很重要，因?yàn)槟阆ＭM可能多地測(cè)試項(xiàng)目中的代碼量（以減少意外的 bug）。

很多框架也可以用于計(jì)算覆蓋率，對(duì)于 SciTime，我們使用了 codecov。你可以通過(guò)創(chuàng)建.codecov.yml 文件來(lái)決定允許的最小覆蓋率閾值，還可以通過(guò)創(chuàng)建.coveragerc 文件來(lái)決定要在覆蓋率分析中包含哪些文件。 

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 步：標(biāo)準(zhǔn)化語(yǔ)法和代碼風(fēng)格

你還需要確保你的代碼遵循 PEP8 準(zhǔn)則（即具有標(biāo)準(zhǔn)樣式并且語(yǔ)法正確）。同樣，有很多工具可以幫助你解決。這里我們用了 flake8。

第 5 步：創(chuàng)建一個(gè)合理的文檔

現(xiàn)在你的項(xiàng)目已經(jīng)測(cè)試過(guò)了，結(jié)構(gòu)也很好了，是時(shí)候添加一個(gè)合理的文檔。首先是要有一個(gè)好的 readme 文件，它會(huì)在你的 Github 項(xiàng)目庫(kù)的根目錄上顯示。完成后，加上以下幾點(diǎn)會(huì)更好：

•  Pull 請(qǐng)求和 issue 模板：當(dāng)創(chuàng)建新的 Pull 請(qǐng)求或 issue 時(shí)，這些文件可以根據(jù)你的需求給你的描述提供模板。
•  Pull 請(qǐng)求創(chuàng)建步驟：https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository
•  issue 創(chuàng)建步驟：https://help.github.com/en/articles/manually-creating-a-single-issue-template-for-your-repository
•  Pull 請(qǐng)求模板：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
•  貢獻(xiàn)指南（contribution guide）。應(yīng)該在貢獻(xiàn)指南中簡(jiǎn)單地說(shuō)明你希望外部用戶如何協(xié)助你改進(jìn)這個(gè)包。Scitime 的貢獻(xiàn)指南參見(jiàn)：https://github.com/nathan-toubiana/scitime/blob/master/.github/CONTRIBUTING.md。
•  準(zhǔn)則，Scitime 的準(zhǔn)則參見(jiàn)：https://github.com/nathan-toubiana/scitime/blob/master/.github/CODE_OF_CONDUCT.md
•  標(biāo)簽和說(shuō)明（見(jiàn)下面的截圖）
•  readme 文件中的標(biāo)簽（推薦一篇如何使用標(biāo)簽的好文章：https://medium.freecodecamp.org/how-to-use-badges-to-stop-feeling-like-a-noob-d4e6600d37d2）。

由于 readme 文件應(yīng)該相當(dāng)綜合，因此通常會(huì)有一個(gè)更詳細(xì)的文檔。你可以用 sphinx 來(lái)完成，然后在 readthedocs 上管理文檔。與文檔相關(guān)的文件通常放在 docs/文件夾中。sphinx 和 readthedocs 相關(guān)教程：https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html。

包含標(biāo)簽和說(shuō)明的項(xiàng)目庫(kù)示例

第 6 步：創(chuàng)建持續(xù)集成

此時(shí)，你的項(xiàng)目離發(fā)布就緒不遠(yuǎn)了。但是，在每次提交之后，必須更新文檔、運(yùn)行測(cè)試以及檢查樣式和覆蓋率似乎有點(diǎn)難以應(yīng)付。幸運(yùn)的是，持續(xù)集成（CI）可以幫助你完成。你可以在每次提交之后使用 GitHub 的 webhook 來(lái)自動(dòng)執(zhí)行所有的這些操作。以下是我們?cè)?SciTime 中使用的一套 CI 工具：

•  對(duì)于運(yùn)行測(cè)試，我們使用了 travis ci 和 appveyor（用于 Windows 平臺(tái)上的測(cè)試）。對(duì)于 Travis CI，除了在項(xiàng)目庫(kù)上設(shè)置 webhook 之外，你還必須創(chuàng)建一個(gè).travis.yml 文件，在該文件中，你不僅可以運(yùn)行測(cè)試，還可以上傳更新的覆蓋率輸出以及檢查樣式和格式。通過(guò)創(chuàng)建 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 文件的示例：請(qǐng)注意，每次提交，測(cè)試都需要與檢查測(cè)試覆蓋率一起進(jìn)行。但還有一個(gè) 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 文件示例：這里我們只運(yùn)行測(cè)試。

這將使更新項(xiàng)目庫(kù)的整個(gè)過(guò)程更加容易。

集成 webhook 的提交歷史記錄示例

第 7 步：創(chuàng)建你的第一個(gè) release 和 publication

此時(shí)，你即將發(fā)布的包應(yīng)與以下類似： 

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/ 

現(xiàn)在可以發(fā)布了！首先要做的是在 GitHub 上創(chuàng)建你的第一個(gè) release——這是為了在給定的時(shí)間點(diǎn)跟蹤項(xiàng)目的狀態(tài)，每次版本更改時(shí)都需要?jiǎng)?chuàng)建新的 release。創(chuàng)建步驟：https://help.github.com/en/articles/creating-releases。

完成后，唯一要做的就是發(fā)布包。發(fā)布 python 包最常見(jiàn)的平臺(tái)是 PyPI 和 Conda。以下我們將描述如何用兩者發(fā)布：

•  對(duì)于 PyPI，首先需要?jiǎng)?chuàng)建一個(gè)帳戶，然后用 twine 執(zhí)行一些步驟：https://realpython.com/pypi-publish-python-package/。這應(yīng)該相當(dāng)簡(jiǎn)單，而且 Pypi 還提供了一個(gè)可以在實(shí)際部署之前使用的測(cè)試環(huán)境。PyPI 總體上包括創(chuàng)建源代碼（python setup.py sdist）并使用 twine（twine upload dist/*）來(lái)上傳。完成后，應(yīng)該有一個(gè)與你的包對(duì)應(yīng)的 PyPI 頁(yè)面，并且任何人都應(yīng)該能夠通過(guò)運(yùn)行 pip 命令來(lái)安裝你的包。
• 對(duì)于 Conda，我們推薦通過(guò) conda forge 來(lái)發(fā)布你的包，conda forge 是一個(gè)社區(qū)，幫助你通過(guò) conda 渠道發(fā)布和維護(hù)包。你可以按照以下步驟將包添加到社區(qū)：https://conda-forge.org/#add_recipe，然后你會(huì)被添加到 conda forge Github 組織中，并能夠非常輕松地維護(hù)你的包，然后任何人都可以通過(guò)運(yùn)行 conda 命令來(lái)安裝你的包。

完成！

現(xiàn)在，你的包應(yīng)該已經(jīng)發(fā)出去，并且任何人都可以使用了！雖然大部分工作都完成了，但是你仍然需要維護(hù)你的項(xiàng)目，你需要進(jìn)行一些更新：這大體上意味著每次進(jìn)行重大更改時(shí)都要更改版本，創(chuàng)建新的 release，并再次執(zhí)行第 7 步。