mootdx2 对外接口与数据能力全景

mootdx2 模块为量化交易和行情数据分析提供对接通达信及权威金融数据源的完整接口体系。其数据能力涵盖：统一日 K 线智能管理（离线优先+自动增量）、在线行情与底层双模驱动、本地二进制数据极速解析、巨潮资讯公告数据、专业历史财务报表解析、股票与 ETF 通用复权、增量防封数据同步、交易日历、北交所行情、板块管理与数据导出等。

核心特性：

全链路复权支持：所有返回 K 线类数据的接口（bars、k、daily、index 等）均原生支持 adjust='qfq'（前复权）/ adjust='hfq'（后复权）参数，在底层自动完成复权后直接返回。复权模块采用统一通用流水线，同时支持股票与各类 ETF（包含 588xxx 科创板、56xxxx 等）的除权除息（现金分红、送转股、配股）及扩缩股（份额折算）。

离线优先与高可用：提供 DailyDataManager，优先秒级读取本地通达信目录；本地缺失或过期时自动触发增量拉取并持久化至长效缓存，兼顾纯离线的高性能与在线数据的时效性。

底层驱动双模支持：支持内置纯净 Python 原生协议驱动（native）与经典兼容驱动（tdxpy），免除外部魔改依赖污染。

模块解耦与精准导入规范：支持顶层便捷导入（如 from mootdx2 import DailyDataManager, CninfoClient, holiday）与生产级精准子模块导入（from mootdx2.daily import DailyDataManager、from mootdx2.cninfo import CninfoClient、from mootdx2.utils.holiday import holiday），实现毫秒级按需冷启动并消除循环依赖风险。

💡 核心高频函数使用场景速查指南 (Cheat Sheet)

在实际量化工程与数据分析中，面对众多的接口，建议根据**运行环境（有网/无网/本地有无通达信）与业务目标（回测/盘中实盘/盘后归档/事件研究）**按需选择：

核心函数	所属模块 / 类	核心优势	最适用的业务场景
`DailyDataManager.get_daily`	`from mootdx2 import DailyDataManager`	离线优先、零网络延迟、长效缓存、精确换手率。全自动双模自适应，支持直接输出前/后复权序列。	量化策略历史回测、多因子挖掘、特征工程构建、研究员日常离线数据分析（首选入口）。
`DailyDataManager.batch_sync`	`from mootdx2 import DailyDataManager`	内置防封微延时节流、分批落盘、支持断点与进度条。	盘后全自动定时任务（如每日 15:35 调度）、全市场/自选股票池批量历史日线资产沉淀。
`Quotes.quotes`	`Quotes.factory('std').quotes`	毫秒级极速响应，同时支持单只或数百只标的并发请求。	实盘交易监控、盘中五档买卖盘盯盘看板、即时止损/止盈风控扫描、盘中涨跌幅雷达。
`Quotes.bars`	`Quotes.factory('std').bars`	直连主站实时协议，支持从 1 分钟到年线多周期，突破 800 条限制（底层自动分页缝合）。	盘中即时多周期分析（如 5/15/30 分钟 K 线策略）、实盘计算截至当下的跳动日线（实盘未闭合 Bar）。
`Quotes.kline`	`Quotes.factory('std').kline`	混合模式：离线 `.day` 优先 + 在线即时补齐，内置根据 `start` 自适应跨度推算分页。	已有在线会话下的便利查询、单标的交互式快速可视化看盘。
`Reader.minute` / `Reader.fzline`	`from mootdx2 import Reader`	纯本地极速解析通达信 vipdoc 下的 1 分钟/5 分钟二进制 `.lc1` / `.lc5` 文件。	日内高频/T+0 策略历史回测（需依赖本地 Windows 通达信已下载的日内分钟数据）。
`holiday.is_trade_date`	`from mootdx2.utils.holiday import holiday`	内置中国节假日与调休规则，零外部依赖、纯本地微秒级判断。	实盘/回测调度门禁（定时任务前置校验“今日是否开市”，非交易日直接跳过）。
`CninfoClient.announcements`	`from mootdx2 import CninfoClient`	直连权威巨潮资讯源，支持精确分类（财报/分红/减持/重组等）与时间范围检索。	事件驱动策略研究、财报业绩快报即时监测、大股东减持舆情追踪。
`etf_premium`	`from mootdx2 import etf_premium`	一键获取单只或批量 ETF 实时/收盘折溢价率，自动融合 IOPV 与 NAV，消除跨境时滞。	ETF 盘口与套利监测、QDII 跨境溢价防追高、全市场折溢价监控宽表。

目录索引

一、统一日 K 线管理器 (mootdx2.daily.DailyDataManager) 【推荐】
二、在线行情数据接口 (mootdx2.quotes.Quotes)
三、本地历史数据读取接口 (mootdx2.reader.Reader)
四、通达信底层协议驱动与离线解析 (mootdx2.tdx)
五、巨潮资讯独立公告数据源 (mootdx2.cninfo.CninfoClient)
六、专业财务数据报表解析 (mootdx2.financial / mootdx2.affair)
七、增量防封数据同步工具 (mootdx2.sync)
八、复权计算与因子能力
九、交易日历与节假日数据 (mootdx2.utils.holiday)
十、北交所实时行情 (mootdx2.utils.stock_bj_a)
十一、自定义板块管理 (mootdx2.tools.customize)
十二、数据导出与格式转换工具
十三、服务器管理与高可用基础设施
十四、客户端精准对接与核心子模块导入规范
十五、量化核心指标计算与批量导出 (mootdx2.metrics)

一、统一日 K 线管理器 (`mootdx2.daily.DailyDataManager`) 【推荐】

量化回测与生产分析推荐的首选入口。实现了离线优先机制：优先读取通达信本地 .day 文件，零网络开销；若本地缺失、未安装通达信或数据未覆盖最新交易日，则在 auto_download=True 时自动通过在线防封通道拉取并写入长效缓存。

from mootdx2 import DailyDataManager

# 初始化（可指定通达信路径，不指定则自动探测环境变量 MOOTDX2_TDX_DIR 或操作系统默认目录）
manager = DailyDataManager(tdxdir="tests/fixtures")

核心方法列表

接口方法	参数说明	返回值与功能说明
`get_daily(...)`	`symbol`: 证券代码 (如 `'600036'`) `start`: 起始日期 (如 `'2023-01-01'`) `end`: 结束日期 (如 `'2023-12-31'`) `adjust`: 复权类型 (`'qfq'`/`'hfq'`/`None`) `auto_download`: 缺失时自动在线补齐 (默认 `True`) `turnover`: 是否计算并附加基于 gbbq 的精确历史换手率 (默认 `False`) `offset`: 历史条数上限 (默认 `800`)	单标的日 K 线：返回以日期为索引的 `pd.DataFrame`，按需自动执行前/后复权处理与换手率计算。
`get_daily_batch(...)`	`symbols`: 证券代码列表 `start`/`end`/`adjust`/`auto_download`/`turnover`/`offset` 同上	批量日 K 线获取：返回字典 `Dict[str, Optional[pd.DataFrame]]`，便于多标的并发分析。
`batch_sync(...)`	`symbols`: 代码列表 `offset`: 同步条数 (默认 `800`) `delay`: 单请求节流微延时 (秒，默认 `0.08`) `batch_size`: 批次大小 (默认 `50`) `batch_delay`: 批次间休眠 (默认 `1.0`) `show_progress`: 是否显示进度条 (默认 `True`)	批量更新并落盘：盘后自动化调度专用，内置分批节流防封策略与长效缓存。
`is_offline_ready`	属性 (Property)	布尔值：检测本地通达信目录是否就绪可用。

