Python模块重命名后保持向后兼容的最佳实践及实现方案

要实现新旧模块名同时可用且指向同一底层代码，以下是经过验证的实用方案：

1. 创建旧模块名的转发入口 #

单文件模块场景 #

如果原模块是单个.py文件（如oldname.py），直接创建同名文件并将所有导入指向新模块：

# oldname.py
import warnings
# 提示用户迁移到新模块
warnings.warn(
    "模块oldname已弃用，请使用newname替代",
    DeprecationWarning,
    stacklevel=2
)

# 导入新模块的所有内容，确保调用oldname.foo等价于newname.foo
from newname import *
from newname import __all__
# 保持包结构一致性
__package__ = "newname"

包（目录）场景 #

如果原模块是包（oldname/目录），在其__init__.py中做转发，同时处理子模块映射：

# oldname/__init__.py
import sys
import warnings
import newname

warnings.warn(
    "包oldname已弃用，请使用newname替代",
    DeprecationWarning,
    stacklevel=2
)

# 将旧包及其子模块映射到新包，确保导入oldname.submodule正常工作
sys.modules['oldname'] = newname
sys.modules['oldname.submodule1'] = newname.submodule1
sys.modules['oldname.submodule2'] = newname.submodule2

# 导出新包的所有内容
from newname import *

2. 利用sys.modules直接映射模块别名 #

在新模块的__init__.py中添加映射，让旧模块名直接指向新模块对象：

# newname/__init__.py
import sys

# 当用户import oldname时，实际获取的是newname模块
sys.modules['oldname'] = sys.modules[__name__]

# 原模块的业务代码...
def foo():
    print("hello from newname")

这种方式无需单独维护旧模块文件，直接在新模块中完成别名映射，适合简单的重命名场景。

3. 关键细节注意事项 #

• 元数据同步：确保新旧模块的__version__、__author__等元数据一致，直接从新模块导入避免重复定义。
• 相对导入处理：如果旧模块中有相对导入，需修改为指向新模块的绝对导入，避免导入错误。
• 全面测试：覆盖所有导入场景：import oldname、from oldname import foo、import oldname.submodule等，验证所有功能正常。
• 文档说明：在项目README或文档中明确告知用户模块重命名的情况，给出迁移步骤，帮助用户逐步切换到新模块名。

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