kdata 模块核心 API 接口文档 (独立对外版)

kdata 是一个专注于量化行情数据获取和分析的 Python 本地开发包。它高度整合了多种行情数据源（如 Efinance, Akshare, Mootdx 等），为量化交易与数据分析提供一站式、高性能、自动本地缓存的极简接口。

本规范文档完全独立自包含，无需依赖其他说明文件即可独立查阅使用。

📖 快速开始与环境要求

• Python 版本: Python >= 3.11
• 安装与引用:

  pip install kdata
  

  import kdata
  from kdata import KDataError, KDataParamError, KDataFetchError
  

⚠️ 异常体系与最佳实践 (Exception Handling)

kdata 提供了结构化、分工明确的自定义异常类体系（定义于 kdata.exceptions，并通过顶层统一导出），便于调用方精准区分参数校验与路由问题与网络与数据拉取问题。

为了确保 100% 向后兼容已有业务代码，所有异常均采用多重继承设计：

最佳捕获与调用模式：

import kdata
from kdata import get_any_ohlc, KDataParamError, KDataFetchError

# 精准区分参数错误与网络抓取失败
try:
    df = get_any_ohlc("sh.600519", start_date="2024-01-01")
except KDataParamError as e:
    # 处理参数格式或周期不支持等问题
    print(f"输入参数错误: {e}")
except KDataFetchError as e:
    # 处理上游网络波动或数据拉取失败
    print(f"数据获取失败: {e}")

📌 数据规范与数据格式说明 (Data Specifications)

本项目统一使用 pandas.DataFrame 作为 K 线数据的手持结构，标准列名为 open, high, low, close, volume，索引 (Index) 为交易日期 Date (DatetimeIndex)。

1. 字段定义表

2. 关于 volume 列物理含义的统一说明

为了保持接口一致性，本库统一使用 volume 列名，但其物理含义根据标的自动切换：

1. 个股 (Stocks) & ETF: volume 代表 成交量 (Trading Volume)，即成交的股数 (Shares) 或手数 (Lots)。
2. 大盘指数 (Indices): volume 代表 成交金额 (Trading Amount / Turnover)。因为大盘指数无实体发行股数，成交金额更能真实反映全市场的流动性与活跃度。

3. 复权规则与分红数据机制 (Adjustment & Dividends)

• 复权规则:
  • 个股与 ETF 默认直接返回前复权 ('qfq') 数据，大盘指数使用不复权数据。
  • Fail-Fast 原则: 若在复权计算时发生分红除权数据拉取失败或因子对齐异常，系统严禁静默降级为未复权行情并禁止污染本地缓存，将显式抛出 DividendFetchError 或 AdjustmentCalculationError 专用异常。
• 分红数据机制:
  • ETF/LOF 前复权依赖 fund_fh_em_cache.parquet 分红除息表。
  • 系统内置 7 天分红缓存 TTL，并在检测到除权事件时自动自愈历史 QFQ 缓存，确保历史序列无除权价格断层。
• 本地缓存: 历史行情数据自动落地 Parquet（兼容历史 CSV）本地缓存。缓存命中时不发起重复网络请求，避免受网络波动或频控影响。

🏷️ 标的代码命名规范 (Symbol Formats)

📊 一、核心行情数据获取 (Core Data Fetching)

1. get_any_ohlc - 自适应统一获取 K 线数据（核心推荐入口）

描述: kdata 推荐的核心统一入口。根据传入的标的代码（个股、ETF、大盘指数）或 MarketIndex 枚举，系统在底层自动识别标的类型并安全派发：

• 个股与 ETF 标的：自动路由至个股存储引擎（data/{market}/stocks/ 或 etfs/），默认进行前复权 (qfq) 处理；
• 大盘指数标的：自动路由至指数独立存储引擎（data/indices/），不复权并保持点位真实历史轨迹。

代码示例:

import kdata
from kdata import get_any_ohlc, MarketIndex, Period

# 1. 获取个股日 K 线（自动识别为个股，前复权）
df_stock = get_any_ohlc("sh.600519", start_date="2024-01-01", period=Period.DAILY)
print(df_stock.head())

