Metadata-Version: 2.5
Name: mootdx2
Version: 1.4.3
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/)

通达信行情与历史数据读取工具包，支持标准股票与扩展市场在线实时行情、离线历史文件（日线/分钟线/分时线/板块）极速解析、财务数据下载解析、90天长效缓存除权因子管理、跨进程文件锁保护及股票与 ETF 统一前复权/后复权精准计算。

---

## 核心特性

- **统一数据获取链 (`kline`)**：自动实现“本地离线 `.day` 优先 + 在线增量补齐/兜底 + 向量化自动复权”，开箱即用。
- **在线行情获取**：基于 TDX 原生协议，支持股票、指数、ETF、期权、期货等多品种实时五档行情、历史 K 线、分时线、逐笔成交与财务摘要查询。
- **高可用双轨驱动与自动容灾 (Failover)**：内置纯 Python 原生协议驱动（`driver='native'`）与经典 `tdxpy` 双轨制；配合最优服务器测速（`bestip`）、线程安全连接池（`RLock` 保护）与 300 秒自适应冷却黑名单，异常时自动触发跨驱动平滑降级与节点重试。
- **现代资源管理协议**：全面支持上下文管理器协议（`with Quotes.factory(...) as client:`），自动释放底层连接与套接字，防止句柄泄漏。
- **本地离线数据解析与反向回写**：高效解析本地通达信数据目录文件（`.day` / `.lc1` / `.lc5` / 板块 `.dat`），支持环境变量 `MOOTDX2_TDX_DIR` 与各平台默认路径识别。
- **原子落盘与长效跨进程缓存**：除权除息数据（XDXR）与本地缓存采用纳秒级临时文件与 `os.replace` 原子落盘，90 天长效 `.plk` 缓存集成 `filelock` 跨进程互斥锁。
- **巨潮官方公告与财报下载**：内置基于标准库零三方依赖的 `CninfoClient`，支持检索上市公司公告与下载官方 PDF 财报原件。

---

## 安装说明

### 使用 pip 安装

```bash
pip install mootdx2
# 安装完整命令行增强依赖
pip install "mootdx2[all]"
```

### 开发环境安装

```bash
git clone https://github.com/mootdx/mootdx.git
cd mootdx
uv sync --all-groups
uv run pytest
```

---

## 快速上手与 API 说明

### 1. 统一 K 线与在线行情 (`mootdx2.quotes.Quotes`)

推荐使用 **上下文管理器 (`with`)** 自动释放底层 TCP 连接：

```python
from mootdx2.quotes import Quotes

with Quotes.factory(market='std', multithread=True, heartbeat=True, bestip=True) as client:
    # 1. 统一获取 K 线 (离线 .day 优先 + 在线增量补齐 + 自动复权 + 日期切片)
    # 本地有 .day 则毫秒级读取历史，仅在线拉取最新缺口增量并自动完成前复权
    df_kline = client.kline(
        symbol='600036',
        start='2020-01-01',
        end='2024-01-01',
        frequency='day',     # 支持 'day', 9, 4 等
        adjust='qfq',        # 支持 'qfq'(前复权), 'hfq'(后复权), None(不复权)
        offline_first=True,  # 优先读取本地 MOOTDX2_TDX_DIR
    )

    # 2. 原生在线获取指定条数 K 线
    df_bars = client.bars(symbol='600036', frequency=9, offset=500, adjust='qfq')

    # 3. 获取实时多股五档报价
    df_quotes = client.quotes(symbols=['600000', '000001', '600519'])

    # 4. 获取分时数据与分笔成交
    df_minute = client.minute(symbol='600036')
    df_trans = client.transaction(symbol='600036', start=0, offset=800)

    # 5. 获取除权除息原始数据 (XDXR)
    df_xdxr = client.xdxr(symbol='600036')
```

---

### 2. 本地离线文件读取 (`mootdx2.reader.Reader`)

自动识别本地通达信安装目录（亦可配置环境变量 `MOOTDX2_TDX_DIR` 或显式指定 `tdxdir`）：

```python
from mootdx2.reader import Reader

reader = Reader.factory(market='std', tdxdir=None)

# 1. 读取日线数据 (支持直接返回前复权/后复权)
df_daily_qfq = reader.daily(symbol='600036', adjust='qfq')

# 2. 读取 1 分钟 / 5 分钟线数据
df_min1 = reader.minute(symbol='600036', suffix='1')
df_min5 = reader.minute(symbol='600036', suffix='5')

# 3. 读取板块数据
df_blocks = reader.block(name='block_gn.dat')
```

---

### 3. 除权除息、长效缓存与批量同步 (`mootdx2.sync` / `mootdx2.cache`)

```python
from mootdx2 import get_xdxr, sync_daily, sync_xdxr
from mootdx2.cache import refresh_all_plk_cache
from mootdx2.tools.reversion import reversion

# 1. 批量预同步日K线至本地离线缓存 (防封节流 + 自动落盘)
sync_kline_res = sync_daily(symbols=['600000', '000001', '600519'], offset=800)

# 2. 批量预同步除权数据 (90 天长效缓存与跨进程文件锁)
sync_xdxr_res = sync_xdxr(symbols=['600000', '000001', '600519'], workers=4)

# 3. 一键扫描并强制刷新本地所有 .plk 缓存文件
refresh_stat = refresh_all_plk_cache(workers=4, delay=0.05)

# 4. 单标的除权数据获取与复权计算
df_xdxr = get_xdxr('600036', refresh=False)
df_qfq = reversion(symbol='600036', stock_data=raw_df, xdxr=df_xdxr, type_='qfq')
```

---

### 4. 巨潮资讯公告检索与 PDF 财报下载 (`mootdx2.data.CninfoClient`)

```python
from mootdx2 import CninfoClient

client = CninfoClient()

# 1. 检索上市公司最新公告明细
df_announcements = client.get_announcements(code='600519', count=20)

# 2. 一键下载官方 PDF 财报原件到指定目录
if not df_announcements.empty and df_announcements.iloc[0]['pdf_url']:
    pdf_path = client.download_pdf(df_announcements.iloc[0], dest_dir='./reports')
    print(f'财报原件已保存至: {pdf_path}')
```

---

### 5. 财务数据下载与解析 (`mootdx2.affair.Affair`)

```python
from mootdx2.affair import Affair

# 获取远程财务文件列表并下载解析
file_list = Affair.files()
Affair.fetch(downdir='download_dir', filename='gpcw19960630.zip')
df_financial = Affair.parse(downdir='download_dir', filename='gpcw19960630.zip')
```

---

### 6. 命令行工具 (CLI)

```bash
# 1. 测速并更新最优行情服务器
mootdx2 bestip -l 5 -v

# 2. 批量同步除权因子 (90天长效缓存 + 并发节流防封)
mootdx2 sync -s "600000,000001,600519" -w 4 -d 0.05

# 3. 获取实时行情并导出
mootdx2 quotes -s 600036 -a daily -o output.csv

# 4. 读取本地通达信数据文件
mootdx2 reader -s 600036 -a daily -o daily_600036.xlsx

# 5. 批量下载历史数据
mootdx2 bundle -s 600000,000001 -a daily -o bundle_dir -e csv
```

---

## 许可证

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