JoinQuant 回测中如何导入研究环境的自定义 .py 文件？

在 JoinQuant 聚宽平台中，您可以将自定义的 .py 文件放在研究环境的根目录下，然后在回测或模拟交易策略中直接通过 import 语句导入使用。

以下是具体的操作步骤和代码示例：

1. 创建工具库文件

首先，在研究环境根目录（即一进入“研究”看到的目录，不要放在子文件夹中）创建一个 .py 文件，例如命名为 my_utils.py。

注意：

• 如果文件中包含中文注释或字符串，必须在第一行添加编码声明 # -*- coding: utf-8 -*-。
• 如果在工具库中需要使用聚宽的 API（如 get_price, log.info 等），需要导入 kuanke.user_space_api。

my_utils.py 文件内容示例：

# -*- coding: utf-8 -*-

# 如果需要使用聚宽的API（如history, get_price等），必须引入此模块
from kuanke.user_space_api import *

def get_avg_price(security, days):
    """
    计算指定标的过去N天的收盘均价
    """
    # 调用聚宽API获取数据
    h = attribute_history(security, days, '1d', ['close'])
    avg = h['close'].mean()
    
    # 打印日志（可在回测日志中看到）
    log.info("计算 %s 过去 %d 天均价为: %.2f" % (security, days, avg))
    
    return avg

class MyStrategyHelper:
    """
    自定义辅助类
    """
    def __init__(self):
        self.name = "Helper v1.0"
        
    def check_signal(self, price, ma):
        return price > ma

2. 在回测策略中导入

在您的策略代码中，直接使用 import 语句导入即可。

策略代码示例：

# -*- coding: utf-8 -*-
from jqdata import *

# 导入自定义库
# 方式1：直接导入所有函数
from my_utils import * 
# 方式2：导入模块
# import my_utils 

def initialize(context):
    set_benchmark('000300.XSHG')
    set_option('use_real_price', True)
    
    # 初始化自定义类（来自 my_utils.py）
    g.helper = MyStrategyHelper()
    log.info("加载辅助工具: " + g.helper.name)
    
    run_daily(market_open, time='every_bar')

def market_open(context):
    security = '000001.XSHE'
    
    # 调用自定义库中的函数
    # 注意：get_avg_price 内部调用了 attribute_history，这在回测中是有效的
    ma5 = get_avg_price(security, 5)
    
    current_data = get_current_data()
    current_price = current_data[security].last_price
    
    # 使用自定义类的方法判断逻辑
    if g.helper.check_signal(current_price, ma5):
        log.info("价格高于均价，满足条件")

3. 注意事项

1. 目录限制：目前只能 import 研究根目录下的 .py 文件。不支持导入子目录下的文件（例如，如果文件在 research/lib/mylib.py，则无法通过 import lib.mylib 导入）。
2. API 权限：在自定义库中使用聚宽数据或交易 API 时，务必添加 from kuanke.user_space_api import *，否则会报错 NameError。
3. 文件名冲突：自定义的文件名不要与 Python 标准库或聚宽常用库重名（如不要命名为 pandas.py, math.py, jqdata.py 等），否则会导致系统库无法加载。
4. 缓存问题：如果您修改了研究目录下的 .py 文件，回测通常会自动加载最新代码。但在某些极端情况下（如模拟交易运行中），可能需要重启进程或重新编译策略才能生效。

Q&A

Q: 为什么我在自定义文件中使用 log.info 报错了？
A: 请检查自定义文件的头部是否包含了 from kuanke.user_space_api import *。聚宽的内置对象（如 log, g, context 以及数据获取函数）在外部文件中默认是不可见的，必须通过该模块引入。

Q: 我可以将多个 .py 文件放在一个文件夹里作为包（Package）导入吗？
A: 不支持。聚宽回测环境目前仅支持导入研究根目录下的单文件模块，不支持通过 __init__.py 构建的子文件夹包结构。建议将逻辑合并到根目录的几个文件中。

Q: 修改了 my_utils.py 后，需要重启回测吗？
A: 是的。Python 的机制决定了模块一旦被导入，再次 import 不会重新加载代码。在回测界面，您需要点击“编译运行”或“运行回测”来重新启动进程，这样才会加载修改后的库文件。

Q: 这种方法支持模拟交易吗？
A: 支持。在模拟交易中同样可以引用研究根目录下的文件。但请注意，如果您在模拟交易运行期间修改了 .py 文件，模拟交易进程可能需要等到第二天重启（或手动重启）才会应用新的逻辑。