如何将生成的OpenAPI客户端安装到zipapp并解决模块找不到问题？

问题背景 #

使用openapi-generator生成OpenAPI客户端后，按以下步骤将其安装到app目录并打包为zipapp：

1. 安装客户端到app目录：

OUT_ABSOLUTE="<path to generated openapi client>"
APP="${PWD}/app"

sudo chown -R "${USER}" "${OUT_ABSOLUTE}"

pip install -t "${APP}" "${OUT_ABSOLUTE}" --upgrade

安装日志显示pydantic-core和openapi-client等依赖安装成功。

2. 打包并运行zipapp：

python -m zipapp app -o my_app.pyz
chmod +x my_app.pyz

python my_app.pyz

运行时出现报错：

Traceback (most recent call last):
  # ... 省略中间栈信息
  File "/home/user1291/code/my_app/my_app.pyz/pydantic_core/__init__.py", line 6, in <module>
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'

注：app目录中确实存在pydantic_core._pydantic_core相关文件。

问题原因 #

pydantic_core包含C语言编写的二进制扩展模块（如.so文件），Python原生zipapp机制无法直接从压缩包中加载这类二进制模块——即使文件存在于zip包内，Python的import系统也无法识别并加载它们。

解决方案 #

方案1：运行时自动提取二进制模块到临时目录 #

修改app/__main__.py，在开头添加代码自动提取zip包中的pydantic_core二进制文件到临时目录，并将该目录加入Python的搜索路径：

import os
import sys
import tempfile
from pathlib import Path
import zipfile

def extract_pydantic_core():
    # 检测是否在zipapp环境中运行
    if not isinstance(sys.executable, str) or '.pyz' not in sys.executable:
        return

    zip_path = Path(sys.executable)
    temp_dir = tempfile.mkdtemp(prefix="pydantic_core_")
    
    # 从zip包中提取所有pydantic_core的二进制文件
    with zipfile.ZipFile(zip_path, 'r') as zf:
        for file_name in zf.namelist():
            if file_name.startswith('pydantic_core/') and file_name.endswith(('.so', '.pyd')):
                dest_file = Path(temp_dir) / file_name
                dest_file.parent.mkdir(parents=True, exist_ok=True)
                with open(dest_file, 'wb') as f:
                    f.write(zf.read(file_name))
    
    # 将临时目录加入sys.path，确保import能找到
    sys.path.insert(0, temp_dir)

# 先执行提取操作
extract_pydantic_core()

# 导入并启动应用
import my_app
if __name__ == "__main__":
    my_app.main()

方案2：将二进制模块放在zipapp外部，通过PYTHONPATH加载 #

1. 单独将pydantic-core安装到外部目录：

mkdir app_externals
pip install pydantic-core -t app_externals --upgrade

2. 清理app目录中的pydantic_core相关文件：

rm -rf app/pydantic_core app/pydantic_core-*.dist-info

3. 打包zipapp：

python -m zipapp app -o my_app.pyz

4. 运行时指定外部依赖路径：

PYTHONPATH=./app_externals python my_app.pyz

方案3：使用支持二进制扩展的打包工具替代zipapp #

改用shiv或pex这类专门处理包含C扩展的Python应用打包工具，它们会自动处理二进制模块的加载逻辑：

使用shiv的示例：

# 安装shiv
pip install shiv
# 打包应用（自动包含所有依赖）
shiv -o my_app.pyz -c __main__ app/
# 直接运行打包后的文件
./my_app.pyz

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