mirror of
https://ghfast.top/https://github.com/aeroxw/easy_tdx_max.git
synced 2026-09-12 15:44:18 +08:00
docs: 补充 README.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
minionszyw
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
0fa685dbdd
commit
68bd74e0c3
@@ -0,0 +1,225 @@
|
|||||||
|
# xmtdx
|
||||||
|
|
||||||
|
通达信 TCP 协议 A 股行情数据客户端，从零实现，零运行时依赖。
|
||||||
|
|
||||||
|
pytdx / mootdx 年久失修：多处已知解析 bug、Python 2 包袱、无类型注解、大量未知字段被静默丢弃。xmtdx 重新实现协议，修复已知 bug，保留全部原始字节与未知字段供后续逆向分析。
|
||||||
|
|
||||||
|
## 特性
|
||||||
|
|
||||||
|
- **零依赖**：纯标准库，Python ≥ 3.10
|
||||||
|
- **同步 + asyncio 双接口**：`TdxClient` / `AsyncTdxClient`，commands 层不含任何 IO
|
||||||
|
- **完整类型注解**：strict mypy 通过
|
||||||
|
- **高可用传输**：`ping_all()` 并发测速，`from_best_host()` 自动优选，断线自动重连
|
||||||
|
- **修复 pytdx 已知 bug**（见下文）
|
||||||
|
- **保留原始字节**：每条数据记录含 `_raw: bytes`，未知字段以 `unknown_N` 命名而非丢弃
|
||||||
|
- **离线 fixture 测试**：13 个无网络 pytest，录制真实服务器响应验证解析正确性
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -e . # 开发模式
|
||||||
|
pip install -e ".[dev]" # 含测试/类型检查工具
|
||||||
|
pip install -e ".[pandas]" # 含 pandas（可选）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 同步
|
||||||
|
|
||||||
|
```python
|
||||||
|
from xmtdx import TdxClient, Market, KlineCategory
|
||||||
|
|
||||||
|
# 指定服务器
|
||||||
|
with TdxClient("180.153.18.170") as c:
|
||||||
|
count = c.get_security_count(Market.SH)
|
||||||
|
bars = c.get_security_bars(Market.SH, "600000", KlineCategory.DAY, 0, 5)
|
||||||
|
for b in bars:
|
||||||
|
print(b.year, b.month, b.day, b.open, b.close, b.high, b.low, b.vol)
|
||||||
|
|
||||||
|
# 自动测速选最低延迟服务器
|
||||||
|
with TdxClient.from_best_host() as c:
|
||||||
|
quotes = c.get_security_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
|
||||||
|
print(quotes[0].price, quotes[0].bid1, quotes[0].ask1)
|
||||||
|
```
|
||||||
|
|
||||||
|
### asyncio
|
||||||
|
|
||||||
|
```python
|
||||||
|
import asyncio
|
||||||
|
from xmtdx import AsyncTdxClient, Market, KlineCategory
|
||||||
|
|
||||||
|
async def main():
|
||||||
|
async with AsyncTdxClient("180.153.18.170") as c:
|
||||||
|
bars = await c.get_security_bars(Market.SH, "600000", KlineCategory.DAY, 0, 5)
|
||||||
|
print(bars[0])
|
||||||
|
|
||||||
|
asyncio.run(main())
|
||||||
|
```
|
||||||
|
|
||||||
|
## API
|
||||||
|
|
||||||
|
### TdxClient
|
||||||
|
|
||||||
|
| 方法 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `get_security_count(market)` | 市场证券总数 |
|
||||||
|
| `get_security_list(market, start)` | 证券列表（每页 ~1000 条） |
|
||||||
|
| `get_security_quotes([(market, code), ...])` | 批量实时五档行情（最多 80 只/次） |
|
||||||
|
| `get_security_bars(market, code, category, start, count=800)` | K 线（股票） |
|
||||||
|
| `get_index_bars(market, code, category, start, count=800)` | K 线（指数） |
|
||||||
|
| `get_minute_time_data(market, code)` | 今日分时（240 条） |
|
||||||
|
| `get_history_minute_time_data(market, code, date)` | 历史某日分时，`date=YYYYMMDD` |
|
||||||
|
| `get_transaction_data(market, code, start, count=800)` | 当日逐笔成交（分页） |
|
||||||
|
| `get_history_transaction_data(market, code, date, start, count=800)` | 历史逐笔成交 |
|
||||||
|
| `get_xdxr_info(market, code)` | 除权除息历史 |
|
||||||
|
| `get_finance_info(market, code)` | 最新财务数据 |
|
||||||
|
| `get_company_info_category(market, code)` | 公司信息文件目录 |
|
||||||
|
| `get_company_info_content(market, code, filename, offset, length)` | 公司信息文本 |
|
||||||
|
|
||||||
|
`AsyncTdxClient` 提供完全相同的方法，均为 `async def`。
|
||||||
|
|
||||||
|
### KlineCategory
|
||||||
|
|
||||||
|
```
|
||||||
|
MIN_1 MIN_3 MIN_5 MIN_15 MIN_30 MIN_60
|
||||||
|
DAY WEEK MONTH SEASON YEAR YEAR_ALT
|
||||||
|
```
|
||||||
|
|
||||||
|
### 高可用工具
|
||||||
|
|
||||||
|
```python
|
||||||
|
from xmtdx import ping_all, KNOWN_HOSTS
|
||||||
|
|
||||||
|
# 并发测速，返回按延迟排序的 [(host, seconds), ...]
|
||||||
|
results = ping_all(KNOWN_HOSTS, timeout=5.0)
|
||||||
|
for host, ms in results:
|
||||||
|
print(f"{host} {ms*1000:.0f} ms")
|
||||||
|
|
||||||
|
# 自动选最优服务器
|
||||||
|
with TdxClient.from_best_host(ping_timeout=5.0) as c:
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
内置服务器列表（`KNOWN_HOSTS`）：
|
||||||
|
|
||||||
|
```
|
||||||
|
180.153.18.170 180.153.18.171 180.153.18.172
|
||||||
|
115.238.56.198 115.238.90.165 218.75.126.9
|
||||||
|
47.107.75.159 59.175.238.38
|
||||||
|
```
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
|
||||||
|
所有 dataclass 字段均有类型注解。每条记录附带 `_raw: bytes`（原始协议字节）。
|
||||||
|
|
||||||
|
### SecurityBar（K 线）
|
||||||
|
|
||||||
|
```
|
||||||
|
open close high low vol amount
|
||||||
|
year month day hour minute
|
||||||
|
_raw
|
||||||
|
```
|
||||||
|
|
||||||
|
### SecurityQuote（实时行情）
|
||||||
|
|
||||||
|
```
|
||||||
|
market code price pre_close open high low
|
||||||
|
vol cur_vol amount s_vol b_vol
|
||||||
|
bid1..bid5 bid_vol1..bid_vol5
|
||||||
|
ask1..ask5 ask_vol1..ask_vol5
|
||||||
|
rise_speed server_time
|
||||||
|
unknown_2 unknown_3 unknown_5..unknown_8 # 待解字段，已确认 ≠ 涨停价
|
||||||
|
_raw
|
||||||
|
```
|
||||||
|
|
||||||
|
### MinuteBar（分时）
|
||||||
|
|
||||||
|
```
|
||||||
|
price vol
|
||||||
|
unknown_1 # 原 pytdx 丢弃字段，保留供分析（≠ 均价）
|
||||||
|
_raw
|
||||||
|
```
|
||||||
|
|
||||||
|
### TransactionRecord（逐笔成交）
|
||||||
|
|
||||||
|
```
|
||||||
|
hour minute price vol
|
||||||
|
buyorsell # 0=买, 1=卖, 2=中性, 8=集合竞价
|
||||||
|
unknown_last
|
||||||
|
_raw
|
||||||
|
```
|
||||||
|
|
||||||
|
### SecurityInfo（证券列表）
|
||||||
|
|
||||||
|
```
|
||||||
|
market code name volunit decimal_point pre_close
|
||||||
|
```
|
||||||
|
|
||||||
|
### XdxrRecord（除权除息）
|
||||||
|
|
||||||
|
```
|
||||||
|
market code year month day category name
|
||||||
|
fenhong peigujia songzhuangu peigu suogu
|
||||||
|
xingquanjia fenshu
|
||||||
|
panqian_liutong panhou_liutong
|
||||||
|
qian_zongguben hou_zongguben
|
||||||
|
_raw
|
||||||
|
```
|
||||||
|
|
||||||
|
### FinanceInfo（财务）
|
||||||
|
|
||||||
|
流通股本、总股本、各省份/行业代码、资产负债表及利润表主要科目（30 个 float 字段）。
|
||||||
|
|
||||||
|
## 修复的 pytdx Bug
|
||||||
|
|
||||||
|
| # | 位置 | 问题 | 修复 |
|
||||||
|
|---|------|------|------|
|
||||||
|
| 1 | `xdxr_info` | 循环内始终读 `body[:7]`，所有记录字段相同 | 改为从当前 `pos` 读取，pos 正确推进 |
|
||||||
|
| 2 | `security_list` | GBK 解码截断时 crash | `decode('gbk', errors='replace')` |
|
||||||
|
| 3 | `security_list` | `pre_close` 错用成交量解码函数 | 改用价格解码 |
|
||||||
|
| 4 | `transaction` | 最后一个字段被 `_` 丢弃 | 保留为 `unknown_last` |
|
||||||
|
| 5 | `minute_time` | `reversed1` 字段被丢弃 | 保留为 `unknown_1` |
|
||||||
|
|
||||||
|
## 架构
|
||||||
|
|
||||||
|
```
|
||||||
|
src/xmtdx/
|
||||||
|
├── client.py # TdxClient / AsyncTdxClient（高层 API）
|
||||||
|
├── transport/
|
||||||
|
│ ├── sync.py # TdxConnection（socket）+ ping_host / ping_all
|
||||||
|
│ └── async_.py # AsyncTdxConnection（asyncio）
|
||||||
|
├── commands/ # 每条命令：build_request() + parse_response()，无 IO
|
||||||
|
├── codec/ # price / volume / datetime / frame 编解码
|
||||||
|
└── models/ # 纯 dataclass，无业务逻辑
|
||||||
|
```
|
||||||
|
|
||||||
|
commands 层不依赖 transport，可独立单测。transport 层负责 TCP、握手、帧解压、分发。
|
||||||
|
|
||||||
|
## 开发
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 单元测试（无需网络）
|
||||||
|
python -m pytest tests/unit/
|
||||||
|
|
||||||
|
# 集成测试（需要网络）
|
||||||
|
python -m pytest tests/integration/
|
||||||
|
|
||||||
|
# 未知字段探测脚本
|
||||||
|
python scripts/probe_unknowns.py
|
||||||
|
|
||||||
|
# 类型检查
|
||||||
|
mypy src/
|
||||||
|
|
||||||
|
# lint
|
||||||
|
ruff check src/ tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
## 协议说明
|
||||||
|
|
||||||
|
通达信使用私有二进制 TCP 协议：
|
||||||
|
|
||||||
|
- **帧格式**：16 字节响应头（含 zipsize / unzipsize），body 按需 zlib 解压
|
||||||
|
- **价格编码**：变长有符号整数（类 LEB128，bit8=继续，bit7=符号，首字节低 6 位 + 后续低 7 位）
|
||||||
|
- **成交量编码**：4 字节自定义浮点（字节 3 = 指数，字节 0-2 = 精度），**不可用于价格字段**
|
||||||
|
- **握手**：连接后必须顺序发送 3 条 setup 命令，响应丢弃
|
||||||
|
- **价格存储**：整数 × 100，差分编码（相邻 tick 存 delta）
|
||||||
Reference in New Issue
Block a user