setuptools为何未调用site.main()？Qt依赖检测及Wheel优化问询

一、venv环境检测失败的原因与解决 #

你遇到的虚拟环境中检测不到已安装PyQt5的问题，核心原因是setup.py运行时Python的sys.path未包含虚拟环境的site-packages目录。直接运行setup.py时，Python默认不会自动加载虚拟环境的用户站点目录，导致检测逻辑找不到已安装的包。

替代site.main()的更安全写法是手动将虚拟环境的site-packages目录加入sys.path，避免site.main()带来的额外初始化副作用：

# 在setup.py开头添加
import site
# 加入用户站点目录和系统站点目录
site.addsitedir(site.getusersitepackages())
site.addsitedir(site.getsitepackages()[0])

用importlib.util.find_spec替代直接__import__来检测模块，不会执行模块代码，更安全：

import importlib.util

def has_qt_binding(module_name):
    spec = importlib.util.find_spec(module_name)
    return spec is not None

二、优雅的依赖选择逻辑（适配Wheel包） #

Wheel包的依赖是静态写入元数据的，无法动态修改，因此需要分源码安装和Wheel构建/安装两种场景处理：

1. 代码层自动适配任意Qt绑定 #

先在代码中实现Qt绑定的自动加载，彻底解除代码对特定Qt包的依赖：

# 项目根目录下的qt_loader.py
def load_qt_binding():
    # 按优先级排序的Qt绑定列表
    qt_bindings = [
        ("PyQt5", ("PyQt5.QtWidgets", "PyQt5.QtCore", "PyQt5.QtGui")),
        ("PyQt6", ("PyQt6.QtWidgets", "PyQt6.QtCore", "PyQt6.QtGui")),
        ("PySide2", ("PySide2.QtWidgets", "PySide2.QtCore", "PySide2.QtGui")),
        ("PySide6", ("PySide6.QtWidgets", "PySide6.QtCore", "PySide6.QtGui")),
    ]
    
    for binding_name, modules in qt_bindings:
        try:
            # 逐个导入核心模块
            widgets = __import__(modules[0], fromlist=[""], level=0)
            core = __import__(modules[1], fromlist=[""], level=0)
            gui = __import__(modules[2], fromlist=[""], level=0)
            return widgets, core, gui, binding_name
        except ImportError:
            continue
    
    raise ImportError("未检测到任何Qt绑定，请安装PyQt5/PyQt6/PySide2/PySide6中的任意一个")

# 全局导出Qt模块
QtWidgets, QtCore, QtGui, QT_BINDING = load_qt_binding()

之后项目代码直接导入这个文件的模块即可：

from your_package.qt_loader import QtWidgets, QtCore

2. 安装阶段的依赖处理 #

源码安装：动态检测已安装绑定

在setup.py中实现动态检测，优先使用已安装的Qt绑定，否则选择默认项（比如PySide6）：

# setup.py
import sys
import site
import importlib.util
from setuptools import setup

# 修复虚拟环境sys.path问题
site.addsitedir(site.getusersitepackages())
site.addsitedir(site.getsitepackages()[0])

def is_building_wheel():
    # 判断是否正在构建Wheel包
    return "bdist_wheel" in sys.argv or sys.environ.get("BUILD_WHEEL") == "1"

def get_selected_qt_dep():
    # 按优先级检测已安装的Qt绑定
    qt_candidates = ["PyQt5", "PyQt6", "PySide2", "PySide6"]
    for candidate in qt_candidates:
        if has_qt_binding(candidate):
            return candidate
    # 默认选择PySide6
    return "PySide6"

def has_qt_binding(module_name):
    spec = importlib.util.find_spec(module_name)
    return spec is not None

# 构建Wheel时强制使用默认依赖，避免依赖绑定到构建环境
if is_building_wheel():
    qt_dependency = "PySide6"
else:
    qt_dependency = get_selected_qt_dep()

setup(
    name="your-package-name",
    version="0.1.0",
    packages=["your_package"],
    install_requires=[
        qt_dependency,
        # 其他固定依赖
    ],
    extras_require={
        # 提供手动选择依赖的入口
        "pyqt5": ["PyQt5"],
        "pyqt6": ["PyQt6"],
        "pyside2": ["PySide2"],
        "pyside6": ["PySide6"],
    },
)

Wheel安装：静态默认依赖+可选扩展

构建Wheel时，依赖会被固定为默认的PySide6，用户安装后如果想切换其他Qt绑定，只需安装对应扩展依赖即可：

# 安装时指定使用PyQt5
pip install your-package-name[pyqt5]

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