如何使用Astropy模板创建和维护Python包

如果你遇到任何问题,不要犹豫,在astropy dev邮件列表上寻求帮助!

这个 package-template 存储库为Python包提供了一个模板。这套设计反映了主管道的布局 Astropy 以及重用许多用于组织的帮助程序代码 Astropy . 见 package template documentation 有关使用包模板的说明。

发布Python包

您可以使用以下步骤发布包。在这些说明中,我们假设发布是从远程“主”存储库的新克隆生成的,而不是从分叉副本生成的。我们还假设changelog文件名为 CHANGES.rst ,就像astropy的核心包。如果改为使用Markdown,则应该替换 CHANGES.rst 通过 CHANGES.md 在说明书里。

备注

下面的说明假设您没有在工作流中使用bug修复分支。如果你想创建一个错误修复分支,我们建议你阅读更完整的astropy 放行程序 并根据您的套餐进行调整。

  1. 确保持续集成正在通过。

  2. 更新 CHANGES.rst 文件以确保列出所有更改,并更新当前应设置为的发布日期 unreleased ,到当前日期 yyyy-mm-dd 格式。

  3. 更新中的版本号 setup.cfg 对于即将发布的版本,没有 .dev 后缀(例如。 0.1 ). 如果您的软件包使用setuptools_scm来管理版本号,则可以跳过此步骤。

  4. git clean -fxd 删除任何未跟踪的文件(警告:这将永久删除以前未提交的所有文件,因此请确保您不需要保留这些文件)。

  5. 此时,运行以生成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 标志或在完全测试包时通常添加的任何其他标志。

  6. 返回目录的根目录并使用以下命令删除生成的文件:

    git clean -fxd
    
  7. 将更改添加到 CHANGES.rstsetup.cfg ::

    git add CHANGES.rst setup.cfg
    

    并通过以下信息提交:

    git commit -m "Preparing release <version>"
    
  8. 使用标记提交 v<version> ,可以选择使用 -s 选项:

    git tag v<version>
    
  9. 变化 VERSION 在里面 setup.cfg 到下一个版本号,但是 .dev 结尾的后缀(例如。 0.2.dev ). 将新分区添加到 CHANGES.rst 对于下一个版本,只有一个条目 No changes yet ,例如:

    0.2 (unreleased)
    ----------------
    
    - No changes yet
    
  10. 将更改添加到 CHANGES.rstsetup.cfg ::

    git add CHANGES.rst setup.cfg
    

    并通过以下信息提交:

    git commit -m "Back to development: <next_version>"
    
  11. 查看发布提交 git checkout v<version> . 跑 git clean -fxd 删除任何未提交的文件。

  12. (可选)在模拟“典型用户”场景的环境中运行测试。这不是严格意义上必需的,因为您运行了上面的测试,但有时使用定制的开发人员环境来捕捉可能来自您的细微错误。有关设置虚拟环境的更多信息,请参阅 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>
    

    如果您认为您的用户可能安装了其他相关软件包,那么您可能需要对其他依赖项组合重复此操作。假设所有测试都通过了,您可以继续。

  13. 如果您执行了上一步,请执行 git clean -fxd again to remove anything you made there. Run python -m build --sdist . 创建要上载的文件。然后可以通过 twine ::

    twine upload dist/*
    

    如上所述 these 说明。检查PyPI上的条目是否正确,以及tarfile是否存在。

  14. 返回主分支并将更改推送到github::

    git checkout master
    git push --tags origin master
    

    完成此操作后,如果使用Read the Docs,则触发 latest 生成,然后转到项目设置,然后在 版本 你应该看到你刚刚按下的标签。选择要激活的标记,然后保存。

  15. 如果您的软件包在 conda-forge conda频道,您还应该提交一个请求,以更新您的包的原料中的版本号。

测试版/发布候选版本的修改

在包的新版本发布之前,您可能希望对代码进行“预发布”,例如,允许协作者独立测试该版本。如果您正在执行的发布是这种预发布,那么需要修改上面的一些步骤。

发布程序的主要修改是:

  • 当输入新版本号时,而不是仅仅删除 .dev ,输入“1.2b1”或“1.2rc1”。您必须遵循此编号规则 (X.Yb#X.Y.Zrc# ),因为它将确保发布是由各种自动化工具“在”主发布之前”排序的,并且还告诉PyPI这是一个“预发布”。