Vibe-Trading 数据技能实战Tushare trade_cal 交易日历接口的完整调用指南【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading导读交易日历是量化研究与回测系统中最基础也最容易被忽视的数据资产只有先明确哪些日子开市、上一个交易日是哪天才能正确地做数据对齐、信号切片与绩效口径统计算。本文以 Vibe-Trading 仓库中 Tushare 数据技能agent/src/skills/tushare内置的trade_cal接口文档为骨架完整讲解其输入/输出参数、两种 Python 调用方式、数据字段语义并结合仓库内 Tushare 加载器与示例脚本的源码实现给出可直接落地到回测与盘中任务的实战用法。读完本文你将掌握如何获取沪深及国内期货交易所的交易日历、如何利用pretrade_date定位上一交易日、以及如何规避积分与频率限制。一、接口概览交易日历在 Vibe-Trading 数据技能中的位置trade_cal是 Tushare Pro 的核心基础接口在 Vibe-Trading 的 Tushare 技能数据接口列表中对应 ID 为 26 的股票数据条目其描述为获取各大交易所交易日历数据默认提取的是上交所见 SKILL.md。同一接口在期货数据分类下还有 ID 137 的条目用于获取各大期货交易所交易日历见 期货数据/交易日历.md。两个条目指向同一底层接口trade_cal区别仅在默认场景股票数据版本枚举了 SSE、SZSE 以及全部期货交易所而期货数据版本强调上海国际能源交易中心等期货交易所的取值。从仓库结构看Tushare 技能将全部数据接口的参考文档集中在 references 目录下按股票数据/基础数据/交易日历.md这样的多级目录组织方便 Agent 在接到数据请求时按分类快速检索对应接口文档。使用本接口需要 Tushare 账号具备2000 积分这也是 Tushare 平台上多数基础接口的通用门槛。文档同时提示可以通过 Tushare 官方的数据工具WebClient在线调试和查看数据便于在写代码前先验证字段与样例。二、输入参数详解trade_cal的全部入参均为可选文档给出的参数表如下名称类型必选描述exchangestrN交易所SSE 上交所SZSE 深交所CFFEX 中金所SHFE 上期所CZCE 郑商所DCE 大商所INE 上能源start_datestrN开始日期格式 YYYYMMDDend_datestrN结束日期is_openstrN是否交易0 休市1 交易需要重点理解几个细节exchange 不传时默认返回上交所SSE数据。这一默认行为与 SKILL.md 中默认提取的是上交所的描述一致。因此当需要深交所或期货交易所的日历时必须显式传入对应的交易所代码。日期格式固定为 YYYYMMDD 八位字符串。这与 Tushare 全系接口的日期约定一致见 SKILL.md 的参数格式说明不可传2018-01-01或2018/01/01这类带分隔符的写法。start_date / end_date 建议成对使用。不传日期时接口返回的边界由服务端决定实战中为了数据可控应当始终显式指定起止日期。is_open 用于过滤开/休市记录。需要只取交易日时传1需要休市日如统计节假日时传0。注意文档中该参数类型标注为 str与输出字段is_open的字符串表示保持一致。数据分页与单次上限虽然交易日历一年约 365 条记录、单次调用通常可覆盖全年但跨多年查询时仍建议按年或按季度分批拉取避免超过 Tushare 对单次返回行数的限制。三、输出参数详解接口返回 pandas DataFrame字段如下名称类型默认显示描述exchangestrY交易所SSE 上交所SZSE 深交所cal_datestrY日历日期YYYYMMDDis_openstrY是否交易0 休市1 交易pretrade_datestrY上一个交易日四个字段中cal_date与is_open是最常用的组合用于判断某一天是否开市而pretrade_date是最容易被忽视但价值很高的字段——它直接给出了每个日历日所对应的上一个交易日在回测系统中用于将自然日映射到最近的前一个交易日避免自己用循环向前逐日回溯既准确又高效。需要说明上述字段表来自股票数据分类下的交易日历文档其中 exchange 的描述仅列举了 SSE/SZSE 两个股票交易所而期货数据分类下同名接口文档期货数据/交易日历.md指出 exchange 输出与输入参数取值一致即当你查询 CFFEX、SHFE、CZCE、DCE、INE 时返回行的 exchange 列会对应这些交易所代码。同时期货版本将pretrade_date标注为默认不显示N如需该字段可在调用时显式声明。四、Python 调用方式接口文档给出两种等价写法。第一种是对象方法式pro ts.pro_api() df pro.trade_cal(exchange, start_date20180101, end_date20181231)第二种是通用查询式df pro.query(trade_cal, start_date20180101, end_date20181231)两种方式最终都落到同一个 Pro 接口上区别仅是调用风格pro.trade_cal(...)通过属性访问自动映射到trade_cal接口pro.query(trade_cal, ...)则在接口名较多、需要动态拼装参数时更灵活。4.1 初始化 Pro API 与 Token 配置在 Vibe-Trading 仓库的实践里Token 的获取方式有明确约定。以技能目录下的示例脚本 scripts/stock_data_example.py 为参考import tushare as ts from src.config.accessor import get_env_config # 优先读取项目环境配置中的 token其次读取 tushare 本地记录 token get_env_config().data.tushare_token or ts.get_token() # 初始化 pro 接口 pro ts.pro_api(token)也就是说Token 有三种来源优先级从高到低为项目统一环境配置中的tushare_token字段仓库在 src/config/env_schema.py 中定义环境变量 schema环境变量TUSHARE_TOKEN参见 SKILL.md 的快速上手说明export TUSHARE_TOKENyour_tokentushare包本地保存的 tokents.get_token()。这种多级回退的设计与仓库后端数据加载器保持一致在 agent/backtest/loaders/tushare.py 中Tushare 加载器定义了TUSHARE_TOKEN_PLACEHOLDERS {, your-tushare-token}这类占位符检测逻辑只有当 token 非空且不是占位符时才认为连接可用并据此决定是否启用 tushare 作为数据源。4.2 一个完整的可运行示例综合以上内容一个按年获取全部交易所日历、并额外取出pretrade_date的完整写法如下import tushare as ts from src.config.accessor import get_env_config token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token) # 获取上交所 2018 年全年交易日历默认交易所 df pro.trade_cal( exchangeSSE, start_date20180101, end_date20181231, ) print(df[[exchange, cal_date, is_open, pretrade_date]].head()) # 仅取交易日 trade_days df[df[is_open] 1][cal_date].tolist() print(f2018 年上交所交易日数量: {len(trade_days)}) # 期货交易所示例大连商品交易所 df_dce pro.query(trade_cal, exchangeDCE, start_date20180101, end_date20181231) print(df_dce.head())五、数据样例解读接口文档给出的 2018 年上交所数据样例如下节选exchange cal_date is_open 0 SSE 20180101 0 1 SSE 20180102 1 2 SSE 20180103 1 3 SSE 20180104 1 4 SSE 20180105 1 5 SSE 20180106 0 6 SSE 20180107 0 7 SSE 20180108 1 ... 20 SSE 20180121 0从样例可以直观看到典型规律2018-01-01 为元旦假期is_open0即休市1 月 2 日至 5 日周二至周五连续交易is_open11 月 6 日、7 日周六、周日休市交易日与休市日的分布与自然周历完全对应且法定节假日被正确标记为休市。这说明trade_cal返回的是交易所官方口径的日历A 股周末 法定节假日休市的规则被完整编码其中。期货交易所如 DCE的数据样例结构完全一致只是 exchange 列取值不同可以自行在 期货数据/交易日历.md 中核对 DCE 2018 年全年样例。六、实战应用交易日历在回测与数据对齐中的用法结合 Vibe-Trading 仓库的工程实践交易日历数据主要有四类典型用途6.1 回测交易日序列生成回测引擎需要一张有效交易日期列表来遍历每一天。用trade_cal拉取区间内is_open1的记录即可得到该序列避免把周六日或节假日当作有效交易日从源头杜绝信号在休市日被计算这类时序污染问题。仓库的 Tushare 加载器在 agent/backtest/loaders/tushare.py 中封装了 tushare 数据源的接入方式并将返回的trade_date统一转换为pandas.Timestamp后设为索引见该文件对trade_date的pd.to_datetime与set_index处理保证了后续回测统一按 DatetimeIndex 对齐。6.2 用 pretrade_date 做上一个交易日映射这是trade_cal相对其他数据源最实用的一点。当需要把某个自然日例如今天映射到最近的前一个交易日时直接查该自然日对应的pretrade_date即可无需自己写循环回溯。对于节假日跨周的情形如国庆长假pretrade_date能一次到位地给出正确的上一个交易日这在资金归因、持仓估值、复权因子衔接等场景中至关重要。6.3 多交易所日历差异处理A 股与国内期货交易所的休市安排并非完全一致例如部分交易所的特定节假日安排不同。trade_cal支持按exchange分别查询 SSE/SZSE/CFFEX/SHFE/CZCE/DCE/INE因此跨市场策略需要分别维护各自的交易日历而不是共用一个 A 股日历。这与仓库回测引擎按市场拆分agent/backtest/engines/下 china_a、china_futures、global_futures 等独立引擎的多市场架构思路一致。6.4 数据缓存与积分节省交易日历是低频变化的元数据一年全量也仅数百行。建议在首次拉取后本地缓存并按季度增量更新避免每次回测都重复消耗积分与网络请求。由于接口要求 2000 积分批量任务尤其需要做好缓存层这与仓库中其他数据源加载器普遍采用的先查本地/缓存、再回源拉取的策略一致例如 agent/backtest/loaders/base.py 定义的基础加载器抽象。七、注意事项与常见坑积分不足trade_cal需 2000 积分。若调用报权限类错误先检查账号积分与 token 是否正确配置参照第四节的三级 token 回退。日期格式必须为YYYYMMDD字符串传入 datetime 对象或带分隔符字符串会导致参数校验失败。默认交易所不传exchange时默认返回上交所SSE需要其他交易所务必显式传参。is_open 的类型接口返回的is_open是字符串 0/1做布尔过滤时建议用df[is_open] 1而非直接astype(bool)或与整数 1 比较避免类型不匹配的隐性错误。跨年大批量查询虽然单次可覆盖一年但多年区间建议按年分片请求既规避单次返回行数上限也便于按年做缓存与重试。数据版权与频率Tushare 数据仅限研究与个人使用商用需遵守平台条款同时注意接口调用频率限制并发拉取容易触发限流。仓库的 Tushare 加载器在 agent/backtest/loaders/tushare.py 处对tushare quota hit场景做了等待重试处理说明频率限额是真实存在的边界条件编写批量脚本时应参考这种退避重试策略。八、延伸同族交易日历与关联接口除 A 股/期货的trade_cal外Tushare 还提供港美股版本的交易日历接口Vibe-Trading 的技能参考文档中同样收录港股交易日历hk_tradecalID 250美股交易日历us_tradecalID 253跨境或多市场策略在做日期对齐时应使用与标的所在市场匹配的日历接口切勿用 A 股日历去对齐港美股数据。这与仓库回测引擎按市场global_equity、india_equity、korea_equity 等拆分实现的思路相互印证。结语trade_cal是 Tushare 数据技能中体量虽小、却被回测与数据工程广泛依赖的接口。掌握其参数语义、两种调用方式与pretrade_date的正确用法能让交易日期序列的生成与上一交易日的映射从手写逻辑中解放出来。在 Vibe-Trading 中该接口文档位于 agent/src/skills/tushare/references/股票数据/基础数据/交易日历.md配合 SKILL.md 的快速上手说明、scripts/stock_data_example.py 的完整示例脚本以及 agent/backtest/loaders/tushare.py 的加载器实现即可把交易日历无缝接入到自己的回测与盘中任务管线中。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考