Python包依赖版本选择最佳实践及批量配置宽版本方法咨询

一、依赖版本选择的最佳实践 #

• 声明兼容的版本范围，而非固定版本：优先使用numpy>=1.20,<1.22这类范围约束，既保证包能在经过测试的稳定版本上运行，又给依赖解析工具留足空间，避免和其他包的硬版本锁定冲突。除非某个版本有不可替代的特性或必须修复的bug，否则不要用==x.x.x硬锁定。
• 区分生产与开发依赖：将运行必需的生产依赖和测试、lint、构建等开发依赖分开管理。比如用pyproject.toml的[project.dependencies]存生产依赖，[project.group.dev-dependencies]存开发依赖；或者用requirements.txt和requirements-dev.txt分开。
• 定期验证兼容性：通过CI工具在多个Python版本、依赖版本组合下运行测试，确保包在声明的版本范围内能正常工作，避免因依赖版本更新引入隐性问题。
• 避免过度放宽范围：不要写numpy>=1.0这种无限制的范围，老版本可能存在API变更或安全漏洞。要基于实际测试的兼容区间来设置范围，比如只兼容近2-3个小版本。
• 使用标准化依赖文件：优先采用pyproject.toml（符合PEP 621标准）管理依赖，它比传统requirements.txt更规范，支持版本范围、依赖分组、可选依赖等特性，也更适配现代包管理工具（poetry、pip-tools等）。

二、批量设置宽版本范围的可行方法 #

1. 利用pip-tools结合约束文件 #

• 先创建requirements.in文件，只列出包名（不带版本）：

  numpy
  pandas
  requests
  

• 编写constraints.txt，批量定义每个包的版本范围：

  numpy>=1.20,<1.22
  pandas>=1.3,<1.5
  requests>=2.25,<2.30
  

• 执行pip-compile命令生成带范围约束的依赖文件：

  pip-compile requirements.in --constraint constraints.txt --output-file requirements-wide.txt
  

2. 借助poetry批量编辑依赖 #

• 如果已经用poetry初始化项目，直接编辑pyproject.toml的[project.dependencies]部分，用编辑器的正则替换功能批量修改版本：比如把numpy = "==1.21.5"替换为numpy = ">=1.21,<1.22"。
• 也可以写简单的shell脚本遍历依赖，用poetry add命令批量更新版本范围：

  # 示例：遍历指定包列表，设置小版本兼容范围
  for pkg in numpy pandas requests; do
      # 获取当前安装的版本号
      ver=$(poetry show $pkg | grep Version | awk '{print $2}')
      # 拆分版本号，生成 >=major.minor.0,<major.(minor+1).0
      major=$(echo $ver | cut -d. -f1)
      minor=$(echo $ver | cut -d. -f2)
      poetry add "$pkg@>=${major}.${minor}.0,<${major}.$((minor+1)).0" --upgrade
  done
  

3. 自定义Python脚本转换固定版本 #

如果现有requirements.txt是用pip freeze生成的固定版本，可以写脚本批量转换为宽范围：

import re

def convert_to_wide_range(line):
    line = line.strip()
    if not line or line.startswith('#'):
        return line
    # 匹配固定版本格式：pkg==x.y.z
    match = re.match(r'^(.*)==(\d+)\.(\d+)\.(\d+)$', line)
    if match:
        pkg, major, minor, _ = match.groups()
        # 生成 >=major.minor.0, <major.(minor+1).0 的范围
        return f"{pkg}>={major}.{minor}.0,<{major}.{int(minor)+1}.0"
    # 处理其他格式（如带 extras 的包）
    return line

# 读取原文件，转换后写入新文件
with open('requirements.txt', 'r') as infile, open('requirements-wide.txt', 'w') as outfile:
    for line in infile:
        outfile.write(convert_to_wide_range(line) + '\n')

可以根据需求修改脚本中的版本范围规则，比如改为大版本兼容（>=1.20,<2.0）。

内容的提问来源于stack exchange，提问作者rpicatoste