放弃对旧版 Python 版本的支持#

放弃对旧版 Python 版本的支持受标准 核心元数据规范 1.2 规范通过“Requires-Python”属性的支持。

元数据 1.2+ 客户端（如 Pip 9.0+）将通过匹配当前 Python 运行时并将其与包元数据中的所需版本进行比较来遵守此规范。如果它们不匹配，它将尝试安装支持该 Python 运行时的最后一个包分发。

可以通过修改包元数据中的“Requires-Python”属性来使用此机制放弃对旧版 Python 版本的支持。

本指南专门针对 Setuptools 的用户，其他打包工具（如 flit）可能提供类似的功能，但用户需要查阅相关文档。

要求#

此工作流要求

  1. 发布者使用最新版本的 Setuptools，

  2. 使用最新版本的 twine 上传包，

  3. 安装包的用户至少具有 Pip 9.0 或支持元数据 1.2 规范的客户端。

处理通用轮子#

传统上，提供与 Python 2 和 Python 3 语义兼容的 Python 代码的项目会生成 轮子，其名称中带有 py2.py3 标记。在放弃对 Python 2 的支持时，重要的是不要忘记将此标记更改为仅 py3。如果使用 setuptools，通常在 setup.cfg 中 [bdist_wheel] 部分下通过设置 universal = 1 来配置它。

如果您使用此方法，请删除此选项或部分，或明确将 universal 设置为 0

# setup.cfg

[bdist_wheel]
universal = 0  # Make the generated wheels have "py3" tag

提示

由于可以通过 CLI 标志覆盖 setup.cfg 设置，因此请确保您的脚本在包创建脚本中没有 --universal。

定义所需的 Python 版本#

1. 下载最新版本的 Setuptools#

确保在生成源分发或二进制分发之前，更新 Setuptools 并安装 twine。

步骤

python3 -m pip install --upgrade setuptools twine

py -m pip install --upgrade setuptools twine

setuptools 版本应高于 24.0.0。

2. 指定受支持的 Python 发行版的版本范围#

您可以指定版本范围和排除规则，例如至少 Python 3。或者，Python 2.7、3.4 及更高版本。

示例

Requires-Python: ">=3"
Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"

设置这些值的方法是在 setup.py 脚本中的 setup 调用中。这会根据您在 python_requires 中提供的参数插入 Requires-Python 元数据值。

from setuptools import setup


setup(
    # Your setup arguments
    python_requires='>=2.7',  # Your supported Python ranges
)

3. 在发布之前验证元数据#

在 Python 源代码包（您下载的 zip 或 tar-gz 文件）中有一个名为 PKG-INFO 的文本文件。

当 distutils 或 Setuptools 生成源代码包时，会生成此文件。该文件包含一组键和值，键列表是 PyPa 标准元数据格式的一部分。

您可以像这样查看生成的文件内容

tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO

在发布包之前，验证以下内容是否就位

  • 如果您已正确升级，则 Metadata-Version 值应为 1.2 或更高版本。

  • Requires-Python 字段已设置，并且与您在 setup.py 中的规范相匹配。

4. 使用 Twine 发布#

除了速度更快之外，Twine 还具有许多优势，它现在是发布包的受支持方法。

确保您使用的是最新版本的 Twine，至少为 1.9。

放弃 Python 版本#

在您使用 Requires-Python 元数据发布包后，您可以进行进一步更新，以从支持中删除该 Python 运行时。

必须按此顺序进行，才能使自动回退正常工作。

例如，您发布了 Requires-Python: “>=2.7” 作为您的包的 1.0.0 版本。

如果您随后将版本字符串更新为 “>=3.5”，并发布您包的新版本 2.0.0，那么从 2.7 版运行 Pip 9.0+ 的任何用户都将安装该包的 1.0.0 版，而 >=3.5 的任何用户都将收到 2.0.0 版。