【PTrade 量化 API】get_etf_stock_info 函数详解：查询 ETF 成分股持仓数量与现金替代规则

前言在上一篇文章中我们介绍了用get_etf_stock_list一键获取 ETF 全量成分股列表完成了基础的持仓穿透。但在 ETF 申赎套利、实物申购、成分股风险排查等实际量化场景中仅知道成分股名单远远不够我们还需要知道单只成分股的持仓数量、申购时能否现金替代、个股是否停牌等关键信息。本文就带大家完整学习 PTrade 平台的get_etf_stock_info函数从功能定义、参数语法、返回字段到实战代码、避坑指南全面掌握 ETF 成分股明细查询方法。一、函数功能概述get_etf_stock_info的核心功能是根据指定的 ETF 代码与成分股代码返回该成分股在对应 ETF 中的持仓数量、现金替代标志、交易状态等详细信息。如果说get_etf_stock_list是 ETF 的「配料清单」那get_etf_stock_info就是每一味配料的「详情说明书」—— 不仅知道 ETF 持有哪些股票还能知道每只股票持有多少、申购时能不能用现金代替、当前能不能正常交易。二、函数语法与参数说明2.1 调用格式# 查询单只成分股详情 get_etf_stock_info(etf_code, stock_code) # 批量查询多只成分股详情 get_etf_stock_info(etf_code, [stock_code1, stock_code2, ...])2.2 参数说明表格参数名数据类型必填说明etf_codestr是单只 ETF 的证券代码必须带市场后缀例如510300.SS、159915.SZstock_codestr / list是待查询的成分股代码支持单个字符串或代码列表均需附带市场后缀2.3 使用环境限制该函数为 PTrade 股票交易模块专属 API仅可在 PTrade 客户端的股票交易环境中调用回测环境或其他第三方环境无法正常运行。三、返回值核心字段详解函数返回嵌套字典结构外层字典的键为成分股代码内层字典存储该股票的各项明细信息。高频实用的核心字段如下表字段名数据类型字段含义取值说明code_numfloatETF 对该成分股的持仓数量单位为股例如4700.0代表 ETF 持有 4700 股该股票cash_replace_flagintETF 申购时是否支持现金替代1 支持现金替代0 不支持现金替代is_openint成分股当前交易状态1 正常交易0 停牌不可买卖四、实战代码示例4.1 示例 1查询单只成分股持仓细节场景说明查询沪深 300ETF510300.SS中贵州茅台600519.SS的持仓数量、现金替代权限及当前交易状态。def initialize(context): print(策略启动查询沪深300ETF中贵州茅台的持仓细节) g.etf_code 510300.SS # 沪深300ETF代码 g.stock_code 600519.SS # 贵州茅台代码 def before_trading_start(context, data): # 1. 调用函数获取单只成分股详情 stock_detail get_etf_stock_info(g.etf_code, g.stock_code) # 2. 提取核心字段并格式化 hold_num stock_detail[g.stock_code][code_num] can_replace 可以 if stock_detail[g.stock_code][cash_replace_flag] 1 else 不可以 is_trading 正常交易 if stock_detail[g.stock_code][is_open] 1 else 已停牌 # 3. 打印结果 print(f{g.etf_code}沪深300ETF中 {g.stock_code}贵州茅台的详情) print(f1. ETF持仓数量{hold_num} 股) print(f2. 申购时能否现金替代{can_replace}) print(f3. 股票当前状态{is_trading}) def handle_data(context, data): pass运行输出示例策略启动查询沪深300ETF中贵州茅台的持仓细节 510300.SS沪深300ETF中 600519.SS贵州茅台的详情 1. ETF持仓数量100.0 股 2. 申购时能否现金替代可以 3. 股票当前状态正常交易4.2 示例 2批量查询多只成分股并对比场景说明同时查询沪深 300ETF 中贵州茅台、工商银行两只成分股的信息对比持仓数量与现金替代规则。def initialize(context): print(策略启动对比沪深300ETF中两支成分股的持仓细节) g.etf_code 510300.SS # 沪深300ETF代码 g.stock_codes [600519.SS, 601398.SS] # 贵州茅台、工商银行 def before_trading_start(context, data): # 1. 批量查询多只成分股详情 stocks_detail get_etf_stock_info(g.etf_code, g.stock_codes) # 2. 循环遍历输出每只股票信息 for code in g.stock_codes: stock_name 贵州茅台 if code 600519.SS else 工商银行 hold_num stocks_detail[code][code_num] can_replace 可以 if stocks_detail[code][cash_replace_flag] 1 else 不可以 print(f\n{stock_name}{code}详情) print(f- ETF持仓数量{hold_num} 股) print(f- 能否现金替代{can_replace}) def handle_data(context, data): pass运行输出示例策略启动对比沪深300ETF中两支成分股的持仓细节 贵州茅台600519.SS详情 - ETF持仓数量100.0 股 - 能否现金替代可以 工商银行601398.SS详情 - ETF持仓数量6100.0 股 - 能否现金替代可以五、使用注意事项避坑指南双参数必填代码必须带市场后缀ETF 代码与成分股代码均为必传参数且必须附带.SS沪市或.SZ深市后缀缺少参数、漏写后缀或代码格式错误都会返回空字典。仅支持查询 ETF 自有成分股只能查询目标 ETF 实际包含的成分股。若查询的股票不在该 ETF 成分股列表中例如在上证 50ETF 中查询宁德时代会返回空信息并非函数调用失败。批量查询需传入列表格式查询多只成分股时需将股票代码放入 Python 列表中统一传入而非多个独立参数单只查询直接传入字符串即可。运行环境限制与get_etf_stock_list一致该函数仅在 PTrade 股票交易模块可用使用前请确认当前运行环境。六、总结get_etf_stock_info是 ETF 精细化量化策略的核心底层工具尤其适用于 ETF 实物申赎套利、停牌成分股风险排查、申赎成本估算等场景。配合get_etf_stock_list函数可以完整实现「获取全量成分股 → 批量查询持仓细节」的全流程为 ETF 相关量化策略提供完整的数据支撑。风险提示本文只做技术教学不做任何投资建议本文举例上市公司名称 仅仅用作举例说明不具有任何其他含义投资有风险入市需谨慎