Files
pytdxdata/README.md
T
openbot-coder 1bee6b0fc7 release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增
- 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages
- SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱)
- docs/ai.md:文档站的「AI 助手接入」页
- tests/test_check_docs.py(10 项):漂移检查器自身的自测

变更
- README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 /
  扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md
- README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404)
- check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用),
  并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数
- 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站
- uv.lock 同步

修复
- ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正
- docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败)
- README 标注的测试数量 85 → 109(pytest 实际收集用例数)
2026-09-15 14:55:07 +08:00

126 lines
6.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# pytdxdata
[![CI](https://img.shields.io/github/actions/workflow/status/openbot-coder/pytdxdata/ci.yml?branch=main&label=CI)](https://github.com/openbot-coder/pytdxdata/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pytdxdata)](https://pypi.org/project/pytdxdata/)
[![Python](https://img.shields.io/pypi/pyversions/pytdxdata)](https://pypi.org/project/pytdxdata/)
[![License](https://img.shields.io/pypi/l/pytdxdata)](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)
[![PyPI downloads](https://img.shields.io/pypi/dm/pytdxdata)](https://pypi.org/project/pytdxdata/)
通达信(TongDaXin)行情数据客户端:**动态连接池 + 双层 TTL 缓存 + 多连接并发分页**,纯 asyncio、**零运行时依赖**。
**A股(沪/深/北) + 港股 + 美股 + 期货 + 期权**,一套接口全市场。
📖 **完整文档:<https://openbot-coder.github.io/pytdxdata/>**
## 安装
```bash
pip install pytdxdata # 或 uv add pytdxdata
```
可选异步加速:
```bash
pip install "pytdxdata[uvloop]"
```
## 30 秒上手
```python
import asyncio
from pytdxdata import TdxData
from pytdxdata.models import Market, KlinePeriod, Adjust
async def main():
async with TdxData() as td: # 自动建连接池 + 缓存
# 日K线(count 超过单页大小会自动多连接并发分页)
bars = await td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=240)
# 前复权(自动走 MAC 通道)
qfq = await td.get_kline(Market.SZ, "300308", KlinePeriod.DAY,
count=500, adjust=Adjust.QFQ)
# 五档报价(传 (market, code) 元组列表,>80 只自动切批)
quotes = await td.get_quotes([(Market.SH, "600000"), (Market.SZ, "000001")])
# 逐笔成交(MAC 通道,支持历史日期)
ticks = await td.get_transactions(Market.SZ, "000001", date=20260811)
print(bars[-1].close, quotes[0].price, len(ticks))
asyncio.run(main())
```
返回的是标准库 `dataclass` 组成的 `list`(库本身不依赖 pandas)。要 DataFrame 一行转:
```python
from dataclasses import asdict
import pandas as pd
df = pd.DataFrame([asdict(b) for b in bars])
```
## 特性
| 特性 | 说明 |
|------|------|
| 🧩 动态连接池 | 启动时对服务器**真实 K 线探测**选优(剔除握手正常但数据为空的坏节点),健康分 + EWMA 延迟选路,跨服务器故障转移 |
| 🗄️ 双层 TTL 缓存 | 内存 LRU + 磁盘 SQLite(WAL),TTL 分级;single-flight 并发同键去重;缓存**已解析记录**(重复请求 0 网络 0 解析) |
| ⚡ 并发分页 | 单请求拆 N 页(显式 start 偏移 → 无状态可并行)并行拉取、按序拼接、失败换连接重试 |
| 🔀 双通道整合 | 标准通道(经典行情)+ MAC 通道(逐笔 / 复权 / 1 分钟 K 线),按命令自动选路 |
| 📦 零重型依赖 | 纯 asyncio + stdlib(socket / zlib / struct / sqlite3) |
| 📊 全市场覆盖 | A股、港股、美股、期货、期权(46 个扩展市场) |
| 📄 服务器文件解析 | 板块 `block_*.dat` / 行业 `tdxhy.cfg` / 财报 `gpcw*.zip` **下载即解析**成 dataclass |
| 🤖 AI 助手友好 | 内置 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 与 [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) |
## 文档导航
| 我想… | 去哪 |
|------|------|
| 装好跑起来 | [快速开始](https://openbot-coder.github.io/pytdxdata/getting-started/) |
| 抄场景代码(转 DataFrame / 批量下载 / 离线板块快照) | [场景示例](https://openbot-coder.github.io/pytdxdata/cookbook/) |
| 查方法签名与参数 | [TdxData 方法](https://openbot-coder.github.io/pytdxdata/api/tdxdata/) — 由 docstring 自动生成 |
| 搞清枚举该填几 | [枚举速查](https://openbot-coder.github.io/pytdxdata/api/enums/) |
| 看协议二进制格式、三池路由、缓存策略 | [深入原理](https://openbot-coder.github.io/pytdxdata/internals/architecture/) |
| 用命令行 | [命令行工具](https://openbot-coder.github.io/pytdxdata/cli/) |
| 完整接口清单(51 个数据方法) | [`docs/API_REFERENCE.md`](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/) |
| 版本变更 | [`CHANGELOG.md`](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md) |
> 本 README 只做**入口层**。深度内容一律在文档站,避免两处维护造成漂移。
## 给 AI 助手用
仓库根的 [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) 是一份可直接加载的技能:三条必守约定、`KlinePeriod` 等枚举取值表、
「想做什么 → 用哪个方法」决策表、以及 9 条真实陷阱。AI 编程助手读完就能一次写对,不必翻源码。
```bash
# 丢进你所用 AI 助手的 skills 目录即可
curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \
https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md
```
## 示例
- [`examples/quickstart.py`](https://github.com/openbot-coder/pytdxdata/blob/main/examples/quickstart.py) — 报价 / K线 / 分时 / 板块
- [`examples/server_files.py`](https://github.com/openbot-coder/pytdxdata/blob/main/examples/server_files.py) — 板块 / 行业 / 财报 下载 + 解析
## 开发
```bash
uv sync # 建虚拟环境 + 注册 tdx 命令
uv run pytest tests/ # 109 个测试用例(协议 / 池 / 缓存 / 分页 / API / 文件解析 / CLI / 文档漂移)
uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings)
uv run mkdocs serve # 本地预览文档站
```
## 已知限制
- 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情
- 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避
- 港股 / 美股期权在通达信协议内无数据
- 服务器可用性随时间变化,可用 `python -m pytdxdata.server_probe` 重新探测
## 免责声明
本包仅用于**技术研究与教育目的**。行情数据来自通达信公开接口,不保证实时性与准确性;
作者不对任何投资决策负责。使用前请遵守通达信服务条款及相关法律法规。
## License
[MIT](https://github.com/openbot-coder/pytdxdata/blob/main/LICENSE)