如何在pyproject.toml中为OpenCV配置默认依赖与条件可选依赖？

问题背景 #

我开发了一个名为mylib的Python库，它依赖OpenCV。OpenCV提供了opencv-python（带GUI支持）和opencv-python-headless（无GUI，适合服务器环境）两个互斥的发行版——二者都能适配mylib，但无法同时安装。

目前我通过两个可选依赖实现版本选择，但存在语义缺陷：用户不能直接执行pip install mylib，必须明确指定pip install mylib[opencv-python]或pip install mylib[opencv-python-headless]，对新手不友好。

我尝试通过环境标记设置默认依赖，仅在用户未指定额外项时自动安装opencv-python-headless，配置如下：

[project]
dependencies = [
  "opencv-python-headless; 'opencv-gui' not in extras",
]

[project.optional-dependencies]
opencv-gui = ["opencv-python"]

查阅环境标记规范后，注意到extra相关标记的说明，想确认：**这种基于extras的条件依赖功能是否由构建后端决定？**我当前使用hatchling，但愿意更换任何支持该功能的构建后端。

解答 #

是的，这种基于extras的条件依赖支持确实由构建后端决定，不过目前主流的现代构建后端大多已经支持该特性：

1. Hatchling（你当前使用的后端） #

Hatchling完全支持PEP 508中定义的extra环境标记，你的配置是有效的。当用户执行：

• pip install mylib：会自动安装opencv-python-headless
• pip install mylib[opencv-gui]：会安装opencv-python，且由于两个包互斥，pip会自动替换掉opencv-python-headless

不过需要注意：部分旧版本的pip可能对这种条件依赖的处理存在问题，建议在文档中提醒用户使用pip 21.0及以上版本。

2. 其他支持的构建后端 #

如果后续需要更换后端，以下选项也完全支持该特性：

• setuptools：只要使用pyproject.toml配置（而非旧版setup.py），同样支持PEP 508的extra标记
• flit：现代轻量构建后端，原生支持所有PEP 508环境标记
• poetry：虽然poetry的依赖声明语法略有不同，但也能通过条件依赖实现相同逻辑

注意事项 #

• 确保opencv-python和opencv-python-headless在你的pyproject.toml中没有同时被强制依赖，避免pip冲突
• 在库的README中明确说明两种安装方式：默认安装无GUI版本，指定[opencv-gui]额外项安装带GUI版本，引导用户选择

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