基于Python Import Hook解决QuantConnect用户库本地导入问题

实现逻辑 #

• 仅当检测到指定环境变量存在时启用导入钩子，完全不影响QC线上运行逻辑
• 自动拦截导入请求，为一级库名追加一层同名子目录前缀
• 无需修改原有符合QC规则的导入语句，本地与线上行为完全一致

完整实现代码 #

import sys
import os
import importlib.util

# 配置项：修改为你自己的所有自定义库名称
LIBRARY_NAMES = {"Utilities"}
# 触发导入钩子的环境变量名
TRIGGER_ENV = "QC_LOCAL_MODE"

# 仅本地环境设置了对应环境变量时才启用钩子
if os.getenv(TRIGGER_ENV) is not None:
    # 本地环境将Library目录加入导入搜索路径
    PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
    sys.path.insert(0, os.path.join(PROJECT_ROOT, "Library"))

    class QCLocalImportFinder:
        def find_spec(self, fullname, path, target=None):
            parts = fullname.split(".")
            if not parts:
                return None
            root_lib = parts[0]
            # 只处理配置过的库、且未添加过同名二级前缀的导入请求
            if root_lib not in LIBRARY_NAMES or (len(parts) >= 2 and parts[1] == root_lib):
                return None
            # 构造重定向后的模块路径
            redirected_name = f"{root_lib}.{root_lib}.{'.'.join(parts[1:])}" if len(parts) > 1 else f"{root_lib}.{root_lib}"
            try:
                spec = importlib.util.find_spec(redirected_name, path)
                if spec:
                    # 保持原模块名不变，避免后续导入冲突
                    spec.name = fullname
                    return spec
            except ModuleNotFoundError:
                pass
            return None
    
    # 将自定义导入查找器加入最优先位置
    sys.meta_path.insert(0, QCLocalImportFinder())

使用方法 #

1. 将上述代码粘贴到项目main.py文件的最开头，位于所有其他导入语句之前
2. 修改LIBRARY_NAMES集合，填入你所有自定义库的名称
3. 本地开发时设置环境变量QC_LOCAL_MODE=1即可生效，QC线上环境无该变量时钩子自动不加载

效果验证 #

• 本地环境：from Utilities.Whatever import *会自动定位到Library/Utilities/Utilities/Whatever.py，导入正常
• QC线上环境：原有导入逻辑完全不变，兼容QC平台的导入规则

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