如何为使用lazy imports的Python包创建根别名并完成版本过渡？

核心实现思路 #

要实现oldpkg和newpkg完全可互换（模块对象一致、子模块导入等价、CLI命令兼容），核心是利用Python的sys.modules模块注册表，让两个包名指向同一个模块对象，同时通过动态映射处理子模块的导入请求。

1. 模块对象统一 #

直接修改sys.modules，让新/旧包名指向同一模块实例，确保import oldpkg, newpkg; oldpkg is newpkg为True。

2. 子模块映射兼容 #

通过模块级__getattr__方法，将新包的子模块导入请求转发到旧包（或反之），并在sys.modules中注册映射，保证后续导入复用同一子模块对象。

3. CLI命令兼容 #

为别名包添加__main__.py，将命令行执行逻辑转发到目标包的__main__.py。

分阶段过渡步骤 #

对应你规划的5个迁移阶段，具体实现如下：

阶段1：newpkg作为oldpkg的指针 #

1. 创建newpkg目录，结构与oldpkg匹配：

   └── newpkg
       ├── __init__.py
       └── __main__.py
   

2. newpkg/init.py 内容：

   import sys
   
   # 让newpkg模块与oldpkg完全一致
   import oldpkg
   sys.modules['newpkg'] = sys.modules['oldpkg']
   
   # 动态映射子模块
   def __getattr__(name):
       old_submod = f'oldpkg.{name}'
       try:
           __import__(old_submod)
       except ImportError:
           raise AttributeError(f"module 'newpkg' has no attribute '{name}'")
       # 注册子模块映射，避免重复处理
       submod = sys.modules[old_submod]
       sys.modules[f'newpkg.{name}'] = submod
       return submod
   

3. newpkg/main.py 内容：

   from oldpkg.__main__ import main
   
   if __name__ == '__main__':
       main()
   

4. setup.py 中添加newpkg到packages列表：

   setup(
       # ... 其他配置
       packages=['oldpkg', 'newpkg'],
       # ...
   )
   

此时所有newpkg的导入和CLI调用都会完全等价于oldpkg。

阶段2：迁移内容到newpkg，oldpkg转为指针 #

1. 将oldpkg目录下的所有文件（子模块、子包、__init__.py、__main__.py）移动到newpkg目录。
2. 修改oldpkg/init.py，反向指向newpkg：

   import sys
   
   import newpkg
   sys.modules['oldpkg'] = sys.modules['newpkg']
   
   def __getattr__(name):
       new_submod = f'newpkg.{name}'
       try:
           __import__(new_submod)
       except ImportError:
           raise AttributeError(f"module 'oldpkg' has no attribute '{name}'")
       submod = sys.modules[new_submod]
       sys.modules[f'oldpkg.{name}'] = submod
       return submod
   

3. 修改oldpkg/main.py：

   from newpkg.__main__ import main
   
   if __name__ == '__main__':
       main()
   

此时代码逻辑完全迁移到newpkg，oldpkg仅作为别名存在。

阶段3：oldpkg添加弃用警告 #

在oldpkg/__init__.py开头添加警告：

import warnings

warnings.warn(
    "oldpkg已废弃，请使用newpkg替代",
    DeprecationWarning,
    stacklevel=2  # 确保警告指向用户的导入代码
)

# ... 保留阶段2的模块映射代码

用户导入oldpkg时会收到提示，但功能不受影响。

阶段4：oldpkg导入时抛出错误 #

将警告改为强制报错，引导用户彻底切换：

raise ImportError(
    "oldpkg已停止使用，请卸载oldpkg并安装使用newpkg"
)

此时导入oldpkg会直接触发错误，阻断旧代码的使用。

阶段5：移除oldpkg #

• 删除oldpkg目录
• 在setup.py中移除oldpkg的packages声明
• 发布新版本，完成彻底迁移

实践案例 #

• scikit-learn：早期同时支持sklearn和scikit_learn包名，通过模块别名过渡，最终统一为sklearn，旧包名导入会触发弃用警告。
• pytest：历史上支持py.test命令和pytest模块，通过命令行别名和模块转发实现过渡，现在仅保留pytest作为标准入口。
• Flask生态：部分扩展如Flask-Mail曾重命名为Flask-Mailman，通过旧包转发到新包的方式，给用户足够的迁移缓冲期。

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