构建Python扩展模块Wheel时如何使用预编译共享库？

核心方案：直接复用预编译库，无需重新编译 #

不需要子类化Extension类，setuptools本身提供了现成的配置方式，核心是让构建流程跳过源码编译，直接将外部编译好的SO/DLL（符合稳定受限ABI）作为扩展模块打包，并正确关联到Python的导入路径。

具体配置步骤 #

1. 定义Extension时关联预编译库 #

在setup.py中，给Extension对象设置空的sources（因为不需要编译源码），通过extra_objects传入预编译库的路径，同时开启受限ABI支持：

from setuptools import setup, Extension

setup(
    name="your_extension",
    version="0.1.0",
    ext_modules=[
        Extension(
            name="your_extension.core",  # Python中实际导入的模块名
            sources=[],  # 无源码需要编译，留空
            extra_objects=["path/to/prebuilt/libyourlib.so"],  # 替换为你的预编译库路径
            define_macros=[("Py_LIMITED_API", "0x03080000")],  # 对应Python 3.8+的受限ABI版本
            py_limited_api=True,  # 启用受限ABI，生成跨版本兼容的abi3 Wheel
        )
    ],
    packages=["your_extension"],  # 声明你的Python包
)

2. 确保预编译库被正确打包 #

如果预编译库不在Python包的目录下，需要通过package_data指定要包含的文件，让setuptools把它打包进Wheel：

setup(
    # ... 其他配置 ...
    package_data={
        "your_extension": ["*.so", "*.dll"],  # 匹配包内的预编译库文件
    },
    include_package_data=True,
)

如果库在独立目录，也可以用data_files指定安装后的路径：

setup(
    # ... 其他配置 ...
    data_files=[
        ("lib/python3.8/site-packages/your_extension", ["path/to/prebuilt/libyourlib.so"])
    ],
)

3. 构建并验证兼容Wheel #

运行python setup.py bdist_wheel构建Wheel。对于Linux/macOS/Windows，可以分别用auditwheel/delocate-wheel/delvewheel处理库依赖，确保Wheel能在目标环境正常运行。因为启用了py_limited_api=True，会生成带abi3后缀的Wheel，兼容多个Python 3.x版本。

关于子类化Extension的疑问 #

完全没必要子类化Extension类，上述配置已经能满足需求。如果需要自定义构建逻辑（比如动态选择预编译库版本），可以重写build_ext命令来跳过编译步骤，直接复制预编译库：

from setuptools.command.build_ext import build_ext
import shutil
import os

class CustomBuildExt(build_ext):
    def build_extension(self, ext):
        # 跳过编译流程，直接复制预编译库到扩展输出目录
        dest_path = self.get_ext_fullpath(ext.name)
        os.makedirs(os.path.dirname(dest_path), exist_ok=True)
        shutil.copy("path/to/prebuilt/libyourlib.so", dest_path)

setup(
    # ... 其他配置 ...
    cmdclass={"build_ext": CustomBuildExt},
)

这种方式仅适合有特殊自定义需求的场景，常规情况用extra_objects更简洁。

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