Python单文件实现模拟模块查找兼容层的方法

不需要写全套自定义SourceLoader，用标准导入机制的几个轻量扩展点就能实现，全程只需要一个compat.py文件，不用给两个版本包的任何子模块建对应兼容文件。

核心思路 #

Python的导入系统本身留了足够的扩展点，不需要魔改内部逻辑就能实现转发：

• 用Python 3.7+原生支持的模块级__getattr__，处理顶层属性访问、from compat import xxx这类导入请求，直接转发到当前激活的后端版本包
• 给compat模块设置空的__path__，让Python把单文件的compat识别为包，触发子模块导入的查找流程
• 注册一个极简的元路径Finder，拦截所有compat.xxx开头的子模块导入请求，直接返回对应后端版本的真实子模块，不需要在本地创建任何子模块文件

完整实现代码 #

把下面的代码全部放到compat.py文件里即可：

import sys
import importlib
from importlib.abc import MetaPathFinder, Loader
from importlib.util import spec_from_loader

# 后端切换配置：可改成读环境变量、读配置文件、甚至自动检测已安装的包版本
ACTIVE_BACKEND = "version1"

def _load_backend(submodule_path=None):
    """加载当前激活后端对应的真实模块"""
    target = ACTIVE_BACKEND
    if submodule_path:
        target = f"{ACTIVE_BACKEND}.{submodule_path}"
    return importlib.import_module(target)

# 处理compat顶层的属性访问：from compat import Foo、compat.Qux 都会走这里
def __getattr__(name):
    root_backend = _load_backend()
    return getattr(root_backend, name)

# 空__path__标记当前模块为包，触发子模块查找逻辑
__path__ = []

# 拦截compat下所有子模块的导入请求
class _CompatFinder(MetaPathFinder, Loader):
    @classmethod
    def find_spec(cls, fullname, path=None, target=None):
        if not fullname.startswith("compat."):
            return None
        # 提取子模块路径，比如compat.baz.Bar 对应子路径baz.Bar
        sub_path = fullname.split(".", 1)[1]
        # 校验后端对应子模块存在
        try:
            _load_backend(sub_path)
        except ImportError:
            return None
        return spec_from_loader(fullname, cls)

    @classmethod
    def create_module(cls, spec):
        # 直接返回后端真实子模块，不创建新的模块对象
        sub_path = spec.name.split(".", 1)[1]
        return _load_backend(sub_path)

    @classmethod
    def exec_module(cls, module):
        # 模块就是原包的真实模块，不需要额外执行逻辑
        pass

# 注册查找器到导入系统
if not any(isinstance(f, type) and issubclass(f, _CompatFinder) for f in sys.meta_path):
    sys.meta_path.insert(0, _CompatFinder)

使用效果 #

切换ACTIVE_BACKEND的值，下面的导入代码不需要做任何修改，就会自动指向对应版本的包：

import compat
from compat import Foo
from compat.baz import Bar
print(compat.Qux)

# 验证指向正确
import version1
print(Foo is version1.Foo)  # 配置为version1时输出True
print(Bar is version1.baz.Bar)  # 配置为version1时输出True

方案特点 #

• 零额外文件：不管原包有多少层嵌套子模块，都不需要创建对应的兼容模块文件，全部自动转发
• 兼容性好：所有返回的对象都是原包的真实对象，不存在包装类带来的类型判断、C扩展兼容问题
• 性能损耗可忽略：只有第一次导入时走转发逻辑，导入完成后和直接导入原包没有区别
• 扩展方便：要加动态切换逻辑、多版本灰度逻辑，只需要修改_load_backend函数的判断规则即可

注意事项 #

• 方案依赖Python 3.7+的模块级__getattr__特性，如果需要支持3.6及更早版本，需要手动给compat模块对象替换__class__来挂__getattr__，目前绝大多数生产环境已经满足版本要求
• 如果需要运行时动态切换后端，记得清理sys.modules中已经缓存的compat相关模块，否则会拿到之前加载的旧版本对象
• 不要给compat模块手动导入任何子模块，所有子模块都交给注册的Finder自动处理

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