check-python-versions 0.22.0

安装

运行 check-python-versions 需要 Python 3.6 或更高版本（f-strings！）。使用以下命令安装它：

python3 -m pip install check-python-versions

用法

$ check-python-versions --help
usage: check-python-versions [-h] [--version] [--expect VERSIONS]
                             [--skip-non-packages] [--only FILES]
                             [--add VERSIONS] [--drop VERSIONS]
                             [--update VERSIONS] [--diff] [--dry-run]
                             [where [where ...]]

verify that supported Python versions are the same in setup.py, tox.ini,
.travis.yml and appveyor.yml

positional arguments:
  where                directory where a Python package with a setup.py and
                       other files is located

optional arguments:
  -h, --help           show this help message and exit
  --version            show program's version number and exit
  --expect VERSIONS    expect these versions to be supported, e.g. --expect
                       2.7,3.5-3.8
  --skip-non-packages  skip arguments that are not Python packages without
                       warning about them
  --only FILES         check only the specified files (comma-separated list,
                       e.g. --only tox.ini,appveyor.yml)

updating supported version lists (EXPERIMENTAL):
  --add VERSIONS       add these versions to supported ones, e.g --add 3.9
  --drop VERSIONS      drop these versions from supported ones, e.g --drop
                       2.6,3.4
  --update VERSIONS    update the set of supported versions, e.g. --update
                       2.7,3.5-3.9
  --diff               show a diff of proposed changes
  --dry-run            verify proposed changes without writing them to disk

如果没有提供任何参数运行，check-python-versions 将在当前工作目录中查找 setup.py。

如果所有 Python 包的版本号一致（如果指定了 –expect，则这些数字与您的期望匹配），则退出状态为 0。

如果您在命令行上指定了多个目录，则所有检查失败的包将在运行结束时列出，用空格分隔，以便更容易复制和粘贴到 shell 命令行。当您想运行

