手把手教你發佈 Python 項目開源包

編譯：機器之心，做者：Gabriel Lerner、Nathan Toubiana

好不容易碼了個 python 項目，是否是很興奮？那麼怎麼把這個項目發出去讓你們看到呢？本文做者寫了一份在 GitHub 上發佈 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 步。

原文連接：https://medium.freecodecamp.org/from-a-python-project-to-an-open-source-package-an-a-to-z-guide-c34cb7139a22

有關 Scitime 的詳細信息參見：

https://medium.com/m/global-identity?redirectUrl=https%3A%2F%2Fmedium.freecodecamp.org%2Ftwo-hours-later-and-still-running-how-to-keep-your-sklearn-fit-under-control-cc603dc1283b%3Fsource%3Dfriends_link%26sk%3D98e79add47516c38eeec59cf755df938）