docs: 建立 MkDocs 文档站与 AI 层文档

- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、
  Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理
  (架构 / 协议 / 三池路由 / 缓存)
- 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱)
- 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移
- 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入
- 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages
- 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close);
  API_REFERENCE 版本号 v0.3.2 -> v0.4.0
- pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
This commit is contained in:
openbot-coder committed 2026-09-15 13:57:31 +08:00
1 parent 02ec5b6e33
commit c4dd61665b
26 files changed
+2934 -1

No files matched your search

+232
View File
@@ -0,0 +1,232 @@
# 场景示例
每个片段都是完整可跑的。共同前提:
```python
import asyncio
from pathlib import Path
from pytdxdata import TdxData
from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market
```
## 全市场日线批量落库
连接池会把不同股票分配到不同服务器,这是 `*_batch` 存在的意义。
```python
async def dump_all_daily():
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
codes = await td.get_security_list_all(Market.SZ) # 缓存 1 天
symbols = [(Market.SZ, s.code) for s in codes]
bars = await td.get_kline_batch(
symbols,
KlinePeriod.DAY,
count=800,
adjust=Adjust.QFQ,
concurrency=12,
)
print(f"{len(bars)} / {len(symbols)} 只拿到数据")
for code, rows in bars.items():
if not rows:
continue
# 落库 / 写 parquet 都行,这里只演示
print(code, len(rows), rows[-1].datetime, rows[-1].close)
```
!!! tip "分页与并发的取舍"
`concurrency` 不是越大越好。单台服务器有连接上限,`concurrency` 超过 `pool_max × 服务器数`
之后只会排队。实践值:**8~16**。
## 分钟线增量更新
只拉「上次之后」的部分,用 `get_kline_since` 省掉全量重拉。
```python
async def update_minute(code: str, last_dt):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
rows = await td.get_kline_since(Market.SZ, code, KlinePeriod.MIN_1, since=last_dt)
return [r for r in rows if r.datetime > last_dt]
```
!!! warning "1 分钟 K 线走 MAC 单连接串行分页"
这是刻意设计:并发分页会把不同页分到不同服务器,而各服务器**历史深度不一致**,
拼接后会出现**非确定性数据空洞**。所以 `MIN_1` 强制单连接串行(见 [通道与数据源](internals/routing.md))。
## 报价轮询
```python
async def poll_quotes(symbols, interval=5.0):
async with TdxData() as td:
while True:
quotes = await td.get_quotes(symbols) # >80 只自动切批;缓存 TTL 5s
for q in quotes:
print(q.code, q.price, q.bid[0], q.ask[0])
await asyncio.sleep(interval)
```
> 缓存 TTL 与轮询间隔对齐时,重复轮询几乎 0 网络开销。但注意通达信公开源本身是
> **15 分钟延时**数据,别拿它做实时交易决策。
## 板块轮动 / 领涨股
```python
async def sector_rotation():
async with TdxData() as td:
# 近 5 日概念板块涨幅排行
top = await td.get_board_change_ranking(board_type=2, days=5, top_n=10)
for row in top:
print(row)
# 拿第一名板块的成分股
symbol = top[0]["symbol"] if "symbol" in top[0] else "881001"
members = await td.get_board_members(symbol, count=20)
for m in members[:5]:
print(m.code, m.name, m.fields)
# 板块资金汇总
print(await td.get_board_summary(symbol))
```
## 个股所属板块(反向查询)
```python
async def belong(code: str):
async with TdxData() as td:
for b in await td.get_belong_board(Market.SH, code):
print(b)
```
## 逐笔复盘
```python
async def review_transactions(code: str, ymd: int):
async with TdxData() as td:
rows = await td.get_transactions(Market.SZ, code, date=ymd, count=2000)
total = sum(r.trade_count or 0 for r in rows)
buy = sum(r.vol for r in rows if r.bs_flag == 0) # 主动买
sell = sum(r.vol for r in rows if r.bs_flag == 1) # 主动卖
print(f"{ymd} 总成交笔数={total} 主动买={buy} 主动卖={sell}")
```
## 财务因子快照
```python
async def finance_snapshot(codes):
async with TdxData() as td:
for mkt, code in codes:
fin = await td.get_finance(mkt, code) # 标准通道,最新快照
if fin:
print(code, fin)
```
历史专业财报(`gpcw*.zip`,含多报告期)走文件接口:
```python
async def history_financials(code: str):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
infos = await td.get_financial_file_infos() # 索引
records = await td.get_financial_records_parsed(infos[-1].filename)
row = next((r for r in records if r.code == code), None)
if row:
print(row.report_date, row.fields[:8])
```
## 行业分类映射
```python
async def industry_lookup(codes):
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
hy = await td.get_industry_map() # {6位代码: IndustryInfo}
for c in codes:
info = hy.get(c)
if info:
print(c, info.tdx_industry, info.sw_industry)
```
## 板块成分(离线解析) {#offline-block-snapshot}
`get_block_parsed` 拿到的是纯 dataclass,落成本地 JSON 后**完全脱网可用**——
适合做「板块成分快照」的定时任务。
```python
import json
async def snapshot_blocks():
async with TdxData(cache_dir=Path("./tdx_cache")) as td:
all_blocks = []
for fn in ("block_zs.dat", "block_gn.dat", "block_fg.dat"):
for b in await td.get_block_parsed(fn):
all_blocks.append({
"name": b.name,
"category": b.category,
"codes": b.codes,
})
Path("blocks.json").write_text(
json.dumps(all_blocks, ensure_ascii=False), encoding="utf-8"
)
```
## 港股 / 美股 / 期货 / 期权
```python
async def ex_markets():
async with TdxData() as td:
hk = await td.get_kline(ExMarket.HK_MAIN_BOARD, "00700", KlinePeriod.DAY, count=700)
us = await td.get_kline(ExMarket.US_STOCK, "AAPL", KlinePeriod.DAY, count=700)
fut = await td.get_kline(ExMarket.CFFEX_FUTURES, "IFL0", KlinePeriod.DAY, count=700)
opt = await td.get_kline(ExMarket.SH_STOCK_OPTION, "10010971", KlinePeriod.DAY, count=700)
print(len(hk), len(us), len(fut), len(opt))
# 港股全量逐笔(自动翻页,≤50 页 / 9 万条)
ticks = await td.get_goods_transaction_all(ExMarket.HK_MAIN_BOARD, "00700")
print(len(ticks))
```
## 转成 pandas {#to-pandas}
包本身不带 pandas 依赖,但转换是一行的事:
```python
import pandas as pd
async def to_dataframe(code: str):
async with TdxData() as td:
bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=800)
df = pd.DataFrame([{
"dt": b.datetime, "open": b.open, "high": b.high,
"low": b.low, "close": b.close, "vol": b.vol, "amount": b.amount,
} for b in bars])
return df.set_index("dt")
```
## 长驻服务(FastAPI)
!!! danger "不要每次请求都新建 TdxData"
池与缓存都挂在实例上,每请求新建 = 每请求重建连接池 + 缓存全部失效。
```python
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request
@asynccontextmanager
async def lifespan(app: FastAPI):
async with TdxData(cache_dir=Path("./tdx_cache"), pool_min=4, pool_max=16) as td:
app.state.td = td
yield
app = FastAPI(lifespan=lifespan)
@app.get("/kline/{code}")
async def kline(code: str, request: Request):
td = request.app.state.td
bars = await td.get_kline(Market.SH, code, KlinePeriod.DAY, count=30)
return [{"dt": str(b.datetime), "close": b.close} for b in bars]
```
## 下一步
- [接口总览](api/index.md) — 全部方法
- [连接池与缓存](internals/cache-pool.md) — 调优 `pool_min` / `pool_max` / TTL