# 2. 获取场内 ETF 日 K 线（自动识别为 ETF）
df_etf = get_any_ohlc("510300", start_date="2024-01-01")

# 3. 获取大盘指数日 K 线（自动识别为指数，隔离存储并保留真实点位）
df_index = get_any_ohlc("sh.000300", start_date="2024-01-01")

# 4. 使用 MarketIndex 枚举获取核心指数（支持 IDE 补全与防错）
df_sh   = get_any_ohlc(MarketIndex.SH, start_date="2024-01-01")    # 上证指数
df_hsi  = get_any_ohlc(MarketIndex.HSI, start_date="2024-01-01")   # 恒生指数
df_spx  = get_any_ohlc(MarketIndex.SP500, start_date="2024-01-01") # 标普500

参数说明:

返回值说明: pandas.DataFrame

• 索引 (Index): Date (DatetimeIndex，标准化为北京时间 UTC+8)
• 列 (Columns): open, high, low, close, volume
• 底层存储: 个股/ETF 存入 K_DATA_CENTER/{start}_{end}/，指数存入 K_DATA_CENTER/indices/

2. generate_weekly_kdata - 日K转换为周K数据

描述: 将日 K 线 DataFrame 自动重采样并合成为符合标准的周 K 线 DataFrame。

代码示例:

from kdata import get_any_ohlc, generate_weekly_kdata, Period

daily_df = get_any_ohlc('sh.600519', start_date='2023-01-01', period=Period.DAILY)
weekly_df = generate_weekly_kdata(daily_df)

参数说明:

返回值说明: pandas.DataFrame（周K线结构，按每周最后一个交易日聚合并重采样）

4. get_market_breadth - 市场广度指标

描述: 获取 A 股全市场多空家数与涨跌停历史统计数据。

代码示例:

from kdata import get_market_breadth

df = get_market_breadth(days=5)
print(df)

参数说明:

返回值说明: pandas.DataFrame

• 列 (Columns): 日期, 上涨家数, 下跌家数, 涨停家数, 跌停家数

5. get_sector_ranking - 行业板块排名

描述: 获取全市场行业板块领涨/领跌排名数据。

代码示例:

from kdata import get_sector_ranking

# 返回元组: (领涨 TOP N 板块 DataFrame, 领跌 TOP N 板块 DataFrame)
top_sectors, bottom_sectors = get_sector_ranking(top_n=10)

参数说明:

返回值说明: 包含两个 pandas.DataFrame 的元组 (top_sectors, bottom_sectors)

• 列 (Columns): 板块名称, 涨跌幅%, 上涨家数, 下跌家数, 领涨股票, 领涨股票涨幅%

6. get_market_overview - 市场宏观全貌快照

描述: 一站式拉取并汇总包含核心指数、行业板块排名、涨跌停、两融余额、市场情绪、全球主要指数的完整宏观快照字典，自动落盘存储于 data/market/ 目录。

代码示例:

from kdata import get_market_overview

overview = get_market_overview(include_global=True, include_hk=True)
print("包含宏观维度:", list(overview.keys()))

7. get_index_history - 核心指数近期多日行情

描述: 获取主要指数近 N 个交易日的历史行情序列字典。

代码示例:

from kdata import get_index_history

hist = get_index_history(days=10, include_global=True)
print(hist["上证指数"].tail())

📈 二、市场资产规模 (Market Asset Scale)

8. get_etf_scale - ETF 资产规模查询

描述: 获取 ETF 资产管理规模数据（单位：亿元）。

代码示例:

from kdata import get_etf_scale

# 1. 单个代码：返回 float
scale = get_etf_scale('513120')                 # 返回: 114.2 

# 2. 代码列表：返回 {code: scale_float} 字典
scales_dict = get_etf_scale(['513120', '513100'])

参数说明:

返回值说明: 传入单个字符串返回 float（规模，亿元）；传入列表等容器返回 Dict[str, float]。

9. 大盘快照 get_cn_indices / get_hk_indices / get_global_indices

描述: 快速拉取国内、港股、全球主要大盘指数的最新行情快照 DataFrame。

