如何将基于setuptools的whl打包工具从a_tool改名为b_tool并兼容旧代码导入

核心目标 #

• 正式安装包名从a_tool变更为b_tool，支持新代码通过from b_tool import a_module正常导入
• 完全兼容旧代码的from a_tool import a_module导入逻辑，不需要用户修改原有业务代码
• 避免重复业务代码、双份对象实例不同步的问题

落地实现步骤 #

• 迁移正式业务代码
  将项目根目录下原有的顶层业务包目录a_tool/直接重命名为b_tool/，包内部的文件结构、代码逻辑不做任何改动，确保本地验证时from b_tool import a_module可以正常运行。
• 搭建零逻辑兼容导入层
  在项目根目录下创建与b_tool/平级的a_tool/目录，作为旧导入的兼容入口，该目录下不存放任何实际业务实现，所有内容全部做转发映射：
  • 编写a_tool/__init__.py，将原a_tool对外公开的内容全部从b_tool导入，示例：

    # 纯转发逻辑，无实际业务代码
    from b_tool import *
    # 显式匹配原a_tool的公开导出项
    from b_tool import a_module, __version__
    

  • 若原a_tool存在嵌套子模块（如a_tool.utils.xxx这类导入路径），在a_tool/下创建对应的子模块文件，每个子模块同样做纯转发，例如a_tool/utils.py内容为：

    from b_tool.utils import *
    

    可以覆盖所有层级的旧导入语法，避免出现路径找不到的问题。
• 调整setuptools打包配置
  修改setup.py中的包名配置，原有包扫描逻辑无需大幅改动：

  setup(
      # 包名从a_tool改为b_tool
      name="b_tool",
      version=__version__,
      # 原有测试目录排除规则完全保留
      # find_packages会自动扫描到根目录下的b_tool/和a_tool/两个标准包，自动纳入打包列表
      packages=find_packages(
          exclude=["*.tests", "*.tests.*", "tests.*", "tests"]
      ),
      # 可选配置：声明与旧版独立a_tool包的冲突，避免pip安装时出现模块路径冲突
      # conflicts = ["a_tool(<对应新版本号>)"]
  )
  

注意事项 #

• 重点：兼容用的a_tool包内禁止编写独立业务逻辑，所有导入必须指向b_tool内的对象，确保a_tool.a_module与b_tool.a_module是同一个Python实例，不会出现状态不同步、重复内存占用的问题。
• 最终生成的whl包发布后，用户仅需安装b_tool即可同时支持新旧两种导入语法，不需要额外安装兼容依赖。
• 可在后续多个b_tool版本中保留该薄兼容层，给旧代码留足迁移时间，待用户普遍完成升级后，再移除兼容包发布后续版本即可。

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