zest.releaser 技术文档

1. 安装指南

zest.releaser 是一个用于自动化 Python 项目发布的命令行工具集合。它可以帮助你自动完成版本号更新、历史记录更新、版本控制标签创建以及上传到 PyPI 等任务。

安装方式

你可以通过以下方式安装 zest.releaser：

1. 使用 pip 安装：

   pip install zest.releaser
   

2. 安装推荐的额外工具： 如果你希望安装推荐的额外工具（如 wheel、check-manifest、pyroma 和 readme_renderer），可以使用以下命令：

   pip install zest.releaser[recommended]
   

3. 使用 buildout 安装： 如果你使用 buildout，可以在项目的 buildout 配置文件中添加以下内容：

   [buildout]
   parts =
       scripts
   
   [scripts]
   recipe = zc.recipe.egg
   eggs = zest.releaser[recommended]
   

2. 项目的使用说明

zest.releaser 提供了多个命令来帮助你发布 Python 包。这些命令必须在版本控制的代码库中运行。

主要命令

• prerelease：询问你新的版本号（默认为当前版本号去掉 dev 等标记），更新 setup.py 或 version.txt 以及 CHANGES/HISTORY/CHANGELOG 文件，并提交这些更改到版本控制系统。

• release：从当前代码库的主干或分支创建一个版本控制标签，并在临时目录中生成一个标签的检出。然后，它会询问你是否要将该包的源代码发布到 PyPI。

• postrelease：询问你新的版本号（提供一个合理的默认值），并为其添加开发标记。更新 setup.py 或 version.txt 以及 CHANGES/HISTORY/CHANGELOG 文件，并提交这些更改到版本控制系统。

• fullrelease：依次执行 prerelease、release 和 postrelease 命令。

其他工具

• longtest：渲染长描述并在浏览器中打开，方便在上传到 PyPI 之前调试格式问题。

• lasttagdiff：显示当前分支与上一个发布标签之间的差异，方便检查所有更改是否在变更文件中得到充分描述。

• lasttaglog：显示当前分支自上一个发布标签以来的日志，方便检查所有更改是否在变更文件中得到充分描述。

• addchangelogentry：将命令行中提供的文本添加到变更日志中，并作为提交消息。适用于批量更改多个包时使用。

• bumpversion：仅更新版本号，不进行发布。如果存在开发标记，则保留该标记。使用 --feature 选项更新次版本号，使用 --breaking 选项更新主版本号。

3. 项目 API 使用文档

zest.releaser 主要通过命令行工具提供功能，因此没有直接的 API 接口。你可以通过命令行调用上述命令来完成项目的发布和管理。

示例

以下是一些常见的使用示例：

1. 预发布：

   prerelease
   

2. 发布：

   release
   

3. 后发布：

   postrelease
   

4. 完整发布：

   fullrelease
   

5. 仅更新版本号：

   bumpversion --feature
   

4. 项目安装方式

zest.releaser 可以通过 pip 或 buildout 进行安装。推荐使用 pip 安装，因为它简单且易于管理。

使用 pip 安装

pip install zest.releaser

安装推荐的额外工具

pip install zest.releaser[recommended]

使用 buildout 安装

在 buildout 配置文件中添加以下内容：

[buildout]
parts =
    scripts

[scripts]
recipe = zc.recipe.egg
eggs = zest.releaser[recommended]

通过以上步骤，你可以轻松安装并使用 zest.releaser 来管理你的 Python 项目发布流程。