核心机制与外部使用常见问题 (FAQ)

Q1: 离线日线数据如何获取与更新？

途径 A（通达信客户端）：Windows 客户端通过【系统】->【盘后数据下载】下载，数据保存在 vipdoc/{sh,sz}/lday/*.day。
途径 B（纯代码自动化调度，推荐）：通过 DailyDataManager.batch_sync(symbols) 或 CLI 命令 mootdx2 bundle，盘后自动增量下载并写入磁盘长效缓存池（~/.mootdx2/caches/daily/），无通达信软件时首选。

from mootdx2 import DailyDataManager

manager = DailyDataManager()

# 盘后定时任务批量预热长效缓存 (内置微延时防封节流与断点进度)
manager.batch_sync(
    symbols=["600036", "600519", "000001", "510300"],
    offset=800,
    delay=0.08,
)
# 预热后调用 get_daily 将直接秒级直读磁盘缓存，完全不发网络请求
df = manager.get_daily("600036", auto_download=False)

Q2: 如何在各操作系统中自适应运行？（双模机制）

DailyDataManager 内部自动检测运行环境：

本地客户端模式（Windows）：传入 tdxdir="C:/new_tdx" 或配置环境变量 MOOTDX2_TDX_DIR，直接秒级解析本地二进制 .day 文件，零网络开销；
纯代码/服务器模式（Linux / macOS / Docker）：初始化直接留空 DailyDataManager()，自动切换为“在线防封增量同步 + 磁盘长效持久化缓存（7天 TTL）”模式。

Q3: 实盘数据 (Intraday) vs 盘后数据 (EOD) 的判定与避坑（量化必读）

核心差异：交易时段（9:15~~11:30, 13:00~~15:00）通过在线接口获取的最后一根日 K 线属于未闭合的动态 Bar（close 为最新撮合成交价，量额持续累加）；收盘清算后（通常 15:30 以后）及本地 .day 文件的数据为已闭合 Bar。
防前视偏差：回测计算指标前，应确保使用已闭合的数据；若在盘中以未闭合 Bar 计算指标，会导致未来函数污染。

import datetime
from mootdx2.utils.holiday import is_trade_date

def is_market_trading() -> bool:
    """判断当前时间是否处于 A 股盘中竞价交易时段"""
    now = datetime.datetime.now()
    if not is_trade_date(now.strftime("%Y-%m-%d")):
        return False
    t = now.time()
    return (datetime.time(9, 15) <= t <= datetime.time(11, 30)) or \
           (datetime.time(13, 0) <= t <= datetime.time(15, 0))

4. 量化开发避坑要点

防止前视偏差（Lookahead Bias）：策略回测必须使用已闭合的数据。若在盘中以未走完的日 K 线收盘价计算信号发单，实质上使用了未定型的未来数据。
前复权因子的即时生效：除权除息日当天开盘前，复权因子已发生跳变。若使用旧的离线 XDXR 缓存对实盘价格进行前复权，会导致当天开盘出现巨大断层。在交易日盘中计算复权时应确保 XDXR 数据同步更新至最新状态。

Q4: 为什么 `DailyDataManager` 与 `Quotes.kline` 分离设计？（架构设计与选型差异）

既然两者都能实现“本地离线优先 + 在线增量补齐”，其分离设计是基于架构职责分层、网络连接生命周期、缓存落盘机制与业务指标专精的系统性考量：

架构定位：DailyDataManager 为量化回测与特征计算的统一离线数据层 (Data Layer)，零无谓网络初始化；Quotes.kline 为在线行情客户端的便利接口 (Client API)，强依赖 Socket 连接池。
持久化与落盘：DailyDataManager 具备磁盘长效缓存 (7天 TTL) 与 batch_sync 节流调度；Quotes.kline 仅在内存中拼接返回，不修改本地磁盘。
指标专精：DailyDataManager 原生深度集成基于 gbbq 的精确历史换手率 (turnover=True)；Quotes.kline 仅包含基础 OHLCV 字段。
分页机制（突破 800 根限制）：
- 通达信 TCP 单包协议限制单次最大返回 800 根 Bar；
- DailyDataManager 离线读 .day 天生无分页与条数限制（直接读全量历史）；在线回退时若指定较大 offset，底层自动多页缝合并落盘；
- Quotes.kline 内置了自适应跨度推算，指定远期 start 时自动计算所需 Bar 总量并放大 fetch_offset，透明激活底层分页。
选型：回测、全市场特征计算、盘后定时任务首选 DailyDataManager；已有在线会话、盘中临时看盘直接调用 client.kline(...)。

Q5: 为什么启用了【纯离线模式】，中间还会偶发出现网络连接或连接失败警告？（离线降级机制与纯离线避坑）

现象描述：在批量处理大批证券标的（如股票、ETF 列表）时，控制台虽然打印了 DailyDataManager 启用地表最快【纯离线模式】，但在处理某些标的时，突然出现网络等待或警告：
```
WARNING mootdx2.tdx.compat NativeTdxHqAPI 连接失败 60.191.117.167:7709 - 连接被服务器关闭
```
根本原因： DailyDataManager.get_daily(...) 与 get_daily_batch(...) 的参数中，默认 auto_download=True。当本地通达信目录中缺失某些特定标的的 .day 离线文件（例如刚上市不久的新发 ETF、某些指数、或者本地通达信软件中未勾选下载的板块标的）时，系统会自动触发离线缺失在线兜底补齐通道。如果此时处于弱网、离线环境，或者连接到了对高频连接执行 RST/断开的通达信行情节点，便会打印连接警告。

解决方案 A：严格纯离线模式（断网可用、零网络 I/O、无意外报警，量化回测推荐）：在调用时显式指定 auto_download=False。如果本地通达信目录缺失该标的文件，将直接返回 None（或在批量字典中为 None），绝不向外发起任何 Socket 网络请求：

from mootdx2 import DailyDataManager

manager = DailyDataManager(tdxdir="/path/to/tdx")

# 1. 单标的强制严格离线
df = manager.get_daily("159352", auto_download=False)
if df is None:
    print("本地缺失该标的离线 .day 数据，已跳过")

# 2. 批量全市场标的强制严格离线
batch_res = manager.get_daily_batch(
    symbols=["600036", "159352", "510300"],
    auto_download=False,  # 👈 严禁发起任何在线网络请求
)

解决方案 B：若需要在线兜底，如何保证连接稳定性：
1. 运行 mootdx2 bestip 测速，将最快、最稳定的行情服务器 IP 保存至本地配置，避开频繁拒绝连接的不稳定节点；
2. 在盘后集中调用 DailyDataManager.batch_sync(symbols) 批量预热长效缓存池，随后即可 100% 纯离线秒级读取。

二、在线行情数据接口 (`mootdx2.quotes.Quotes`)

通过 Quotes.factory(market='std'|'ext', driver='native'|'compat') 创建行情实例。

市场类型：market='std'（标准市场：沪深 A 股/指数）、market='ext'（扩展市场：期权、期货、港股等）。
底层驱动：driver='native'（内置纯净 Python 协议驱动）、driver='compat'（兼容经典驱动，默认）。

1. 标准市场行情接口 (`StdQuotes`)

接口方法	参数说明	数据内容
`quotes(symbol)`	`symbol`: 股票代码或代码列表	实时日行情快照：最新价、昨收、今开、最高/最低、买卖五档报价及量、成交量、成交额等。
`bars(symbol, frequency, start, offset, adjust)`	`frequency`: K 线周期 `start`/`offset`: 范围 `adjust`: 复权类型 (`'qfq'`/`'hfq'`)	K 线数据（支持前/后复权）：OHLCV + 成交额。周期支持 1分钟/5分钟/15分钟/30分钟/1小时/日/周/月/季/年线。
`index(symbol, frequency, start, offset)`	同上	指数 K 线数据（如上证指数 `000001`）。
`index_bars(...)`	同上	指数 K 线数据（`index` 的等价方法）。
`k(symbol, begin, end, adjust)`	`begin`/`end`: 日期范围 `adjust`: 复权类型	指定日期范围的日 K 线数据（支持前/后复权）。
`minute(symbol)`	`symbol`: 股票代码	当天实时分时数据：每分钟的成交价、成交量。
`minutes(symbol, date)`	`date`: `YYYYMMDD`	历史分时数据：指定日期的分钟级明细。
`transaction(symbol, start, offset)`	范围参数	实时分笔成交 (Tick)：每笔交易的时间、价格、成交量、买卖方向。
`transactions(symbol, start, offset, date)`	日期及范围	历史分笔成交 (Tick)：指定日期的逐笔成交。
`finance(symbol)`	`symbol`: 股票代码	财务基本信息：流通股本、总股本、省份、行业等。
`xdxr(symbol)`	`symbol`: 股票代码	除权除息历史数据：分红、配股、送转股明细，用于复权计算。
`stock_count(market)`	`market`: `0` 深圳, `1` 上海	市场股票数量。
`stocks(market)`	`market`: 市场代码	股票列表：指定市场的所有股票代码、名称等信息。
`stock_all()`	无	全市场股票列表：汇总沪深两市所有证券。
`block(tofile)`	`tofile`: 保存路径（可选）	板块信息：概念、行业、区域板块的分类及成分股归属。
`F10C(symbol)`	`symbol`: 股票代码	公司 F10 目录信息。
`F10(symbol, name)`	`name`: 章节名称（可选）	公司 F10 详情：股东研究、经营分析等文本信息。
`traffic()`	无	网络流量统计：当前连接的数据传输统计。

K 线接口通信机制与职责划分说明：

纯网络请求：Quotes.bars() 内部直接调用底层的行情接口 self.client.get_security_bars(...)，通过 TCP socket 向通达信行情服务器实时请求 K 线数据。

两者的职责划分：

Quotes.bars(...)：纯在线拉取实时/近期 K 线数据（受网络连接和服务器条数限制）。

Reader.daily(...)：纯本地读取通达信目录下的 .day 二进制文件。

Quotes.kline(...)：高级组合接口，内部融合了上述两者（离线 .day 优先 + 在线 bars() 增量补齐/兜底，内存级拼接）。

与 DailyDataManager 的定位区别：

Quotes.kline 是在线行情客户端的便利接口，强依赖 Socket 连接且不执行磁盘落盘；

DailyDataManager 是量化回测的统一离线数据层，零网络冷启动、具备长效磁盘缓存、支持防封批量调度，且深度支持精确历史换手率计算（详见前文 Q6 章节说明）。

2. 扩展市场行情接口 (`ExtQuotes`)

接口方法	数据内容
`markets()`	实时市场列表：所有可用的市场标识及名称。
`instrument_count()`	商品总数量。
`instrument(start, offset)`	证券代码/合约列表（分页）。
`instruments()`	全量证券/合约列表（自动翻页）。
`quote(market, symbol)`	五档行情：最新价、买卖五档、持仓量、成交量等。
`minute(market, symbol)`	当天分时数据。
`minutes(market, symbol, date)`	历史分时数据。
`bars(frequency, market, symbol, start, offset)`	扩展市场 K 线数据。
`transaction(market, symbol, start, offset)`	分笔成交。
`transactions(market, symbol, date, start, offset)`	历史分笔成交。

三、本地历史数据读取接口 (`mootdx2.reader.Reader`)

通过 Reader.factory(market='std'|'ext', tdxdir=...) 创建本地数据读取器。解析通达信本地客户端的二进制数据文件（.day / .lc1 / .lc5 等），实现纯离线/极速数据读取。

1. 标准市场本地读取 (`StdReader`)

接口方法	参数与选项	数据内容
`daily(symbol, auto_download, turnover, adjust)`	`auto_download=False` `turnover=False` `adjust='qfq'/'hfq'/None`	本地日线 K 线（包含成交额 `amount`，支持前/后复权）。指定 `turnover=True` 时自动结合本地 `gbbq` 股本变迁计算精确历史换手率 `turnover_rate`；本地缺失且 `auto_download=True` 时自动联网下载并缓存（24h TTL）。
`minute(symbol, suffix)`	`suffix=1` 或 `5`	本地分钟 K 线：`suffix=1` 读 1 分钟线，`suffix=5` 读 5 分钟线。
`fzline(symbol)`	`symbol`: 股票代码	本地 5 分钟 K 线（`minute(symbol, suffix=5)` 的便捷别名）。
`xdxr(symbol)`	`symbol`: 股票代码	本地除权除息数据：优先读取本地缓存，未命中则联网拉取并写缓存。
`block(symbol, group=False)`	`group`: 是否分组	本地板块/成分股数据：解析 `block_zs.dat`、`block_fg.dat`、`block_gn.dat` 等板块文件。
`block_new(name, symbol, group=False)`	板块名称与成分股	自定义板块读写：查询或创建通达信本地自定义板块成分股（写入 `.blk` + `blocknew.cfg`）。

2. 扩展市场本地读取 (`ExtReader`)

接口方法	数据内容
`daily(symbol)`	本地扩展市场日线数据。
`minute(symbol)`	本地扩展市场 1 分钟 K 线。
`fzline(symbol)`	本地扩展市场 5 分钟 K 线。

四、通达信底层协议驱动与离线解析 (`mootdx2.tdx`)

提供脱离高层封装、直接对接底层协议驱动与本地二进制文件的原生能力，适合高性能数据处理或深度协议定制场景。

1. 底层驱动工厂 (`mootdx2.tdx.factory`)

from mootdx2.tdx.factory import create_hq_client

# 创建原生/兼容协议客户端
client = create_hq_client(driver="native", auto_retry=True)  # 可选 "native" 或 "tdxpy"
with client.connect(host="119.147.212.81", port=7709):
    bars = client.get_security_bars(category=9, market=1, code="600036", start=0, count=10)

驱动选项	说明
`driver="native"`	内置纯净驱动：mootdx2 原生纯 Python 编写的协议实现 (`NativeTdxHqAPI`)，无外部第三方重打包依赖。
`driver="tdxpy"`	经典兼容驱动：加载外部兼容驱动，并自动激活纯净防污染握手补丁。

2. 底层离线二进制解析器 (`mootdx2.tdx.offline`)

直接读取通达信客户端数据文件并解析为 SecurityBar 数据结构：

from mootdx2.tdx.offline import read_daily_bars, read_5min_bars, find_daily_bar_file

# 1. 直接解析日线文件 (.day)
bars = read_daily_bars("tests/fixtures/vipdoc/sh/lday/sh000001.day")

# 2. 直接解析 5 分钟线文件 (.lc5)
min_bars = read_5min_bars("tests/fixtures/vipdoc/sh/fzline/sh688001.lc5")

# 3. 自动定位标的日线文件路径
file_path = find_daily_bar_file(market=1, code="000001", vipdoc="tests/fixtures/vipdoc")

核心接口	功能说明
`read_daily_bars(file_path)`	直接解析 `.day` 二进制文件，返回 `List[SecurityBar]`（包含年月日、开高低收、成交量、成交金额）。
`read_min_bars(file_path)`	直接解析 1 分钟 `.lc1` 二进制文件，返回分钟级 `List[SecurityBar]`。
`read_5min_bars(file_path)`	直接解析 5 分钟 `.lc5` 二进制文件，返回 5 分钟级 `List[SecurityBar]`。
`find_daily_bar_file(market, code, vipdoc)`	根据市场标识 (`0` 深圳, `1` 上海) 与证券代码，在 `vipdoc` 目录下快速定位对应 `.day` 文件路径。

五、巨潮资讯独立公告数据源 (`mootdx2.cninfo.CninfoClient`)

独立于通达信协议的 HTTP 公告检索客户端（基于标准库 urllib，零第三方依赖）。动态对接巨潮官方权威 orgId 映射表，支持全市场股票（尤其 601xxx、688xxx 段）历史公告检索与 PDF 附件直链获取。

from mootdx2 import CninfoClient

client = CninfoClient(timeout=15.0)

# 1. 获取 DataFrame 格式公告列表
df = client.get_announcements(code="600519", count=10, page=1, to_df=True)
print(df[["date", "type", "title", "pdf_url"]])

# 2. 获取结构化 Announcement 对象列表
records = client.get_announcements(code="688017", count=3, page=1, to_df=False)
for item in records:
    print(item.date, item.title, item.pdf_url)

核心方法与数据模型

方法 / 属性	参数说明	功能与返回说明
`get_announcements(...)`	`code`: 股票代码 (如 `'600519'`) `count`: 获取条数 (默认 `10`) `page`: 分页页码 (从 `1` 开始) `to_df`: 是否转为 DataFrame (默认 `True`)	历史公告检索：当 `to_df=True` 时返回 `pd.DataFrame`，字段包含 `id`, `code`, `name`, `date`, `type`, `title`, `url`, `pdf_url` 等；当 `to_df=False` 时返回 `List[Announcement]` 对象列表。
`Announcement` 数据类	数据结构模型属性	`id`: 公告编号 `secCode`/`secName`: 股票代码及简称 `title`: 公告标题 `type`: 公告类型（如年报、决议、分红） `date`: 发布日期 `url`: 巨潮网页端详情 URL `pdf_url`: 原始 PDF 附件直链

六、专业财务数据报表解析 (`mootdx2.financial` / `mootdx2.affair`)

提供对通达信专业财务数据（gpcw*.zip / gpcw*.dat）的高性能解析，覆盖 580+ 专业财务科目，并原生提供中文/英文表头映射。

1. 专业财务模块 (`mootdx2.financial`)

from mootdx2.financial import FinancialList, FinancialReader

# 1. 探查服务器最新发布的财务包清单
financial_list = FinancialList()
records = financial_list.parse(financial_list.content())
# 每条记录包含: filename (如 gpcw20240630.zip), filesize, hash

# 2. 解析本地财务文件为 DataFrame（支持中文表头）
df = FinancialReader.to_data("tmp/affairs/gpcw20240630.zip", header="zh")
print(df[["基本每股收益", "每股净资产", "净资产收益率", "主营业务收入", "净利润"]])

接口类 / 方法	功能说明
`FinancialList.content()` / `parse()`	探查通达信服务器上的 `tdxfin/gpcw.txt` 报表发布清单，解析包含文件名、大小及 MD5 哈希的列表。
`FinancialReader.to_data(filepath, header="zh"	"en")`
`Financial.content(filename, downdir)`	从服务器下载指定的财务压缩包文件。

2. 基础财务接口 (`mootdx2.affair.Affair`)

接口方法	功能说明
`Affair.files()`	获取可用的历史财务文件列表。
`Affair.fetch(downdir, filename)`	下载指定财务文件，未指定则批量下载全量财务包。
`Affair.parse(downdir, filename)`	解析指定的财务 `.zip` 文件，返回完整财务 DataFrame。

3. 580+ 财务字段大类拆解

每股与核心收益指标：基本每股收益、扣除非经常性损益每股收益、每股净资产、每股未分配利润、每股资本公积金、每股经营现金流量、净资产收益率 (ROE)。
资产负债表核心：货币资金、交易性金融资产、应收账款、存货、长期股权投资、固定资产、无形资产、短期借款、长期借款、实收资本（股本）、归属于母公司所有者权益合计 等。
利润表核心：营业收入、营业成本、销售/管理/财务费用、投资收益、营业利润、利润总额、归属于母公司所有者的净利润。
现金流量表核心：经营活动现金流入/出及净额、购建固定资产支付现金、取得借款收到现金、现金及现金等价物净增加额。
财务衍生与分析比率：流动比率、速动比率、资产负债率、存货周转率、营收增长率(%)、净利润增长率(%)、销售毛利率/净利率。
金融行业专用科目：银行（吸收存款、贷款垫款、利息净收入）、保险（已赚保费、准备金净额）、证券（代理买卖证券款、融出资金）。

七、增量防封数据同步工具 (`mootdx2.sync`)

针对大批量标的的高频同步场景，内置并发节流防封策略与长效磁盘缓存。

from mootdx2 import sync_daily, sync_xdxr

# 1. 批量同步日 K 线（分批防封调度）
sync_res = sync_daily(
    symbols=["600000", "600036", "000001"],
    offset=800,
    delay=0.08,        # 单任务微延时
    batch_size=50,     # 每 50 只标的一组
    batch_delay=1.0,   # 组间休眠 1 秒
    cache=True,
    show_progress=True,
)

# 2. 批量同步除权除息因子（90天长效缓存，已存在有效缓存自动跳过）
xdxr_stat = sync_xdxr(
    symbols=["600036", "510300"],
    force=False,
    workers=4,
    delay=0.05,
)

接口方法	参数说明	功能与返回说明
`sync_daily(...)`	`symbols`: 标的代码列表 `offset`: 同步条数 `delay`: 单请求延时 `batch_size`: 批次大小 `batch_delay`: 批次间休眠 `cache`: 是否写入长效缓存	批量增量更新日 K 线：返回字典 `{'total': int, 'success': int, 'data': Dict[str, pd.DataFrame]}`，支持长效缓存防封。
`sync_xdxr(...)`	`symbols`: 标的代码列表 `file`: 包含代码的文本文件路径 `force`: 强制覆盖已有缓存 `workers`: 并发线程数 (默认 `4`) `delay`: 节流微延时	批量预同步除权除息因子：90 天长效缓存，智能过滤已缓存标的，返回包含成功数、跳过数及文件映射的统计字典。

八、复权计算与因子能力

mootdx2 统一了股票与 ETF 的全套复权计算流水线：

1. 透传式复权（推荐用法）

所有日线及历史 K 线接口均支持 adjust 参数：

# 1. 在线获取招商银行前复权日 K 线
quotes = Quotes.factory("std")
df_qfq = quotes.bars(symbol="600036", frequency=9, adjust="qfq")

# 2. 离线读取沪深 300ETF 前复权日 K 线
reader = Reader.factory("std", tdxdir="~/new_tdx")
df_etf = reader.daily(symbol="510300", adjust="qfq")

adjust 参数支持的值：'qfq' / '01' / 'before'（前复权），'hfq' / '02' / 'after'（后复权）。

2. 股票与 ETF 通用复权流水线 (`mootdx2.tools.reversion`)

接口方法	功能说明
`reversion(symbol, stock_data, xdxr, type_)`	通用复权主入口：自动识别标的类型。若是 ETF 基金（15/16/50/51/56/588 等）则自动走扩缩股折算逻辑；若是股票则按送转股、分红派息、配股综合流水线计算。
`etf_reversion(data, xdxr, adjust)`	ETF 专属复权：基于 `xdxr` 中 `category==11`（基金折算/分红）的扩缩股比例与现金分红执行前/后复权。
`_reversion(bfq_data, xdxr_data, type_)`	A 股股票经典复权算法：基于送转股比例、现金分红与配股价计算复权因子与调整价。
`factor_reversion(symbol, method, raw)`	Sina 预计算因子兜底：当本地或通达信 XDXR 数据缺失时，自动回退使用新浪预计算因子完成复权。

3. 复权因子序列获取 (`mootdx2.utils.factor` / `mootdx2.contrib.adjust`)

接口方法	数据内容与来源
`fq_factor(symbol, method)`	获取单只股票或 ETF 的历史前/后复权因子时间序列（从新浪获取，24h 本地缓存），自动适配股票与 ETF 字段差异。
`get_adjust_year(symbol, year, factor)`	从同花顺获取指定年份的前/后复权 OHLCV 数据，作为备选复权数据源。

九、交易日历与节假日数据 (`mootdx2.utils.holiday`)

接口方法	返回值与功能说明
`holidays()`	沪深 A 股全量历史交易日历（从新浪获取并 JS 解密），返回包含交易日期的 DataFrame，本地 24h 缓存。
`holiday2(date)`	查询指定日期是否为交易日，返回匹配的 DataFrame 行。
`holiday(date, country)`	多国交易日历（通达信官方源），判断指定日期是否休市，返回布尔值。
`holiday_(date, country)`	同 `holiday()`，但返回匹配的 DataFrame 记录行。

十、北交所实时行情 (`mootdx2.utils.stock_bj_a`)

接口方法	数据内容
`stock_bj_a()`	北交所全部股票实时全景行情（东方财富通道），包含：最新价、涨跌幅、成交量、成交额、换手率、市盈率(动态)、量比、5分钟涨跌、市净率、总市值、流通市值、年初至今涨跌幅等。

十一、自定义板块管理 (`mootdx2.tools.customize`)

对接通达信客户端本地 blocknew.cfg 与自定义板块 .blk 文件：

接口方法	功能说明
`Customize.search(name, group)`	查询自定义板块：按板块名称搜索，支持分组返回。
`Customize.create(name, symbol)`	创建自定义板块：写入板块名称与成分股代码列表。
`Customize.update(name, symbol, overflow)`	更新自定义板块：追加或全量覆盖成分股代码。
`Customize.remove(name)`	删除自定义板块：清理板块记录及关联 `.blk` 二进制文件。

十二、数据导出与格式转换工具

1. 多格式 DataFrame 导出 (`mootdx2.utils.to_file`)

支持扩展名	格式说明
`.csv`	标准逗号分隔 CSV 文件（UTF-8 编码）
`.xlsx` / `.xls`	Microsoft Excel 电子表格
`.h5`	高性能 HDF5 数据集
`.json`	JSON 格式文本（records 数组）

2. 通达信导出文件转 CSV (`mootdx2.tools.tdx2csv`)

接口方法	功能说明
`txt2csv(infile, outfile)`	将通达信导出的 GBK 编码 `.txt` 转换为标准 `date, open, high, low, close, volume, amount` CSV。
`batch(src, dst)`	异步多任务批量转换指定目录下的所有通达信导出文件。

十三、服务器管理与高可用基础设施

1. 最优服务器测速与健康检查 (`mootdx2.server`)

接口方法	功能说明
`bestip(limit, console, sync)`	测速并选出最快服务器：针对 HQ（标准行情）、EX（扩展行情）、GP（财务数据）三类节点测速，写入 `~/.mootdx2/config.json`。
`check_server(sync)`	服务器连通性快速探测。
`ServerManager`	运行期请求级故障自动转移：连续失败达阈值后自动重连至备用最优节点。

2. 多级缓存策略

内存与 DataFrame 缓存 (pd_cache)：按函数签名与参数哈希自动缓存 Pandas 结果，过期自动刷新。
文件级持久化缓存 (file_cache / Pickle)：除权除息因子、交易日历、复权因子均支持长效缓存（~/.mootdx2/caches/），实现首次联网、后续秒级离线。
日线增量同步缓存：sync_daily 与 DailyDataManager 自动将增量拉取的数据落地到磁盘，保障高频调用不被主站流控。

3. CLI 命令行便捷工具

# 在线获取行情
mootdx2 quotes -s 600000 -a bars

# 读取本地数据
mootdx2 reader -s 600000 -a daily

# 探测并保存最优服务器
mootdx2 bestip

# 财务文件探查、下载与解析
mootdx2 affair -l
mootdx2 affair -f gpcw20231231
mootdx2 affair -p gpcw20231231 -o out.csv

# 批量拉取行情数据
mootdx2 bundle -s 600000,000001 -o output/

关于 Level-2 与板块资金流向说明

通达信开放的通信接口基于 Level-1 基础行情，不存在直接的"板块资金流向"汇总接口。资金流向指标需基于 transactions（逐笔分笔成交数据及买卖挂单方向）在客户端自行计算统计，或对接外部 Level-2 / 衍生金融数据源。

十四、客户端精准对接与核心子模块导入规范

为彻底杜绝外部客户端（如 kdata、自定义量化引擎）因全局顶层 __init__.py 损坏带来的级联导入故障，同时兼顾冷启动性能与模块解耦，推荐客户端按核心子目录进行精准按需导入。

1. 核心子模块精准导入速查表

功能域 / 业务场景	生产级推荐引入路径	核心暴露对象 / 接口
通达信底层离线二进制解析	`from mootdx2.tdx.offline import ...`	`read_daily_bars`（日线解析）、`read_min_bars`（1分线）、`read_5min_bars`（5分线）、`find_daily_bar_file`（定位.day路径）
通达信底层协议驱动工厂	`from mootdx2.tdx.factory import ...`	`create_hq_client`（创建纯原生 Python 或兼容协议客户端）
通达信底层传输与状态同步	`from mootdx2.tdx.transport import ...`	`sync`（底层握手与协议保活探针）
本地通达信目录综合读取器	`from mootdx2.reader import ...`	`Reader`（支持标准/扩展市场日线与分时 DataFrame 读取）
统一日 K 线管理器 (离线+增量)	`from mootdx2.daily import ...`	`DailyDataManager`（离线优先、自动增量补全、防封节流调度）
通用股票与 ETF 精密复权	`from mootdx2.tools.reversion import ...`	`reversion`（全自动除权除息/扩缩股流水线）、`etf_reversion`
通达信自定义板块管理	`from mootdx2.tools.customize import ...`	`Customize`（读写 `blocknew.cfg` 与 `.blk` 文件）
巨潮资讯公告与研报直链	`from mootdx2.cninfo import ...`	`CninfoClient`（全市场股票公告检索与官方 PDF 附件获取）
交易日历与休市判定	`from mootdx2.utils.holiday import ...`	`holiday`（交易日判定）、`holidays`（历史全量交易日序列）
专业财务数据报表解析	`from mootdx2.financial import ...`	`FinancialReader`（580+ 财务字段中英文映射）、`FinancialList`
在线实时与历史行情客户端	`from mootdx2.quotes import ...`	`Quotes`（标准/扩展市场 Level-1 实时盘口、分笔成交、K线）
最优服务器测速与配置	`from mootdx2.server import ...`	`bestip`、`check_server`、`ServerManager`
量化核心指标与批量计算	`from mootdx2.metrics import ...`	`etf_premium`（一键折溢价）、`calculate_turnover_by_amount`、`calculate_realtime_turnover`、`calculate_turnover_rate`、`fetch_etf_iopv`、`calculate_etf_premium`、`calculate_cbond_premium`、`batch_offline_metrics`、`batch_online_metrics`

2. 核心子目录常用对接代码范例

(1) 底层二进制极速直读 (`mootdx2.tdx.offline`)

直接解析本地通达信 .day、.lc1、.lc5 二进制文件为结构化对象，适合底层高性能量化回测：

from mootdx2.tdx.offline import read_daily_bars, read_5min_bars, find_daily_bar_file

# 直接解析通达信日线文件
bars = read_daily_bars("/path/to/vipdoc/sh/lday/sh600036.day")
for bar in bars[-3:]:
    print(bar.datetime, bar.open, bar.high, bar.low, bar.close, bar.vol)

# 根据代码与市场 (0=深圳, 1=上海) 定位本地 .day 路径
day_path = find_daily_bar_file(market=1, code="600036", vipdoc="/path/to/vipdoc")

(2) 日 K 线智能管理与增量防封同步 (`mootdx2.daily`)

量化工程首选入口，离线优先秒级直读，过期自动联网增量拉取并落地长效缓存：

from mootdx2.daily import DailyDataManager

manager = DailyDataManager(tdxdir="tests/fixtures")
# 获取前复权日线 DataFrame (支持 turnover=True 自动附带精确换手率)
df_qfq = manager.get_daily("600036", adjust="qfq", turnover=True, auto_download=True)

(3) 股票与 ETF 通用精密复权 (`mootdx2.tools.reversion`)

自动识别标的类型，支持 ETF 扩缩股折算与股票送转股、分红配股复权：

from mootdx2.tools.reversion import reversion

df_adjusted = reversion(symbol="510300", stock_data=df_raw, xdxr=df_xdxr, type_="qfq")

(4) 交易日历判定与全量序列 (`mootdx2.utils.holiday`)

from mootdx2.utils.holiday import holiday, holidays

is_trade_day = holiday("2024-10-01", country="China")  # 国庆休市 -> False
df_calendar = holidays()  # 获取历史完整交易日历 DataFrame

(5) 巨潮资讯独立公告检索 (`mootdx2.cninfo`)

from mootdx2.cninfo import CninfoClient

client = CninfoClient(timeout=15.0)
df_announcements = client.get_announcements(code="600519", count=10, to_df=True)

(6) 量化核心指标与批量计算 (`mootdx2.metrics`)

from mootdx2 import etf_premium
from mootdx2.metrics import (
    calculate_realtime_turnover,
    calculate_etf_premium,
    calculate_cbond_premium,
    batch_offline_metrics,
    batch_online_metrics,
)

# 1. 一键获取 ETF 实时/收盘折溢价率 (单标的返回字典，批量返回宽表 DataFrame)
res_single = etf_premium("159513")
df_batch = etf_premium(["513100", "159513", "510300"])

# 2. 实时换手率与纯公式计算
hsl = calculate_realtime_turnover(vol_hand=538019, float_shares=20628945000)
premium = calculate_etf_premium(price=4.55, nav=4.549)

# 3. 纯离线全市场批量扫描 (毫秒级零网络开销)
df_offline = batch_offline_metrics(tdxdir="tests/fixtures", limit=50)

# 4. 在线全景批量监控并导出 CSV
df_online = batch_online_metrics(symbols=["600036", "510300", "513100"], export_csv="output.csv")

十五、量化核心指标计算与批量导出 (`mootdx2.metrics`)

专为量化交易选股、盘口监控与回测因子构建提供高纯度、高内聚的基础指标计算与全市场批量扫描能力。

API 精简与分层规范：

顶层唯一推荐入口：from mootdx2 import etf_premium（单标的/多标的统一自适应，极简调用）。

底层与独立工具：calculate_etf_premium（纯公式）、calculate_cbond_premium（可转债纯公式）、fetch_etf_iopv（独立净值抓取）收敛至子模块 from mootdx2.metrics import ...。

1. 核心导出函数列表

函数名称	推荐引入路径	参数说明	计算公式与返回说明
`etf_premium(...)`	`from mootdx2 import etf_premium` (或 `mootdx2.metrics`)	`symbol` / `symbols`: 单个代码 (如 `'159513'`) 或代码列表 `client`: Quotes 客户端实例 (可选) `export_csv`: 导出 CSV 路径 (仅批量有效) `max_workers`: 并发获取财务线程数 (默认 8)	🌟 ETF 一键折溢价率 (顶层唯一推荐入口)： • 单标的：传入单个代码返回包含 `code`、`price`、`iopv`、`nav`、`basis`、`premium_rate` 的结构化字典； • 批量：传入列表返回按折溢价率降序排列的宽表 DataFrame。底层自动融合通达信行情、披露 NAV 与交易所 15 秒推算 IOPV，彻底消除跨境 QDII 跨时区时滞误差。 (注：`batch_etf_premium` 在子模块作为别名完全兼容)
`fetch_etf_iopv(...)`	`from mootdx2.metrics import fetch_etf_iopv`	`symbol`: 基金代码或代码列表 (如 `'513100'` 或 `['513100', '159513']`) `timeout`: 网络超时 (默认 3.0 秒)	交易所实时参考净值 (IOPV)：获取交易所每 15 秒更新的估算净值。各大券商 App 盘中计算实时折溢价率均以此为基准。支持传入单个代码返回 `float`，或传入列表单请求合并打包返回 `dict`。
`calculate_etf_premium(...)`	`from mootdx2.metrics import calculate_etf_premium`	`price`: 二级市场成交价 (元) `nav`: 基金公司公布的历史净值 NAV (元) `iopv`: 交易所实时参考净值 IOPV (元) `basis`: 基准分母 (`'nav'`/`'iopv'` 默认, 或 `'price'`)	ETF / LOF 纯数学折溢价公式 (%)：`((price - ref) / ref) * 100%`。无网络 I/O，适用于已有现成行情数据的场景直接套公式。同时传入 `nav` 与 `iopv` 时优先采用 `iopv`。
`calculate_cbond_premium(...)`	`from mootdx2.metrics import calculate_cbond_premium`	`bond_price`: 可转债现价 (元) `stock_price`: 正股现价 (元) `conversion_price`: 当前有效转股价 (元)	可转债转股溢价率：转股价值 = `(100 / 转股价) * 正股现价` 转股溢价率 (%) = `(转债价格 - 转股价值) / 转股价值 * 100%`。返回字典 `{"conversion_value": float, "premium_rate": float}`。
`calculate_turnover_by_amount(...)`	`from mootdx2 import calculate_turnover_by_amount`	`amount`: 当日成交额 (如 32.12 亿元) `market_cap`: 流通市值或基金规模 (如 180.52 亿元)	金融第一性原理换手率 (%)：`(amount / market_cap) * 100%`。消除物理单位差异，无网络 I/O，极速且鲁棒。
`calculate_realtime_turnover(...)`	`from mootdx2 import calculate_realtime_turnover`	`vol_hand`: 当日成交量 (单位: 手) `float_shares`: 实际流通总股本或总份额 (单位: 股/份) `amount`: 当日成交额 (可选) `market_cap` / `scale`: 流通市值或基金规模 (可选)	实时换手率 (%)：支持标准量基准 `((vol_hand * 100) / float_shares) * 100%` 或传入 `amount` + `market_cap`/`scale` 自动走金额第一性原理。安全防除零与负值。

**换手率计算架构与第一性原理对比说明（特别针对 ETF / 债券 / 货币基金等多资产）**

旧版本：查盘口 → 查 F10 财务 → 单位转换（猜单位/强乘100）→ 算换手率。不仅慢，且处处是雷（尤其针对债券 ETF、货币 ETF、跨境 QDII 等非股票品种，单位在手/张/份之间混乱，极易引发 100 倍量纲级计算偏差）。
新版本：直接提取盘口的 amount 与已知的资产 scale，一步除法：
```
           Amount
  换 手 率  = ────── × 100%
           Scale
```
（推荐调用 calculate_turnover_by_amount 或 calculate_realtime_turnover(amount=..., scale=...)），零额外网络开销，全资产标的无歧义、极速且 100% 鲁棒。 | calculate_turnover_rate(...) | daily_df: 包含 volume 的日 K 线 DataFrame
gbbq_path: 本地 vipdoc/cw/gbbq 文件路径
symbol: 证券代码 | 离线历史精确换手率序列：基于本地 gbbq 股本变迁文件，利用 pd.merge_asof(direction="backward") 向量化回溯历史有效流通盘，为日 K 线追加 turnover_rate 列，完全消除未来函数。 | | batch_offline_metrics(...) | tdxdir: 本地通达信安装或数据目录
symbols: 待扫描标的列表 (默认扫描全部 .day)
limit: 最大标的数量上限 (用于测试与抽样)
max_workers: 并发线程数 (默认 4) | 纯离线全市场批量扫描：100% 本地文件极速直读，零网络开销。批量提取最新收盘价、成交额 (亿元)、MA5成交额、基于 gbbq 的精确换手率与 MA5换手率宽表。 | | batch_online_metrics(...) | symbols: 标的代码列表
client: Quotes 客户端实例 (可选)
export_csv: 导出 CSV 文件路径 (可选)
max_workers: 并发获取财务/净值线程数 (默认 8) | 在线分块并发批量监控：底层集成 80 只标的分块打包协议，并发聚合最新价、涨跌幅、成交额 (亿元)、实时换手率 (%)、基金净值与 ETF 折溢价率 (%)，支持导出 CSV。 |

2. 常用调用代码范例

(1) ETF 折溢价率一键计算 (`etf_premium`)

from mootdx2 import etf_premium

# 1. 查单只 ETF（传代码字符串，自动返回结构化字典）:
res = etf_premium("159513")
print(res)
# {'code': '159513', 'price': 1.821, 'iopv': 1.6579, 'nav': 1.63, 'basis': 'IOPV', 'premium_rate': 9.84}

# 2. 查多只 ETF（传代码列表，自动输出按溢价率降序排列的宽表 DataFrame）:
df = etf_premium(["513100", "159513", "510300", "159915"])
print(df)
#      code  price    iopv    nav basis  premium_rate
# 0  513100  2.269  1.9839  1.952  IOPV         14.37
# 1  159513  1.821  1.6579  1.630  IOPV          9.84
# 2  510300  4.582  4.5791  4.551  IOPV          0.06
# 3  159915  3.391  3.3909  3.331  IOPV          0.00

(2) 独立数据抓取与底层纯公式 (子模块引入)

from mootdx2.metrics import (
    calculate_turnover_by_amount,
    calculate_realtime_turnover,
    calculate_etf_premium,
    calculate_cbond_premium,
    fetch_etf_iopv,
)

# 1. 独立获取交易所实时参考净值 (IOPV):
# (A) 单只代码 -> 返回 float
iopv_val = fetch_etf_iopv("513100")  # 1.9839
# (B) 代码列表 -> 单次 HTTP 打包返回 dict
iopv_dict = fetch_etf_iopv(["513100", "159513"])  # {'513100': 1.9839, '159513': 1.6579}

# 2. 已有行情数据时直接套用纯数学公式:
prem = calculate_etf_premium(price=2.269, iopv=1.9839)  # 14.37%

# 3. 可转债转股价值与溢价率:
cbond_metric = calculate_cbond_premium(bond_price=125.0, stock_price=25.0, conversion_price=20.0)
print("转股价值:", cbond_metric["conversion_value"])  # 125.0
print("转股溢价率:", cbond_metric["premium_rate"])     # 0.0%

# 4. 实时换手率:
# 金额/规模第一性原理 (全资产标的无歧义)
hsl_amt = calculate_turnover_by_amount(amount=32.12, market_cap=180.52)  # 17.79%
# 经典量基准
hsl = calculate_realtime_turnover(vol_hand=538019, float_shares=20628945000)  # 0.2608%

(3) 纯离线全市场批量扫描与量化筛选 (`batch_offline_metrics`)

适用于全市场/自选资金池的最新横截面指标快速扫描、选股初筛与流动性排序。100% 直读本地通达信二进制文件与 vipdoc/cw/gbbq 股本变迁，零网络开销：

from mootdx2 import batch_offline_metrics
import pandas as pd

# 1. 扫描通达信数据目录 (传 None 自动探测本地安装或测试目录)
print("正在执行纯离线批量极速扫描...")
df = batch_offline_metrics(
    tdxdir="/path/to/tdx",   # 通达信数据目录 (包含 vipdoc)
    symbols=None,            # 传 None 自动扫描全部 .day; 也可传入自选标的列表
    limit=None,              # 抽样上限 (可选)
    max_workers=8,           # 并发线程数
)

# 2. 经典量化指标初筛 (成交额 > 1 亿 且 换手率 > 2.0%)
filtered_df = df[
    (df["amount_yi"] >= 1.0) & 
    (df["turnover_rate"] >= 2.0)
].sort_values("amount_yi", ascending=False).reset_index(drop=True)

# 3. 输出资金最活跃的前 10 只标的
cols = ["symbol", "latest_date", "close", "amount_yi", "ma5_amount_yi", "turnover_rate", "ma5_turnover_rate"]
print(filtered_df[cols].head(10).to_string(index=False))

# 4. 导出为 CSV / Excel 报告
filtered_df.to_csv("offline_metrics_summary.csv", index=False, encoding="utf-8-sig")

batch_offline_metrics 输出字段详解：

列名	含义	字段说明与计算原理
`symbol`	证券代码	6 位代码（如 `600036`, `510300`）
`latest_date`	最新交易日	本地 `.day` 记录的最新收盘日期
`close`	最新收盘价	元
`amount_yi`	当日成交额	亿元（本地二进制金额折算）
`ma5_amount_yi`	5 日均成交额	亿元（近 5 个交易日平滑成交金额，反映资金持续性）
`turnover_rate`	精准换手率	%（基于本地 `gbbq` 股本变迁回溯计算，非估算值，无未来函数）
`ma5_turnover_rate`	5 日均换手率	%（近 5 日换手率均值，用于研判放量异动）

(4) 纯离线批量历史 K 线时序提取 (`DailyDataManager.get_daily_batch`)

适用于多标的策略回测、特征工程与 Alpha 因子挖掘，为每只标的提供完整的历史日 K 线时序面板：

from mootdx2 import DailyDataManager

# 初始化数据管理器
mgr = DailyDataManager(tdxdir="/path/to/tdx")

symbols = ["513100", "510300", "600036", "000001"]

# 批量提取纯离线日线时序字典
batch_dict = mgr.get_daily_batch(
    symbols=symbols,
    auto_download=False, # 👈 强制纯离线模式，严禁发起任何网络请求
    turnover=True,      # 👈 自动逐日回溯本地 gbbq 计算精确换手率序列
    adjust="qfq",       # 👈 本地自动前复权
    offset=800,         # 👈 获取最近 800 个交易日
)

# 查看某只标的的完整历史 DataFrame
df_513100 = batch_dict["513100"]
print(df_513100[["open", "high", "low", "close", "volume", "amount", "turnover_rate"]].tail())

(5) 在线批量全景监控（股票 + ETF 宽表一键导出）

适用于实盘盘中实时监控，自动分块并发获取 Level-1 盘口、实时换手率、实时 IOPV 与 ETF 折溢价率：

from mootdx2 import batch_online_metrics

symbols = [
    "600036", "600519", "000001", "300750",
    "510300", "510050", "159915", "513100", "513050",
]

# 自动分块批量获取实时成交额、换手率与 ETF 实时 IOPV 折溢价率
df_online = batch_online_metrics(symbols=symbols, export_csv="output/realtime_metrics.csv")
print(df_online[["code", "price", "change_pct", "amount_yi", "turnover_rate", "iopv", "premium_rate"]])

3. 向下兼容性保障 (Backward Compatibility)

为了保证现有量化项目（如基于旧版 pytdx / mootdx 编写的外部系统）无缝平滑升级，mootdx2 的数据标准化转换层自动提供了双向兼容字段别名：

`mootdx2` 标准字段	兼容历史字段名	所在接口	说明
`rise_speed`	`reversed_bytes9`	`Quotes.quotes()`	涨速字段，兼容老脚本的 `row.get("reversed_bytes9")`
`meigujing_zichan`	`meigujingzichan`	`Quotes.finance()`	每股净资产/基金净值，兼容无下划线格式
`liutong_guben`	`liutongguben`	`Quotes.finance()`	流通股本，兼容无下划线格式
`zong_guben`	`zongguben`	`Quotes.finance()`	总股本，兼容无下划线格式

Development Status
- 2 - Pre-Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Natural Language
- English
Programming Language

Release files for mootdx2 1.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mootdx2 1.6.3
File	Size	Uploaded
mootdx2-1.6.3.tar.gz	13.6 MB	Sep 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mootdx2 1.6.3
File	Interpreter	ABI	Platform	Reset
mootdx2-1.6.3-py3-none-any.whl 244.1 kB Sep 19, 2026	Python 3	none	any	Details

Total release size:13.8 MB

Release files / mootdx2-1.6.3.tar.gz

Download URL	mootdx2-1.6.3.tar.gz
Size	13.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`6bfb3874d54999dd6436d18c0723dd64cd55c9ee1a5821f5598f1a3956a6414e`
BLAKE2b-256 checksum How to use checksums	`bebcd5c794e234ebc0cfcdb87d03e62d3b7248f16ed9a0f19fcde3f2619c0d79`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / mootdx2-1.6.3-py3-none-any.whl

Download URL	mootdx2-1.6.3-py3-none-any.whl
Size	244.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`838a51ccdc20071e3754a0917319b202caed61116a0a4efa2be167a67febb74c`
BLAKE2b-256 checksum How to use checksums	`d00615c478d8c65099241f10bd6322bea310fde8ff7bc5c6117491a63adbbdc2`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`