写的加布里埃尔·勒纳和内森Toubiana

兴奋您的python项目吗?你想与更广泛的受众分享吗?包装和发布您的软件包是一个伟大的方式让别人对您的项目很感兴趣。这是一个简单的一步一步指导构建和发布你的第一个python包。

我们将描述我们经历的所有步骤创建年代citime一个包,给估计算法的训练时间(你可以了解更多关于Scitime在这里)。

请注意:我们将在GitHub假设您已经有一个项目,你想打包和发布。

步骤0:让你的项目授权

在做任何其他事情之前,你的项目应该有一个许可证,因为它是开源的。这取决于你想包使用,许多可用的许可证。一些许可证上的开源项目麻省理工学院,BSD或GPL。

添加一个项目许可证,简单地添加一个许可证文件存储库根按照描述的步骤在这里。

步骤1:使代码publish-ready

有一些初步的事情你需要做你的项目package-able:

• 您的项目结构需要到位。通常,存储库的根目录中包含一个存储库文件夹的名字——这就是核心项目代码。这个文件夹以外的是必要的额外的代码运行,构建包(测试、文档等)
• 文件夹应该包含一个(或多个)核心模块(s)和一个__init__ . py文件导入类/函数你会希望最终用户有访问权。这个文件还可以包含包的版本,使它容易给最终用户。
• 理想情况下,一个适当的日志系统(而不是打印)应设置使用日志记录包中。
• 当有关,你应该组织在一个或多个核心代码类。

步骤2:创建一个设置。py和setuptools

一旦你的项目有一组结构,你应该添加一个设置。py文件存储库的根源。这个主要是帮助自动化所有的发布和版本维护流程。这里有一个例子的设置。py应该类似于(源在这里)。

一些笔记:

• 如果你的包最低依赖,一个干净的处理这些的方法是将它们添加在安装文件中,通过install_requires论点。如果你想分享所有传递依赖,你也可以traditionnally指向它们requirement.txt(然而,只有最小依赖关系必须在setup . py)
• 如果你想要的元数据(从存储库)当有人下载安装包,你应该将这些通过添加package_data论点
• 更多的信息设置()函数可以被发现在这里

注意:步骤3到6是可选的(但强烈推荐),但是你可以直接跳到步骤7现在如果你想出版你的包裹。

步骤3:设置本地测试和测试覆盖率检查

如果尚未如此,在这一点上,您的项目应该有单元测试。虽然有许多框架可以帮助你做到这一点,一个简单的方法是使用pytest。所有测试都应该在一个专用的文件夹(命名测试/或测试/例如)。在那个文件夹,把所有你所需要的测试文件,以覆盖尽可能多的你的核心代码。这里有一个例子如何编写一个单元测试。这也是我们的一个年代citime的测试文件。

一旦到位,您可以通过运行在本地运行你的测试python - m pytest从存储库根。

一旦创建你的测试,你还应该能够估计覆盖。这是很重要的,正如你想最大化的代码量的测试项目(减少意外的bug)。

很多框架可用于这个,Scitime我们使用codecov。你可以确定一个阈值的最小覆盖允许通过创建一个.codecov.yml文件并决定哪些文件包含覆盖分析通过创建一个.coveragerc文件。

步骤4:规范语法和代码风格

您还需要确保您的代码遵循PEP8指南(我。e标准样式,语法是正确的)。再次,很多工具可以帮助。我们使用flake8。

第五步:创建一个适当的文档

现在,您的项目已经测试和一个好的结构,它应该是一个很好的时间来添加一个适当的文档。第一件事是有一个不错的readme文件将出现在你的Github回购根。一旦这样做,这里有一些额外的“好”:

• 把请求模板和问题:创建一个新的公关或问题时,这些文件允许你模板的描述。遵循这些步骤PRs和这些步骤对问题创建它们。以下是Scitime的公关模板和问题模板。
• 一个贡献指南。这应该是一个简短的指南如何外部用户为你的包。这是Scitime的贡献指南。
• 一个的行为准则(这里的年代citime的)。
• 标签和描述(见截图)。
• 徽章在readme文件(这是一个不错的文章如何设置这些)。

readme文件应该很综合,它也是非常标准的有一个更深入的文档。您可以使用斯芬克斯这样做,然后主机的文档readthedocs(这是Scitime的例子)。通常在一个相关的文档文件文档/文件夹(作为年代完成citime)。这是一个不错的斯芬克斯& readthedocs教程。

第六步:建立持续集成

在这一点上,您的项目并不是远离准备出版。然而,似乎有些过了,必须处理更新文档,运行测试和检查方式和报道后提交。幸运的是,持续集成(CI)可以帮助你。您可以使用人GitHub自动化每次提交后所有这些事情。这是我们用于Scitime CI工具的设置:

• 为了运行测试,我们使用travis-ci和appveyor(用于测试在windows平台上)。travis-ci,除了设置存储库上的人,您还需要创建一个.travis.yml文件,你不仅运行测试,还可以上传更新覆盖输出并检查样式和格式。通过创建一个appveyor也是一样appveyor.yml文件
• Codecov和readthdocs也有专门的人

这应该使更新存储库的整个过程变得更简单。

第七步:创建您的第一个版本出版

在这一点上,你即将包应类似于:

your_package /
__init__ . py
your_module.py文档/
测试/
setup . py
travis.yml
appveyor.yml
.coveragerc
.codecov.yml
README.md
许可证.github /
CODE_OF_CONDUCT.md
CONTRIBUTING.md
PULL_REQUEST_TEMPLATE.md
ISSUE_TEMPLATE /

现在准备出版!首先要做的是创建你的第一个版本在GitHub——这是跟踪你的项目在一个给定的时间点,每次应该创建一个发布版本的变化。您可以遵循这创建发布。

一旦完成,剩下要做的唯一的事就是发布您的软件包。最常见的平台上发布一个python包PyPI和Conda。我们将介绍如何发表在:

• 在PyPI,您首先需要创建一个账户,然后按照以下步骤使用线。这应该是相当简单的,PyPI还提供了一个测试环境,可以用在实际的部署。后者主要包括创建一个源分布(python的设置。py sdist用细绳()和上传线上传dist / *)。一旦完成,应该有一个PyPI页面对应于您的软件包(这里的年代citime的),任何人都应该能够运行安装包皮普命令。
• 对于conda,我们建议出版您的软件包conda-forge这是一个社区,帮助你通过conda渠道发布和维护您的软件包。你可以按照以下步骤包添加到社区,你就会被添加到conda-forge GitHub组织并能够维持你的包很容易(这是Scitime conda-forge页面)——任何人都应该能够运行安装包conda命令。

全部完成!

你现在应该包最终出版,而且任何人都可以!虽然大部分工作已经完成,你将仍然需要保持你的项目需要做一些更新:这基本上意味着每次你做出重大的改变,改变了版本创建新版本并再次经历步骤7。