历史 K 线下载 · 易行量化

完整调用

import os
from pathlib import Path
from exsdk import ExApi

output = Path("data")
output.mkdir(parents=True, exist_ok=True)
with ExApi(os.environ["EXSDK_TOKEN"]) as api:
    rows = api.tools.download_kline_data(
        symbol=os.environ["EXSDK_SYMBOL"],
        period="1m",
        start="20260901",
        end="20260909",
        csv_file_name=output / "history.csv",
    )
    print("写入行数", rows)

运行前把 EXSDK_SYMBOL 设置为需要下载的期货合约，并选择该合约有数据的日期范围。方法同步完成，不需要额外调用 wait_update()。

日期、周期与范围

start、end 都是 YYYYMMDD 格式的有效交易日字符串，起止日都包含，且 start <= end。
夜盘归属其交易日，不按自然日切分。
周期与 watch_kline() 相同；仅支持期货。
SDK 自动分页。单个交易日超过查询上限时会报错，不静默丢弃数据。

CSV 格式

输出按时间升序，相同时间戳只写入一行。列与 K 线 DataFrame 相同，UTF-8 BOM 编码、不含 pandas 索引，缺失数值写为空单元格。没有数据时写出表头并返回 0。

import pandas as pd
frame = pd.read_csv("data/history.csv", encoding="utf-8-sig")
print(frame.head())

文件与并发行为

csv_file_name 接受字符串或 pathlib.Path；父目录必须已存在。成功覆盖同名文件，失败保留原文件并清理临时文件。目录不可写、空间不足等会以 ExError 报告。

下载不会更新已建立的观察句柄，也不会暂停实时流；大量订阅时长时间下载可能积压尚未消费的推送。建议批量历史任务使用独立程序，避免阻塞正在驱动交易的更新循环。当前尚未结束的 K 线可能在下载后继续变化。