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

好不容易碼了個 python 項目，是不是很興奮？那么怎么把這個項目發(fā)出去讓大家看到呢？本文作者寫了一份在 GitHub 上發(fā)布 python 包的簡單分步指南。

作者以 SciTime 項目(一個對算法訓練時間進行估計的包)的發(fā)布為例，詳細解釋了發(fā)布的每個步驟。

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

第 0 步：獲取項目許可證

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

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

第 1 步：讓你的代碼準備就緒

要將項目進行打包，你需要做一些預(yù)備工作：

• 讓你的項目結(jié)構(gòu)正確就位。通常情況下，項目庫的根目錄包含一個以項目名稱命名的文件夾，項目的核心代碼應(yīng)該位于此文件夾中。在這個文件夾之外是運行和構(gòu)建包(測試、文檔等)所需的其他代碼。

• 核心文件夾應(yīng)包括一個(或多個)模塊和一個 __init__.py 文件，該文件包含你希望讓終端用戶訪問的類/函數(shù)。此文件還可以包含包的版本，以便于終端用戶訪問。

• ?理想情況下，應(yīng)使用 logging 包來設(shè)置合理的日志記錄系統(tǒng)(而不是用 prints 輸出)。

• ?理想情況下，應(yīng)將你的核心代碼分配到一個或多個類中。

from?.estimate?import?Estimator

以__init__.py 為例，如果 Estimator 是終端用戶將會訪問的類(該類在 estimate.py 文件中定義)

import?logging


class?LogMixin(object):
????@propertydef?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

在你的項目有了一套結(jié)構(gòu)之后，你應(yīng)該在項目庫的根目錄下添加 setup.py 文件。這有助于所有發(fā)布和版本維護過程的自動化。以下是 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 參數(shù)來添加依賴項(如果列表很長，你可以像之前那樣指向一個 requirement.txt 文件)。

• 如果你希望在任何人安裝包時(從項目庫中)下載元數(shù)據(jù)，則應(yīng)通過 package_data 參數(shù)來添加這些元數(shù)據(jù)。

• 有關(guān) setup() 函數(shù)的更多信息，請參見：https://setuptools.readthedocs.io/en/latest/setuptools.html

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

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

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

一旦就位，你就可以通過在項目庫的根目錄運行 python -m pytest 在本地進行測試。

創(chuàng)建測試后，你還應(yīng)該能估算覆蓋率。這一點很重要，因為你希望盡可能多地測試項目中的代碼量(以減少意外的 bug)。

很多框架也可以用于計算覆蓋率，對于 SciTime，我們使用了 codecov。你可以通過創(chuàng)建.codecov.yml 文件來決定允許的最小覆蓋率閾值，還可以通過創(chuàng)建.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 步：創(chuàng)建一個合理的文檔

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

• Pull 請求和 issue 模板：當創(chuàng)建新的 Pull 請求或 issue 時，這些文件可以根據(jù)你的需求給你的描述提供模板。

• ? ? ? Pull 請求創(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 請求模板：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)。應(yīng)該在貢獻指南中簡單地說明你希望外部用戶如何協(xié)助你改進這個包。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 文件應(yīng)該相當綜合，因此通常會有一個更詳細的文檔。你可以用 sphinx 來完成，然后在 readthedocs 上管理文檔。與文檔相關(guān)的文件通常放在 docs/文件夾中。sphinx 和 readthedocs 相關(guān)教程：https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html。

包含標簽和說明的項目庫示例

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

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

• 對于運行測試，我們使用了 travis ci 和 appveyor(用于 Windows 平臺上的測試)。對于 Travis CI，除了在項目庫上設(shè)置 webhook 之外，你還必須創(chuàng)建一個.travis.yml 文件，在該文件中，你不僅可以運行測試，還可以上傳更新的覆蓋率輸出以及檢查樣式和格式。通過創(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 文件的示例：請注意，每次提交，測試都需要與檢查測試覆蓋率一起進行。但還有一個 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 步：創(chuàng)建你的第一個 release 和 publication

此時，你即將發(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)建你的第一個 release——這是為了在給定的時間點跟蹤項目的狀態(tài)，每次版本更改時都需要創(chuàng)建新的 release。創(chuàng)建步驟：https://help.github.com/en/articles/creating-releases。

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

• 對于 PyPI，首先需要創(chuàng)建一個帳戶，然后用 twine 執(zhí)行一些步驟：https://realpython.com/pypi-publish-python-package/。這應(yīng)該相當簡單，而且 Pypi 還提供了一個可以在實際部署之前使用的測試環(huán)境。PyPI 總體上包括創(chuàng)建源代碼(python setup.py sdist)并使用 twine(twine upload dist/*)來上傳。完成后，應(yīng)該有一個與你的包對應(yīng)的 PyPI 頁面，并且任何人都應(yīng)該能夠通過運行 pip 命令來安裝你的包。

• ?對于 Conda，我們推薦通過 conda forge 來發(fā)布你的包，conda forge 是一個社區(qū)，幫助你通過 conda 渠道發(fā)布和維護包。你可以按照以下步驟將包添加到社區(qū)：https://conda-forge.org/#add_recipe，然后你會被添加到 conda forge Github 組織中，并能夠非常輕松地維護你的包，然后任何人都可以通過運行 conda 命令來安裝你的包。

完成！

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

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

有關(guān) 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)

總結(jié)

以上是生活随笔為你收集整理的引入yml依赖包_手把手教你发布 Python 项目开源包的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。