from kdata import get_cn_indices, get_hk_indices, get_global_indices

cn_df = get_cn_indices()        # 国内主要指数 DataFrame
hk_df = get_hk_indices()        # 港股核心指数 DataFrame
global_df = get_global_indices()# 全球核心指数 DataFrame

🛠️ 三、高级 ETF/LOF 溢价套利组件 (Arbitrage & Premiums)

概念解析

• IOPV (实时参考净值): 盘中由交易所实时计算并发布的基金份额参考净值。
• NAV (单位净值): 基金公司官方公布的每股净资产值。
• 折溢价率%: 计算公式为 (价格 - 净值) / 净值 * 100。
• LOF(S) 说明: S 代表 Stale (过期/上日净值)，表示盘中无实时 IOPV 估值，使用前一日净值参考。

10. Scanner - ETF/LOF 溢价监控扫描器

描述: 批量抓取 ETF/LOF 实时价格与净值以计算折溢价率，支持一键筛选 Top 溢价/深折价标的及场内赎回费率提取。

代码示例:

from kdata import Scanner  # 或 from kdata.scanner import Scanner
from mootdx.quotes import Quotes

# 1. 初始化扫描器 (client 可选，默认自动创建 Quotes.factory(market="std"))
scanner = Scanner(f10_workers=12)

# 2. 加载资金池 (支持 YAML 配置文件解析)
etf_universe = Scanner.load_universe('data/etf/config_etf.yaml')

# 3. 执行实时折溢价扫描
scan_df = scanner.scan(etf_universe)

# 4. 批量补充场内赎回费率
scan_df = scanner.add_fees(scan_df)
print(scan_df.head())

# 5. 快捷获取 Top 10 溢价/折价标的 (自动异步补全 F10 标的/官方/赎回费)
all_df, top_premium, top_discount = scanner.scan_prospects(
    etf_universe, top_n=10, simple=False
)

Scanner 构造函数与方法说明:

scan 返回的 DataFrame 列结构:

11. get_etf_premium_data - ETF 估算溢价率数据序列

描述: 获取指定 ETF 历史价格及最新估算净值的溢价率数据序列。

代码示例:

from kdata import get_etf_premium_data  # 或 from kdata.premium import get_etf_premium_data

df = get_etf_premium_data(
    symbol='513100', 
    start_date='2026-07-01', 
    end_date='2026-07-24'
)
print(df.tail())

参数说明:

返回值与列说明: pandas.DataFrame

• 索引 (Index): Date (DatetimeIndex)
• 列 (Columns):
  • close: 每日收盘价 (float)
  • NAV(IOPV_时间): 单位净值/IOPV（列名含时间戳后缀，如 NAV(IOPV_15:30:00)）
  • premium: 绝对折溢价差额 = close - NAV (float)
  • premium_rate: 折溢价率(%) = (premium / NAV) * 100 (float)

12. get_latest_etf_premium - 单只 ETF 最新溢价快照

描述: 获取单只 ETF 实时最新价格、净值和折溢价快照字典。

代码示例:

from kdata import get_latest_etf_premium  # 或 from kdata.premium import get_latest_etf_premium

info = get_latest_etf_premium('513100')
print(info)

参数说明:

返回字典字段解析 (dict):

{
    'code': '513100',              # 证券代码 (str)
    'name': '纳指100ETF',          # 基金简称 (str)
    'price': 2.104,                # 实时盘口现价 (float)
    'nav': 2.085,                  # 单位净值/IOPV (float 或 None)
    'premium_rate': 0.911,         # 实时折溢价率 % (float 或 None)
    'updated': '2026-07-24'        # 净值更新日期/时间戳 (str 或 None)
}

13. 命令行终端工具 (CLI Commands)

系统附带 6 个开箱即用的终端命令行工具，安装包后可直接在命令行调用，无需编写 Python 代码：

