如何使用Astropy模板创建和维护Python包¶
如果你遇到任何问题,不要犹豫,在astropy dev邮件列表上寻求帮助!
这个 package-template 存储库为Python包提供了一个模板。这套设计反映了主管道的布局 Astropy 以及重用许多用于组织的帮助程序代码 Astropy . 见 package template documentation 有关使用包模板的说明。
发布Python包¶
您可以使用以下步骤发布包。在这些说明中,我们假设发布是从远程“主”存储库的新克隆生成的,而不是从分叉副本生成的。我们还假设changelog文件名为 CHANGES.rst
,就像astropy的核心包。如果改为使用Markdown,则应该替换 CHANGES.rst
通过 CHANGES.md
在说明书里。
备注
下面的说明假设您没有在工作流中使用bug修复分支。如果你想创建一个错误修复分支,我们建议你阅读更完整的astropy 放行程序 并根据您的套餐进行调整。
确保持续集成正在通过。
更新
CHANGES.rst
文件以确保列出所有更改,并更新当前应设置为的发布日期unreleased
,到当前日期yyyy-mm-dd
格式。更新中的版本号
setup.cfg
对于即将发布的版本,没有.dev
后缀(例如。0.1
). 如果您的软件包使用setuptools_scm来管理版本号,则可以跳过此步骤。跑
git clean -fxd
删除任何未跟踪的文件(警告:这将永久删除以前未提交的所有文件,因此请确保您不需要保留这些文件)。此时,运行以生成tar文件的命令将取决于您的包是否具有
pyproject.toml
不管有没有文件。如果没有,那么:python setup.py build sdist --format=gztar
如果是,那么首先要确保 build 程序包已安装并处于最新状态:
pip install build --upgrade
然后使用以下命令创建源分发:
python -m build --sdist .
以下所有说明将假定您
pyproject.toml
. 如果你不使用pyproject.toml
不过,请看https://docs.astropy.org/en/v4.0.x/development/astropy-package-template.html相反。在这两种情况下,都要确保生成的文件可以进入内部
dist
,展开tar文件,进入展开的目录,并使用以下命令运行测试:pip install -e .[test] pytest
您可能需要添加
--remote-data
标志或在完全测试包时通常添加的任何其他标志。返回目录的根目录并使用以下命令删除生成的文件:
git clean -fxd
将更改添加到
CHANGES.rst
和setup.cfg
::git add CHANGES.rst setup.cfg
并通过以下信息提交:
git commit -m "Preparing release <version>"
使用标记提交
v<version>
,可以选择使用-s
选项:git tag v<version>
变化
VERSION
在里面setup.cfg
到下一个版本号,但是.dev
结尾的后缀(例如。0.2.dev
). 将新分区添加到CHANGES.rst
对于下一个版本,只有一个条目No changes yet
,例如:0.2 (unreleased) ---------------- - No changes yet
将更改添加到
CHANGES.rst
和setup.cfg
::git add CHANGES.rst setup.cfg
并通过以下信息提交:
git commit -m "Back to development: <next_version>"
查看发布提交
git checkout v<version>
. 跑git clean -fxd
删除任何未提交的文件。(可选)在模拟“典型用户”场景的环境中运行测试。这不是严格意义上必需的,因为您运行了上面的测试,但有时使用定制的开发人员环境来捕捉可能来自您的细微错误。有关设置虚拟环境的更多信息,请参阅 Python虚拟环境 ,但为了示例起见,我们假设您使用 Anaconda . 执行事项:
conda create -n myaffilpkg_rel_test astropy <any more dependencies here> source activate myaffilpkg_rel_test python -m build --sdist . cd dist pip install myaffilpkg-version.tar.gz python -c 'import myaffilpkg; myaffilpkg.test()' source deactivate cd <back to your source>
如果您认为您的用户可能安装了其他相关软件包,那么您可能需要对其他依赖项组合重复此操作。假设所有测试都通过了,您可以继续。
如果您执行了上一步,请执行
git clean -fxd
again to remove anything you made there. Runpython -m build --sdist .
创建要上载的文件。然后可以通过twine
::twine upload dist/*
如上所述 these 说明。检查PyPI上的条目是否正确,以及tarfile是否存在。
返回主分支并将更改推送到github::
git checkout master git push --tags origin master
完成此操作后,如果使用Read the Docs,则触发
latest
生成,然后转到项目设置,然后在 版本 你应该看到你刚刚按下的标签。选择要激活的标记,然后保存。如果您的软件包在
conda-forge
conda频道,您还应该提交一个请求,以更新您的包的原料中的版本号。
测试版/发布候选版本的修改¶
在包的新版本发布之前,您可能希望对代码进行“预发布”,例如,允许协作者独立测试该版本。如果您正在执行的发布是这种预发布,那么需要修改上面的一些步骤。
发布程序的主要修改是:
当输入新版本号时,而不是仅仅删除
.dev
,输入“1.2b1”或“1.2rc1”。您必须遵循此编号规则 (X.Yb#
或X.Y.Zrc#
),因为它将确保发布是由各种自动化工具“在”主发布之前”排序的,并且还告诉PyPI这是一个“预发布”。