创建新名称Python包时保留旧包导入兼容性的解决方案问询

以下方案均可同时兼容import A的旧调用和import B的新调用，按需选择即可：

方案1：双包目录同步方案 #

这是最稳妥、兼容性最高的实现方式，不需要依赖Python导入机制的特殊逻辑。

• 调整项目目录结构，同时保留A、B两个根包目录，两份代码完全一致：

├── A
│   └── __init__.py
├── B
│   └── __init__.py
└── pyproject.toml / setup.py

• 在打包配置的packages字段中同时声明A和B两个包，安装B包时两个根包会同时被写入Python的site-packages目录，两种导入方式都可以正常命中。
• 优势：实现简单无黑盒逻辑，适配所有Python版本，不会出现导入顺序、深层导入异常问题。
• 维护优化：可以通过构建脚本自动同步A、B目录的代码，或者给两个目录做软连接，避免手动维护两份代码出现不一致。

方案2：导入重定向方案 #

不需要维护两份代码，通过Python的模块缓存机制实现别名映射，适合包结构复杂的场景。

• 项目只保留B包的代码，目录结构如下：

├── B
│   └── __init__.py
├── A.py
└── pyproject.toml / setup.py

• 新增顶层A.py文件，内容如下：

import sys
# 把B包的模块实例直接挂载为A的模块实例
from B import *
sys.modules["A"] = sys.modules["B"]
# 如果有子模块需要兼容，按同样规则批量注册即可
# sys.modules["A.xxx"] = sys.modules["B.xxx"]

• B包的__init__.py按正常逻辑实现module()方法即可。
• 优势：全程只需要维护一份B包的代码，没有冗余内容，迭代成本低。
• 注意点：如果原A包存在多层子模块导入，需要把所有子模块的别名都提前注册到sys.modules中，避免深层导入报错。

方案3：旧包废弃迁移方案 #

如果后续计划完全下线A包，可以搭配以上方案同步推进迁移：

• 给旧的A包发布一个最终版本，代码只做重定向和废弃提醒：

import warnings
warnings.warn("A包已停止维护，后续请直接安装使用B包", DeprecationWarning, stacklevel=2)
from B import *
import sys
sys.modules["A"] = sys.modules["B"]

• 在A包的PyPI描述页说明迁移规则，引导存量用户逐步切换到B包。

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