如何实现Python import优先搜索指定路径，解决__init__.py导致的失效问题？

问题背景 #

想要修改Python的import机制，让它优先搜索指定路径的模块，找不到时再回退到原有路径。但传统的sys.path方法在目标包存在__init__.py时失效，具体场景如下：

案例1：无__init__.py时正常工作 #

文件结构：

.
├── a
│   ├── b.py       # content: x='x'
│   └── c.py       # content: y='y'
├── hack
│   └── a
│       └── b.py   # content: x='hacked'
└── test.py

test.py代码：

import sys
sys.path.insert(0, 'hack')

from a.b import x
from a.c import y

print(x, y)

运行结果：hacked y，符合预期。

案例2：原包有__init__.py时失效 #

文件结构：

.
├── a
│   ├── b.py
│   ├── c.py
│   └── __init__.py
├── hack
│   └── a
│       └── b.py
└── test.py

运行相同的test.py，结果是x y，hack路径下的b.py未被加载。

案例3：给hack包加__init__.py后丢失回退能力 #

文件结构：

.
├── a
│   ├── b.py
│   ├── c.py
│   └── __init__.py
├── hack
│   └── a
│       ├── b.py
│       └── __init__.py
└── test.py

运行test.py报错：ModuleNotFoundError: No module named 'a.c'，因为hack路径下没有c.py，且无法回退到原路径查找。

需求：让案例2场景正常工作，且仅在test.py顶部添加少量代码，不修改原有仓库代码，同时支持被导入模块内部的import语句也能应用该规则。

解决方案 #

使用Python的元路径查找器（MetaPath Finder） 自定义导入逻辑，优先在指定的hack路径查找模块，找不到时交给默认导入机制处理。

修改后的test.py代码 #

import sys
import importlib.abc
import importlib.util
from pathlib import Path

class HackPathFinder(importlib.abc.MetaPathFinder):
    def __init__(self, hack_dir):
        self.hack_dir = Path(hack_dir).resolve()

    def find_spec(self, fullname, path, target=None):
        # 将模块名转换为hack目录下的路径，比如a.b -> hack/a/b.py
        module_parts = fullname.split('.')
        module_path = self.hack_dir.joinpath(*module_parts)
        
        # 检查是否是单个模块文件
        py_file = module_path.with_suffix('.py')
        if py_file.exists():
            return importlib.util.spec_from_file_location(fullname, py_file)
        
        # 检查是否是包含__init__.py的包
        init_file = module_path.joinpath('__init__.py')
        if init_file.exists():
            return importlib.util.spec_from_file_location(
                fullname, init_file,
                submodule_search_locations=[str(module_path)]
            )
        
        # 找不到就返回None，让后续默认查找器处理
        return None

# 把自定义查找器插入到元路径最前面，确保优先执行
sys.meta_path.insert(0, HackPathFinder('hack'))

# 原有导入代码完全不变
from a.b import x
from a.c import y

print(x, y)

运行结果 #

在案例2的文件结构下运行，会输出hacked y，既优先加载了hack路径下的b.py，又能正常从原路径加载c.py，完全符合需求。

原理说明 #

Python的导入流程会依次调用sys.meta_path列表中的查找器：

1. 我们将自定义的HackPathFinder插入到列表最前面，确保它最先被执行。
2. 当导入模块时，查找器会先尝试在hack目录下定位对应的模块文件或包。
3. 如果找到，就返回该模块的spec（规格对象），Python会用这个spec加载模块；如果找不到，返回None，流程会自动交给后面的默认查找器，也就是原有的导入机制，这样就保留了回退能力。
4. 该逻辑对模块内部的import语句同样生效，因为所有导入请求都会经过元路径查找器。

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