refactor(datasource): 统一数据获取架构,使用 df.attrs 传递元数据

核心改进:
- CCXTSource 添加 df.attrs 支持(source, exchange, symbol, timeframe, adj)
- UniversalDataFetcher 简化透传方法,保留兼容接口
- fetch_etf_with_nav 标记为 deprecated,推荐使用 fetch_etf + df.attrs
- 所有数据源统一契约:返回 DataFrame + df.attrs

架构改进:
- 统一返回单 DataFrame,元数据通过 attrs 传递
- 消除多返回值接口(price_df, nav_df, premium_series)
- 文档注释更新,反映新接口用法
- 添加 DeprecationWarning 提示迁移路径
This commit is contained in:
2026-05-23 23:40:18 +08:00
parent 7446d1b2e8
commit 3619e26bf1
2 changed files with 31 additions and 4 deletions

View File

@@ -12,8 +12,10 @@
# 单标的获取(自动识别类型)
df = fetcher.fetch("000300.SH", "2024-01-01", "2024-12-31")
# ETF获取含净值
price_df, nav_df = fetcher.fetch_etf_with_nav("513100.SH", "2024-01-01", "2024-12-31")
# ETF获取含净值,从 df.attrs 提取
df = fetcher.fetch_etf("513100.SH", "2024-01-01", "2024-12-31")
nav_df = df.attrs.get('nav')
premium_series = df.attrs.get('premium')
# 批量获取
results = fetcher.fetch_batch(["000300.SH", "NDX", "N225"], "2024-01-01", "2024-12-31")
@@ -306,9 +308,12 @@ class UniversalDataFetcher:
end_date: str
) -> Tuple[Optional[pd.DataFrame], Optional[pd.DataFrame], Optional[pd.Series]]:
"""
获取ETF价格 + 净值 + 溢价率序列(兼容旧接口)
获取ETF价格 + 净值 + 溢价率序列(⚠️ DEPRECATED 兼容旧接口)
内部调用统一的 fetch_etf() 方法,从 DataFrame.attrs 提取元数据
⚠️ 推荐使用新接口:
df = fetcher.fetch_etf(code, start_date, end_date, adj='raw')
nav_df = df.attrs.get('nav')
premium_series = df.attrs.get('premium')
Args:
code: ETF代码
@@ -321,6 +326,14 @@ class UniversalDataFetcher:
- nav_df: ETF净值数据来自 df.attrs['nav']
- premium_series: 溢价率序列(来自 df.attrs['premium']
"""
import warnings
warnings.warn(
"fetch_etf_with_nav() is deprecated. "
"Use fetch_etf(code, start, end, adj='raw') and access df.attrs['nav'] and df.attrs['premium'] instead.",
DeprecationWarning,
stacklevel=2
)
# 调用统一的 fetch_etf() 方法
df = self._tushare.fetch_etf(code, start_date, end_date, adj='raw')