check-python-versions ~/src/zopefoundation/*

来检查所有 380 多个包，然后只想重新运行失败的检查，以提高效率时，这很有帮助。

此外，还提供了对更新支持的 Python 版本的实验性支持，因此您可以执行类似的操作

check-python-versions ~/projects/* --add 3.9 --dry-run --expect 2.7,3.6-3.9
check-python-versions ~/projects/* --drop 3.4 --diff
check-python-versions ~/projects/* --update 2.7,3.6- --dry-run --diff
check-python-versions ~/projects/* --add 3.9 --drop=-2.6,-3.5

（最后一个将显示每个文件的差异，并在进行任何更改之前要求交互式确认。）

程序化更新可由人类编写的文件很困难，因此请预期会有错误（并且请提交问题）。

文件

setup.py 或 pyproject.toml 是唯一必需的文件；如果缺少其他任何文件，它们将被忽略（并且这不会被视为失败）。

• setup.py：传递给 setup() 的 classifiers 参数应具有以下形式的分类器

  classifiers=[
      ...
      "Programming Language :: Python :: x.y",
      ...
  ],

  check-python-versions 将尝试解析文件并遍历 AST 以提取分类器，但如果失败，它将执行 python setup.py --classifiers 并解析输出。

  如果至少有一部分是列表字面量，则提供了对动态计算分类器的原始支持，例如这可以工作，甚至可以更新

  classifiers=[
      ...
      "Programming Language :: Python :: x.y",
      ...
  ] + ... expression that computes extra classifiers ...,

• setup.py：传递给 setup() 的 python_requires 参数（如果存在）

  python_requires=">=2.7, !=3.0.*, !=3.1.*",

  check-python-versions 将尝试解析文件并遍历 AST 以提取 python_requires 值。它期望找到一个字符串字面量或形式为 "literal".join(["...", "..."]) 的简单表达式。

• pyproject.toml 可以有这些中的任何一个

  # PEP 621 static metadata
  
  [project]
  classifiers = [
      ...
      "Programming Language :: Python :: 3.8",
      ...
  ]
  requires-python = ">= 3.8"
  
  # old-style Flit metadata
  
  [tool.flit.metadata]
  classifiers = [
      ...
      "Programming Language :: Python :: 3.8",
      ...
  ]
  requires-python = ">= 3.8"
  
  # Poetry metadata
  
  [tool.poetry]
  classifiers = [
      ...
      "Programming Language :: Python :: 3.8",
      ...
  ]
  
  [tool.poetry.dependencies]
  python = "^3.8"

• tox.ini：如果存在，它应具有

  [tox]
  envlist = pyXY, ...

  环境名称如 pyXY-ZZZ 也被接受；后缀被忽略。

• .travis.yml：如果存在，它应具有

  python:
    - X.Y
    - ...

  和/或

  matrix:
    include:
      - python: X.Y
        ...
      - ...

  和/或

  jobs:
    include:
      - python: X.Y
        ...
      - ...

  和/或

  env:
    - TOXENV=...

  （但并非所有这些形式都支持更新）

• appveyor.yml：如果存在，它应具有

  environment:
    matrix:
      - PYTHON: C:\\PythonX.Y
      - ...

  环境变量名称假定是 PYTHON（不区分大小写）。值应该是以下之一

  • X.Y

  • C:\\PythonX.Y（不区分大小写）

  • C:\\PythonX.Y-x64（不区分大小写）

  或者，您可以使用 TOXENV 并使用常规值（pyXY）。

  （目前不支持更新 TOXENV。）

• .manylinux-install.sh：如果存在，它应包含类似于以下内容的循环

  for PYBIN in /opt/python/*/bin; do
      if [[ "${PYBIN}" == *"cp27"* ]] || \
         [[ "${PYBIN}" == *"cp35"* ]] || \
         [[ "${PYBIN}" == *"cp36"* ]] || \
         [[ "${PYBIN}" == *"cp37"* ]] || \
         [[ "${PYBIN}" == *"cp38"* ]]; then
          "${PYBIN}/pip" install -e /io/
          "${PYBIN}/pip" wheel /io/ -w wheelhouse/
             rm -rf /io/build /io/*.egg-info
      fi
  done

  check-python-versions 将寻找 $PYBIN 形式的测试

  [[ "${PYBIN}" == *"cpXY"* ]]

  其中 X 和 Y 是任意数字。

  这些脚本用于多个 zopefoundation 存储库，如 zopefoundation/zope.interface。这是最不规范化的格式。

• .github/workflows/*.yml：如果存在，它应具有

  jobs:
    (anything):
      strategy:
        matrix:
          python-version:
            - X.Y
            - ...

  或

  jobs:
    (anything):
      strategy:
        matrix:
          config
            - [ X.Y, "pyXY" ]
            - ...

Python 版本

除了 CPython X.Y 之外，check-python-versions 还会在某些文件中识别 PyPy 和 PyPy3

• setup.py 或 pyproject.toml 可能有一个

  'Programming Language :: Python :: Implementation :: PyPy',

  分类器

• tox.ini 可能具有 pypy[-suffix] 和 pypy3[-suffix] 环境

• .travis.yml 可能具有 pypy 和 pypy3 作业，带有可选版本后缀（例如 pypy2.7-6.0.0，pypy3.5-6.0.0）

• .github/workflows/*.yml：可能具有 pypy/pypy3/pypy-N.M/pypy-N.M-vX.Y.Z 作业。

• appveyor.yml 和 .manylinux-install.sh 通常不包含 pypy 测试，因此 check-python-versions 无法识别它们，这些文件被排除在 PyPy 支持一致性检查之外。

即将发布的 Python 版本（如在 setup.py 中的 3.12 或 .travis.yml 中的 3.12-dev）也会显示出来，但不会导致不匹配错误。

此外，setup.py 中的 python_requires 或 pyproject.toml 中的 requires-python 通常有一个下限，但没有上限。check-python-versions 将假定这意味着支持到其他数据源中提到的最新 Python 3.x 版本，或者当前的 3.x 版本（目前是 3.11），取较低者。这意味着如果你使用 python_requires ‘>= 3.6’ 等类似设置，新 Python 3 版本的发布不会突然导致所有你的 lint 检查失败。

当你在指定 –expect、–add、–drop 或 –update 的 Python 版本范围时，你可以使用以下格式：

• X.Y（例如 --add 3.8）

• X.Y-U.V 用于包含范围（例如 --add 3.5-3.8）

• X.Y-，表示从 X.Y 到 X 系列的最后一个已知发布版本（例如 --add 3.5- 等同于 --add 3.5-3.7）

• -X.Y，等同于 X.0-X.Y（例如 --drop -3.4 等同于 --drop 3.0-3.4）

或者上述格式的逗号分隔列表（例如 --expect 2.7,3.5-，--drop -2.6,-3.4）。

–expect/–add/–drop/–update 目前不允许指定替代实现（例如 pypy）。

pre-commit 集成

使用 pre-commit，check-python-versions 可以成为你的 git-workflow 的一部分。将以下片段添加到你的 .pre-commit-config.yaml。

repos:
-   repo: https://github.com/mgedmin/check-python-versions
    rev: "0.22.0"
    hooks:
    -   id: check-python-versions