如何在Python包中控制只允许特定Python版本使用

在发布Python包时,有时候我们想要限制只能在某些Python版本中使用,防止用户在不兼容的版本中安装使用。本文将介绍在构建Python包时,如何通过设置来只允许特定Python版本运行。

使用python_requires

Python包的元数据中包含一个python_requires字段,用于指定package的Python版本依赖关系。在setup.py或setup.cfg中设置这个字段可以检查Python版本:

python
# setup.py

from setuptools import setup

setup(
  name='mypackage',
  python_requires='>=3.6', # 需要Python 3.6或以上
)

ini
# setup.cfg

[options]
python_requires = >=3.6

在用户使用pip安装该package时,会检查Python版本,如果低于指定的版本,将会产生错误并终止安装过程。

所以通过python_requires可以方便地限制只在某些Python版本中使用。例如只需要Python 3.10+:

python
python_requires='>=3.10'

需要注意的是,只检查版本是不够的,还需要确保代码能在该Python版本下正常运行。所以在设置版本限制时,要提前在所有支持的版本中测试package。

设置classifiers

PyPI页面会显示package的元数据信息,其中就包含一个classifiers字段,它指定了该package的分类信息,包括支持的Python版本。

例如只支持Python 3.10+可以这样设置classifiers:

python
classifiers=[
  'Programming Language :: Python :: 3',
  'Programming Language :: Python :: 3.10',
  'Programming Language :: Python :: 3.11',
]

我们指定了一个general的Python 3分类,以及具体的3.10和3.11版本。这样PyPI页面就会显示这些信息,说明只兼容这两个版本。

与python_requires不同,classifiers不会主动检查版本,仅起说明作用。但设置准确的classifiers可以让用户一目了然该package的Python兼容性。

classifiers还可以指定包的适用平台、许可证、操作系统等信息,非常全面,可以参考官方classifiers列表。

https://pypi.org/classifiers/

版本范围的环境标记

在requirements中可以使用PEP 440定义的版本规范和环境标记来表示依赖关系。例如:

package1
package2; python_version > "3.6"
这表示package2需要Python 3.6以上。

所以可以用这种方式在requirements中加上版本限制,也是控制兼容性的一种方式。

随着Python版本维护classifiers

随着Python的更新,当添加或移除对某些Python版本的支持时,需要同步更新python_requires和classifiers的声明。

一般的维护流程是:

1. 在新版本中测试package,确保兼容
2. 发布时在setup.py和PyPI元数据中添加该版本的声明 例如Python 3.12发布后,可以更新为:

python
python_requires='>=3.10,<4.0' 

classifiers=[
  ...,
  'Programming Language :: Python :: 3.12',
]

如果不再支持某旧版本,也需要删除对应classifiers声明。

通过持续维护,可以确保classifiers和python_requires准确反映package兼容的Python版本。这在长期维护一个package时十分必要。

总结

• python_requires可以限制Python版本
• classifiers发布元数据表示兼容版本
• 版本范围的环境标记也可用于指定依赖关系
• 随着Python版本要持续维护元数据

利用好这些机制,就可以方便地控制package只在特定Python版本下可用,避免用户在不兼容环境中安装使用。同时也方便用户一眼看清package的Python兼容性。对于库的作者和使用者来说,都是很有必要的功能。