如何在不修改客户端代码的情况下支持Python包多版本共存？

问题根因 #

你之前的写法不生效是因为Python的子模块导入逻辑和父模块__init__.py的导入属性是独立的：

• 在lib/__init__.py里执行from .v1 import foo，只是将foo模块设置为lib模块的一个属性，支持import lib; lib.foo.f()这种调用方式
• 当执行from lib.foo import f时，Python会直接到lib包对应的文件系统目录下查找是否存在foo.py文件或者foo子目录，你的lib根目录下没有对应的文件，所以会抛出ImportError

解决方案 #

只需要修改lib/__init__.py，通过修改Python包的特殊属性__path__实现全局重定向即可，不需要为每个子模块单独创建代理文件。__path__是Python包的内置属性，用来指定导入子模块时的文件查找路径，我们只需要根据版本将该路径指向对应的v1/v2目录即可：

import os
from pathlib import Path

# 读取版本配置，也可以替换为其他运行时检查逻辑
use_v2 = os.environ.get("USE_V2", "0") == "1"
target_version = "v2" if use_v2 else "v1"

# 构造目标版本的绝对路径
lib_root = Path(__file__).parent
target_dir = str(lib_root / target_version)

# 替换当前lib包的查找路径为目标版本目录
__path__ = [target_dir]

该方案支持所有嵌套层级的子模块导入，不管是lib.foo还是深层的lib.bar.baz都会自动到对应版本目录下查找，完全不需要修改客户端代码。

扩展说明 #

如果需要支持运行时动态切换版本，可以在上述代码基础上增加切换方法：

import sys
from pathlib import Path

def switch_version(version: str) -> None:
    global __path__
    if version not in ("v1", "v2"):
        raise ValueError("仅支持v1、v2两个版本")
    # 更新包查找路径
    lib_root = Path(__file__).parent
    __path__ = [str(lib_root / version)]
    # 清空已导入的子模块缓存，确保后续导入使用新版本
    for mod_name in list(sys.modules.keys()):
        if mod_name.startswith("lib."):
            del sys.modules[mod_name]

用户可以在代码中显式调用lib.switch_version("v2")来切换版本，切换后再导入的子模块就会使用新版本的实现。

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