1. kdata-download: 单标的/批量 K 线数据下载器

   # 单只股票/ETF K线下载 (指定日期范围)
   kdata-download sh.600519 2024-01-01 2024-12-31
   
   # 单只指数下载
   kdata-download sh.000300 2024-01-01 2024-12-31
   
   # 根据 YAML 配置文件批量下载
   kdata-download -b data/etf/config_etf.yaml
   kdata-download -b data/china/config_a.yaml
   

2. kdata-market: 大盘市场概览与多市场指数快照

   # A 股主要指数快照与概览
   kdata-market --cn
   
   # 港股主要指数概览
   kdata-market --hk
   
   # 美股主要指数概览
   kdata-market --usa
   
   # 全球全市场综合概览
   kdata-market --all
   

3. kdata-etf: ETF 规模筛选、成交额过滤与配置导出

   # 更新本地 ETF 元数据与规模缓存
   kdata-etf update
   
   # 过滤规模 >= 100亿 且 日均成交额 >= 1亿 的高流动性 ETF
   kdata-etf filter --min-scale 100 --min-vol 1
   
   # 导出规模 >= 50亿 的 ETF 配置列表到 YAML
   kdata-etf export --min-scale 50 -o target.yaml
   

4. kdata-premium: 单只 ETF 实时/历史折溢价率与 IOPV 分析

   # 获取 513100 实时溢价快照
   kdata-premium 513100 --snapshot
   
   # 获取 513100 指定日期范围的历史溢价序列
   kdata-premium 513100 2024-01-01 2024-12-31
   

5. kdata-scan: 全市场 ETF/LOF 实时折溢价套利机会扫描器

   # 扫描默认资金池
   kdata-scan
   
   # 简易加速模式 (跳过 F10 赎回费拉取)
   kdata-scan --simple
   
   # 筛选折价率 >= 3% 的标的
   kdata-scan --min-discount-pct 3 --simple
   

6. kdata-serve: 启动 HTTP 中心数据中继服务 (Central Hub)

   # 在指定端口启动 HTTP 数据中心服务 (供各客户端作为统一数据源代理访问)
   kdata-serve --host 0.0.0.0 --port 8765
   

   核心 HTTP 端点与标的隔离规范:

   • GET /ohlc: 个股与场内 ETF 历史 K 线（前复权）。严格禁止传入大盘指数，若误传大盘指数，服务端将拦截并返回 HTTP 404（响应正文说明具体原因）。
   • GET /market/history: 大盘基准指数历史 K 线（不复权）。严格禁止传入普通个股或 ETF，若误传普通个股，服务端将拦截并返回 HTTP 404。
   • GET /market/indices: 核心市场指数最新行情截面快照表。
   • GET /market/overview: 宏观市场全貌快照字典（多空家数、两融、板块排名等）。

   注：当 Python 客户端（配置了 KDATA_CENTRAL_URL）请求服务端收到 404、429 或网络异常时，系统将自动无感降级回退至本地数据源链，不会中断业务运行。

🔧 四、基础工具与辅助配置 (Utils & Env)

14. init_env / get_data_dir

描述: 管理 kdata 本地缓存数据目录与环境初始化。

from kdata import init_env, get_data_dir

data_dir = get_data_dir()  # 返回缓存目录路径，默认: ~/.kdata
init_env(force=True)       # 强制重置并重建本地缓存索引结构

15. get_name_from_code

描述: 通过代码反查股票、ETF 或大盘指数的官方中文名称。

from kdata import get_name_from_code

name = get_name_from_code('sh.600519')  # 返回: '贵州茅台'

📅 五、交易日历与节假日服务 (Calendar Service)

提供基于交易所真实开休市规则与法定节假日的交易日裁决与自动向前回溯能力。

16. is_trade_date - 交易日判定

描述: 判定指定日期是否为指定市场的开盘交易日。自动过滤周末并精确识别国务院公布的元旦、春节、清明、劳动节、端午、中秋、国庆等法定休市安排。

from kdata import is_trade_date

# 检查指定日期是否为 A 股交易日
is_open = is_trade_date("2024-10-01", market="cn")  # 返回: False (国庆节休市)
is_open_today = is_trade_date()                     # 默认检测当天是否开盘

17. get_previous_trading_date - 历史交易日回溯

