Python .egg 库转换为 .whl 的操作指南（Glue Python Shell 3.9 适用）

内容性质：操作方法（howto）。两种方式均经实测验证。可直接指导客户。

概述

Glue Python Shell 升级到 Python 3.9 后不再支持 .egg 格式的库（egg 不会被安装进运行环境，作业不报错但 import 时抛 ModuleNotFoundError）。所有 .egg 都必须转换为 .whl。本文给出两种转换方式及选择依据。

其他仍在使用 egg 的场景（老 setuptools 项目迁移）同样适用。

先判断：纯 Python 还是含 C 扩展

unzip -l xxx.egg | grep '\.so'

• 无输出 = 纯 Python 包 → 方式一、方式二均可；
• 有 .so = 含 C 扩展 → 只能用方式一从源码在目标 Python 版本环境重新编译（直接转换的包 ABI 不匹配，装上也用不了）。

方式一（推荐）：从源码重新打包

前提：有该包的源代码（含 setup.py 的目录）+ 与目标运行时一致的 Python 环境（Glue Python Shell 3.9 对应 Python 3.9、x86_64；建议 Amazon Linux 2 或 manylinux2014 容器）。

1. 进入含 setup.py 的源码目录。

2. 检查 install_requires 依赖声明（纯内网环境重点）：

   • 凡运行时已预装且满足的依赖（Glue analytics 库集的 boto3、botocore、six 等），从声明中删除——否则 --extra-py-files 逐包安装该 wheel 时 pip 会为这些依赖联网，内网必失败；
   • 运行时未预装的依赖，需一并打成 wheel 随包提供。

3. 打包：

   python setup.py bdist_wheel
   

4. 产物在 dist/ 下：

   • 纯 Python → xxx-py3-none-any.whl（通用标签，任意平台可装）；
   • 含 C 扩展 → 带 cp39 及平台标签（必须在 Python 3.9 环境编译才与 Glue 3.9 匹配）。

方式二（无源码应急）：wheel convert 直接转换

仅适用于纯 Python egg。实测转换产物可正常 pip install 并 import：

pip install wheel
wheel convert xxx-0.2.1-py3.6.egg
# 当前目录产出 xxx-0.2.1-py39-none-any.whl（标签取决于执行环境的 Python 版本）

注意：wheel convert 只是格式转换，不会处理依赖声明——若原 egg 的 metadata 声明了外部依赖且目标环境纯内网，仍需按方式一第 2 步的思路处理（或确认依赖已被运行时预装满足）。

转换后的使用（Glue Python Shell）

1. .whl 上传 S3；
2. 加入作业的 Python library path（--extra-py-files），多个路径用英文逗号分隔；
3. Python version 设为 3.9，保存运行；
4. 验证：日志出现 Successfully installed xxx，且代码 import 正常。

常见坑

• "作业成功但 import 失败"：egg 在 3.9 下被静默忽略（日志有 Egg file installation is not supported anymore，但为 INFO 级不中断作业），别被作业 SUCCEEDED 迷惑。
• 转换环境的 Python 版本要与目标一致：cp39 产物必须出自 Python 3.9 环境。
• manylinux 基线：含 C 扩展时编译环境 glibc 不能高于目标运行时（Glue Python Shell 3.9 = glibc 2.26，建议 manylinux2014 基线），详见相关 KB。

参考

• Python shell 作业提供自有库：https://docs.amazonaws.cn/glue/latest/dg/add-job-python.html
• wheel 工具文档（convert 命令）：https://wheel.readthedocs.io/en/stable/reference/wheel_convert.html
• 相关 KB：《Glue Python Shell 从 Python 3.6 迁移到 3.9：库依赖不兼容的排查与处理》《确定 Glue Python Shell 真实运行时并离线打包 wheel》《Glue Python Shell 纯内网环境离线安装 Python 库的机制与实践》