Metadata-Version: 2.5
Name: mootdx2
Version: 1.5.0
Summary: 通达信数据读取接口.
Project-URL: Homepage, https://www.mootdx.com
Project-URL: Repository, https://github.com/mootdx/mootdx
Author-email: bopo <ibopo@126.com>
License-File: AUTHORS.rst
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: click>=8.1.3
Requires-Dist: filelock>=3.12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mini-racer>=0.12.0
Requires-Dist: prettytable>=3.5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tdxpy>=0.2.5
Requires-Dist: tenacity>=8.1.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: typing-extensions>=4.5.0
Description-Content-Type: text/markdown

[English](./README_EN.md)

# Mootdx2

[![PyPI version](https://img.shields.io/pypi/v/mootdx2.svg)](https://pypi.org/project/mootdx2/)
[![Python Version](https://img.shields.io/pypi/pyversions/mootdx2.svg)](https://pypi.org/project/mootdx2/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Language](https://img.shields.io/badge/Language-Python%203-blue.svg)](https://www.python.org/)

通达信行情与历史数据读取工具包，面向高频量化回测与生产分析，提供在线实时行情、本地二进制数据毫秒级解析、专业历史财务报表提取、全系股票与 ETF 精准复权、巨潮资讯官方公告检索以及增量防封同步能力。

---

## 项目概述

`mootdx2` 为量化交易系统和金融研究提供高可用、多源融合的底层数据基础设施。

```text
                               ┌────────────────────────────────────────┐
                               │       mootdx2 核心架构与数据流景       │
                               └────────────────────────────────────────┘
                                                    │
         ┌───────────────────────────┬──────────────┴──────────────┬───────────────────────────┐
         │                           │                             │                           │
         ▼                           ▼                             ▼                           ▼
┌──────────────────┐       ┌──────────────────┐          ┌──────────────────┐        ┌──────────────────┐
│  离线数据管理    │       │   在线行情驱动   │          │   专业财务数据   │        │   官方公告数据   │
│ DailyDataManager │       │  Quotes / tdx    │          │ Financial/Affair │        │   CninfoClient   │
└──────────────────┘       └──────────────────┘          └──────────────────┘        └──────────────────┘
         │                           │                             │                           │
  • 本地 .day 毫秒解析        • 原生/兼容双模协议驱动       • 580+ 科目全字段覆盖        • 零三方依赖 HTTP 客户端
  • 自动时效与增量补齐        • 实时五档与全周期 K 线       • 中英文字段表头映射         • 权威 orgId 动态映射
  • 磁盘长效缓存 (Pickle)     • 自动故障转移与节点测速      • 远程报表发布清单探查       • 公告检索与 PDF 原件直链
         │                           │                             │                           │
         └───────────────────────────┴──────────────┬──────────────┴───────────────────────────┘
                                                    ▼
                               ┌────────────────────────────────────────┐
                               │         向量化通用复权流水线           │
                               │  股票送转分红配股 + ETF 扩缩股与现金分红 │
                               └────────────────────────────────────────┘
```

---

## 核心能力与数据全景

### 1. 离线优先的统一数据获取链
- **DailyDataManager 智能管理器**：优先读取本地通达信目录历史日线，无本地环境时自动启用在线同步。当检测到本地数据缺失或未覆盖最新交易日时，自动触发增量下载补齐，兼顾纯离线的极致性能与在线数据的实时性。
- **底层二进制直接解析 (`mootdx2.tdx.offline`)**：内置直接解析通达信本地 `.day`（日线）、`.lc1`（1分钟线）、`.lc5`（5分钟线）二进制文件的极速引擎，脱离上层抽象提供纳秒级数据解包。

### 2. 在线行情与双模协议驱动
- **双模协议引擎**：支持内置纯 Python 原生协议驱动（`driver='native'`）与经典兼容驱动（`driver='tdxpy'`），提供无外部污染的通信管道。
- **全市场品类覆盖**：支持标准市场（沪深 A 股、主板/科创板/创业板、指数、全系 ETF）与扩展市场（期货、期权、港股等）的实时日行情快照、五档盘口、逐笔成交 (Tick)、分时线、多周期 K 线（1分钟至年线）及 F10 文本提取。
- **生产级高可用体系**：内置最优服务器测速探测（`bestip`）、请求级自动故障转移（Failover）与节点自适应冷却黑名单。

### 3. 全链路股票与 ETF 通用复权
- **原生复权支持**：所有 K 线数据获取接口原生支持 `adjust='qfq'`（前复权）与 `adjust='hfq'`（后复权）参数，底层直接完成向量化复权计算后输出。
- **全品种支持**：统一复权流水线无缝兼容股票（送转股、派发现金红利、配股）与各类 ETF 基金（覆盖 51/588 科创板/56 等代码段的基金份额折算与现金分红）。
- **多级兜底机制**：本地 XDXR 离线缓存、网络 XDXR 实时提取与新浪/同花顺因子序列自动降级兜底。

### 4. 专业财务数据解析 (580+ 财务指标)
- **多期历史报表探查与下载**：支持自动获取通达信服务器最新的财务报表归档发布清单（`gpcw.txt` 文件大小与 MD5 比对）。
- **全科目结构化解包**：解析 `gpcw*.zip` / `.dat` 原始数据，支持中英文标准表头映射，覆盖基础每股指标、资产负债表、利润表、现金流量表、营运偿债比率以及金融行业（银行/保险/证券）专属科目。

### 5. 巨潮资讯权威公告检索 (`CninfoClient`)
- **独立数据通道**：基于 Python 标准库 `urllib` 实现，零额外第三方依赖。
- **全市场映射保障**：动态对接巨潮官方权威 `orgId` 映射表，彻底解决 601xxx、688xxx 等特定网段代码无法命中公告的问题。
- **完整研报与公告回溯**：支持获取包含发布日期、分类标签、公告正文标题、网页详情 URL 以及官方原始 PDF 附件下载链接的结构化数据。

### 6. 防封增量同步与持久化基础设施
- **请求节流与并发控制**：`sync_daily` 与 `sync_xdxr` 内置批次切分、单任务微延时与滑动窗口限流，避免触发服务器流控封禁。
- **进程安全与长效缓存**：支持 90 天长效缓存机制，写入采用跨进程文件锁（`filelock`）与原子替换保护，防止多进程并发损坏。

---

## 快速安装

```bash
# 安装基础包
pip install mootdx2

# 安装完整增强依赖 (包含可视化与交互工具)
pip install "mootdx2[all]"
```

---

## 架构概览与接口参考

项目提供从高层数据管理器到底层二进制解析的多级调用体系，详细接口说明与字段定义请参阅专项文档：

- 完整接口参数与全景能力说明：[`docs/mootdx2_interfaces.md`](./docs/mootdx2_interfaces.md)
- 场景化代码示例与实战脚本：[`sample/README.md`](./sample/README.md)
  - `sample/01_quotes/`: 在线行情获取与原生/兼容协议驱动双模演示
  - `sample/02_reader/`: 本地二进制数据极速离线读取与日 K 线管理器
  - `sample/03_affairs/`: 专业财务报表下载与 580+ 科目字段解析
  - `sample/04_quant_and_etf/`: 股票与 ETF 复权计算、股息率统计与 K 线绘制
  - `sample/05_utils/`: 服务器测速探测与缓存性能优化
  - `sample/06_cninfo/`: 巨潮资讯公告检索与 PDF 原件获取

---

## 开源协议

本项目基于 [MIT License](./LICENSE) 协议开源。
