您好,登錄后才能下訂單哦!
本文假設(shè)你在 GitHub 上已經(jīng)有一個(gè)想要打包和發(fā)布的項(xiàng)目。
第 0 步:獲取項(xiàng)目許可證
在做其他事之前,由于你的項(xiàng)目要開源,因此應(yīng)該有一個(gè)許可證。獲取哪種許可證取決于項(xiàng)目包的使用方式。開源項(xiàng)目中一些常見許可證有 MIT 或 BSD。
要在項(xiàng)目中添加許可證,只需參照以下鏈接中的步驟,將 LICENSE 文件添加到項(xiàng)目庫中的根目錄即可:https://help.github.com/en/articles/adding-a-license-to-a-repository
第 1 步:讓你的代碼準(zhǔn)備就緒
要將項(xiàng)目進(jìn)行打包,你需要做一些預(yù)備工作:
from .estimate import Estimator
以__init__.py 為例,如果 Estimator 是終端用戶將會(huì)訪問的類(該類在 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)目庫的根目錄下添加 setup.py 文件。這有助于所有發(fā)布和版本維護(hù)過程的自動(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):
注意:第 3 步到第 6 步是可選的(但強(qiáng)烈推薦),但是如果你現(xiàn)在馬上想發(fā)布你的包,可以直接跳到第 7 步。
第 3 步:設(shè)置本地測試和檢查測試覆蓋率
此時(shí)還沒有完成,你的項(xiàng)目還應(yīng)該有單元測試。盡管有許多框架能幫助你做到,但一種簡單的方法是使用 pytest。所有測試都應(yīng)該放在一個(gè)專用的文件夾中(例如名為 tests/或 testing 的文件夾)。在這個(gè)文件夾中放置你需要的所有測試文件,以便盡可能多地包含你的核心代碼。下面是一個(gè)如何編寫單元測試的示例。這里還有一個(gè) SciTime 的測試文件。
一旦就位,你就可以通過在項(xiàng)目庫的根目錄運(yùn)行 python -m pytest 在本地進(jìn)行測試。
創(chuàng)建測試后,你還應(yīng)該能估算覆蓋率。這一點(diǎn)很重要,因?yàn)槟阆MM可能多地測試項(xiàng)目中的代碼量(以減少意外的 bug)。
很多框架也可以用于計(jì)算覆蓋率,對于 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 步:標(biāo)準(zhǔn)化語法和代碼風(fēng)格
你還需要確保你的代碼遵循 PEP8 準(zhǔn)則(即具有標(biāo)準(zhǔn)樣式并且語法正確)。同樣,有很多工具可以幫助你解決。這里我們用了 flake8。
第 5 步:創(chuàng)建一個(gè)合理的文檔
現(xiàn)在你的項(xiàng)目已經(jīng)測試過了,結(jié)構(gòu)也很好了,是時(shí)候添加一個(gè)合理的文檔。首先是要有一個(gè)好的 readme 文件,它會(huì)在你的 Github 項(xiàng)目庫的根目錄上顯示。完成后,加上以下幾點(diǎn)會(huì)更好:
由于 readme 文件應(yīng)該相當(dāng)綜合,因此通常會(huì)有一個(gè)更詳細(xì)的文檔。你可以用 sphinx 來完成,然后在 readthedocs 上管理文檔。與文檔相關(guān)的文件通常放在 docs/文件夾中。sphinx 和 readthedocs 相關(guān)教程:https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html。
包含標(biāo)簽和說明的項(xiàng)目庫示例
第 6 步:創(chuàng)建持續(xù)集成
此時(shí),你的項(xiàng)目離發(fā)布就緒不遠(yuǎn)了。但是,在每次提交之后,必須更新文檔、運(yùn)行測試以及檢查樣式和覆蓋率似乎有點(diǎn)難以應(yīng)付。幸運(yùn)的是,持續(xù)集成(CI)可以幫助你完成。你可以在每次提交之后使用 GitHub 的 webhook 來自動(dòng)執(zhí)行所有的這些操作。以下是我們在 SciTime 中使用的一套 CI 工具:
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 文件的示例:請注意,每次提交,測試都需要與檢查測試覆蓋率一起進(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)行測試
這將使更新項(xiàng)目庫的整個(gè)過程更加容易。
集成 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。
完成后,唯一要做的就是發(fā)布包。發(fā)布 python 包最常見的平臺(tái)是 PyPI 和 Conda。以下我們將描述如何用兩者發(fā)布:
完成!
現(xiàn)在,你的包應(yīng)該已經(jīng)發(fā)出去,并且任何人都可以使用了!雖然大部分工作都完成了,但是你仍然需要維護(hù)你的項(xiàng)目,你需要進(jìn)行一些更新:這大體上意味著每次進(jìn)行重大更改時(shí)都要更改版本,創(chuàng)建新的 release,并再次執(zhí)行第 7 步。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場,如果涉及侵權(quán)請聯(lián)系站長郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。