描述: 获取严格早于指定基准日期的最近一个法定交易日。自动跳过周末与连续法定休市长假。

from kdata import get_previous_trading_date

# 获取国庆假期前最后一个交易日
prev_date = get_previous_trading_date("2024-10-08", market="cn")  # 返回: '2024-09-30'

18. get_latest_settled_trading_date - 最新已结算交易日

描述: 获取逻辑上最新的已结算交易日。综合考量市场结算时间点（如 A 股 16:00 CST、港股 17:00 CST、美股 21:00 UTC）与休市日历。

from kdata import get_latest_settled_trading_date

settled_date = get_latest_settled_trading_date("cn")

📑 六、专业财务与公告检索服务 (Fundamentals & Announcements)

19. get_financial_report - 解析专业财务数据包

描述: 解析通达信本地专业财务 .zip 压缩包或解压后的 .dat 文件，覆盖 580+ 专业财务科目，原生支持中英文表头映射。

from kdata import get_financial_report

# 解析本地财报并使用中文表头
df_fin = get_financial_report("data/financial/gpcw20240630.zip", header="zh")
if not df_fin.empty:
    print(df_fin[["基本每股收益", "每股净资产", "净资产收益率", "营业收入", "净利润"]])

20. get_stock_announcements - 巨潮资讯权威公告检索

描述: 基于标准 HTTP 接口实时检索上市公司官方披露公告，支持全市场股票（含主板、科创板、创业板），提供标题、类型、日期及原始 PDF 附件直链。

from kdata import get_stock_announcements

# 获取贵州茅台最近 10 条官方公告
df_ann = get_stock_announcements("600519", count=10, page=1)
if not df_ann.empty:
    for _, row in df_ann.iterrows():
        print(f"[{row['date']}] {row['title']} -> {row['pdf_url']}")

📋 七、枚举与常量定义 (Constants)

1. Period - K 线周期枚举

from kdata import Period

Period.DAILY   # 日线周期 ('d')
Period.WEEKLY  # 周线周期 ('w')

2. DownloadProvider - 行情下载数据源枚举

from kdata import DownloadProvider

DownloadProvider.AUTO  # 默认自动模式（系统自动调度并在多数据源间无感降级备份，外部调用推荐使用此项）

3. MarketIndex - 核心大盘指数枚举

MarketIndex 枚举整合了跨市场的核心基准指数，传入 get_index_ohlc 时具备代码防错与 IDE 智能补全支持：

调用示例:

from kdata import MarketIndex, get_index_ohlc

# 使用枚举直接获取指数历史 K 线
df_sh = get_index_ohlc(MarketIndex.SH, start_date="2024-01-01")
df_hsi = get_index_ohlc(MarketIndex.HSI, start_date="2024-01-01")
df_spx = get_index_ohlc(MarketIndex.SP500, start_date="2024-01-01")

💡 六、最佳实践与设计原理

1. 自动多源降级: AUTO 调度模式下，EFinance, Akshare, Mootdx, Baostock 互为备份。单个数据源遭遇网络波动或频控时，系统会自动无感切换备份数据源。
2. 高效增量缓存: 所有下载的历史 K 线数据落地本地缓存（默认优先 Parquet，兼容历史 CSV）。二次查询时增量补全，极大减少网络 API 调用开销。
3. 时区与日期防错: 交易日期统一处理为北京时间 (CST) 00:00:00 对应交易日，避免跨时区或盘后交易日推导偏差。
4. 批量下载与并发控制 (Pacing): 系统遵循 Gentle on Providers 原则以保障数据抓取的长期稳定性。若配置了 Central Hub (KDATA_CENTRAL_URL)，当服务端队列负载过高触发 429 限流保护时，内部已自动记录退避并平滑降级到本地行情源，不会向外部抛出异常中断程序。
   • 外部调用方最优做法： 如果外部是多线程/多进程批量下载任务（如 ThreadPoolExecutor）：
     • 将线程并发数调小（建议并发在 2 ~ 4 之间）。
     • 在批量循环中保留微小间隔（如 time.sleep(0.05 ~ 0.1)）。