joinquant 平台如何读写文件与实现数据持久化？（附 read_file / write_file Python 源码）

在 JoinQuant（聚宽）量化交易平台中，read_file 和 write_file 是用于在回测、模拟交易与研究环境（私有空间）之间进行数据读写和持久化的核心 API。

一、常用文件操作 API 说明

1. write_file（写入文件）

将策略运行过程中的数据写出保存到研究环境的根目录（或指定相对路径）。

• 语法：write_file(path, content, append=False)
• 参数：
  • path：相对路径（相对于私有空间根目录）。
  • content：文件内容（str 或 bytes）。
  • append：是否为追加模式，默认为 False（覆盖模式）。

2. read_file（读取文件）

在回测或模拟盘中读取保存在研究环境中的私有文件。

• 语法：read_file(path)
• 参数：path 为相对路径。
• 返回值：文件的原始字节/字符串内容（不自动解码）。

二、具体代码示例

1. TXT 文本文件的写入与读取

# 写入文本文件
write_file('my_log.txt', 'Hello JoinQuant! 第一次记录\n', append=False)

# 追加写入文本
write_file('my_log.txt', '追加一条策略记录\n', append=True)

# 读取文本文件
content = read_file('my_log.txt')
log.info(content)

2. CSV 文件（Pandas DataFrame）的写入与读取

在 Python 3 环境下解析 CSV 文件，需要结合 io.BytesIO 与 pandas.read_csv：

import pandas as pd
from io import BytesIO

# 示例1：将策略生成的 DataFrame 保存为 CSV
def after_trading_end(context):
    # 获取近5日行情数据
    df = attribute_history('000001.XSHE', 5, '1d')
    # 将 DataFrame 转换为 CSV 格式文本并保存
    write_file('history_data.csv', df.to_csv(), append=False)

# 示例2：读取研究环境中的 CSV 文件
def initialize(context):
    body = read_file('history_data.csv')
    data = pd.read_csv(BytesIO(body), index_col=0)
    log.info(data.head())

3. JSON 数据的写入与读取

用于保存股票池或策略配置等结构化数据：

import json

# 保存股票池列表为 JSON 文件
stock_list = ['000001.XSHE', '600000.XSHG']
write_file('mystocks.json', json.dumps(stock_list))

# 读取 JSON 文件
json_data = read_file('mystocks.json')
securities = json.loads(json_data)
log.info(securities)

三、注意事项与踩坑指南

1. 文件路径：read_file 与 write_file 操作的都是聚宽平台云端“研究环境”中的私有空间，不能直接读取本地电脑本地硬盘的文件。若需使用本地文件，请先手动上传至聚宽研究环境。一般放在根目录下即可。
2. Python 2 与 Python 3 兼容：
   • 在 Python 3 环境中解析 CSV 文件请导入 from io import BytesIO；
   • 若在 Python 2 环境中需使用 from six import StringIO。
3. 追加写入：追加模式设置 append=True，常用于每日盘后记录交易日志或持仓变动。