Files
pytdxdata/docs/llms.txt
T
openbotandopenbot-coder 8a78156145 perf: 全市场报价改单连接流水线(3.5s → 0.33s)+ 修复基金笔数口径 (#9)
## 性能:get_quotes 全市场 5,227 只 A股 3.5s → 0.33s

协议硬上限 80 只/请求 → 必须切 66 片;老实现是纯串行 for 循环,
每片一次往返(≈60ms),3.5s 全花在等网络上。

发现通达信响应是自描述长度帧且服务器按序应答,因此同一连接可连发
多条请求只付一次往返:实测单连接流水 66 请求 526ms(串行 7,372ms)。

- TdxConnection.execute_pipeline(cmds):一次下发全部 → 按序读回;中途失败强制断连
- _quotes_std 改工作窃取调度(快台多干,避免被最慢节点拖累)
- DynamicPool.warm(n):并发预建连接(acquire 在全局锁内一次一条,22 并发首拉会多花 5~6s)
- CacheManager.get_or_fetch_obj:回源直接返回对象,省掉冷路径 pickle→unpickle 白烧
- pool_max 默认 12 → 24

调优实测 p50/max:每台 1 连接×深度 6 = 455ms;每台 2 连接×深度 3 = 325ms。
端到端(全默认):首次 783ms、稳态 300~343ms、热缓存 67ms。
正确性:用昨收价交叉比对 30 只零错配,流水线与逐片结果集合完全一致。

## 修复:指数 / ETF / LOF 的 trade_count 不再伪装成笔数

通达信对指数和多数场内基金不提供笔数,那 4 字节里塞的是「价格 × 1000」
(指数是「均价 × 1000」)。旧版直接当笔数用,tdx transactions sh510310
会打印出「3994 笔」这种假数据。

- 新增 TransactionRecord.trade_count_available
- 新增 symbols.has_order_count(market, code) 按品种判定
  (沪市 501x/502x/506x 实测有真实笔数,不能按「5 开头=基金」一刀切)
- 历史通道 0x013001 无笔数字段,同样标记不可用

## 文档:可转债量纲口径

核查可转债分时/逐笔后确认数据本身无缺陷(16 只当日 + 8 只历史日,
分时末价/现价、Σvol/日线vol、逐笔 VWAP 比值均 1.000000),
但 vol 单位是「手」(=10 张)导致 amount/vol 是均价的 10 倍,对外文档缺失。

- SecurityBar / TransactionRecord / MinuteBar 量纲注释补全
- has_order_count 实测表补沪可转债 110/111/113/118、沪 EB 132、深可转债 123/127/128
- API_REFERENCE 新增跨品种量纲对照表;llms.txt / SKILL.md 同步

## 版本

0.6.7

## 测试

306 → 346 全通过(新增 tests/test_pipeline.py 11 项 + 基金笔数相关回归)

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-22 19:41:55 +08:00

136 lines
9.2 KiB
Plaintext
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
> 通达信(TongDaXin)行情数据客户端:动态连接池 + 双层 TTL 缓存 + 3 连接并发分页。纯 asyncio,零运行时依赖,覆盖 A股(沪/深/北)/港股/美股/期货/期权。
pytdxdata 是一个 Python 库,从通达信**公开**行情服务器直接读取行情与服务器文件,无需账号。
面向量化研究与历史数据落库场景(数据为 15 分钟延时,不适合实时交易)。
## 安装与最小可用示例
```bash
pip install pytdxdata # 或 uv add pytdxdata;要求 Python >= 3.11
```
```python
import asyncio
from pytdxdata import TdxData
from pytdxdata.models import KlinePeriod
async def main():
async with TdxData() as td: # 自动探测服务器、建连接池、初始化缓存
bars = await td.get_bars("sh600000", KlinePeriod.DAY, count=2400)
print(bars[-1].datetime, bars[-1].close)
asyncio.run(main())
```
## 心智模型(AI 必读)
1. **入口只有一个类**:`TdxData`。所有数据获取都是它的公开异步方法(v0.6 起为 **28 个统一方法**,
另有 33 个 deprecated 别名与 `start()` / `close()` 生命周期方法),必须在 `async with` 内使用。
2. **标的用字符串**,形如 `sz000001` / `sh600000` / `hk00700` / `usAAPL` / `cffex:IFL0`。
同一个 6 位代码在不同市场含义不同:`sh000001` 是上证指数,`sz000001` 是平安银行;
裸 6 位数字(如 `000001`)视为沪市指数。统一接口不再接受 `(market, code)` 元组。
3. **枚举取值没有直觉,必须用枚举成员,不要写数字字面量**:
- `Market`: SZ=0 / SH=1 / BJ=2
- `KlinePeriod`: MIN_5=0, MIN_15=1, MIN_30=2, MIN_60=3, **DAY=4**, WEEK=5, MONTH=6, **MIN_1=7**, MIN_3=8, YEAR=9, SEASON=10, YEAR_ALT=11
- `Adjust`: NONE=0 / QFQ=1(前复权) / HFQ=2(后复权);**默认 NONE**,很多券商软件默认前复权,对比数据前先对齐
- `ExMarket`: 港股主板 HK_MAIN_BOARD=31 / 美股 US_STOCK=74 / 中金所 CFFEX_FUTURES=47 / 沪股票期权 SH_STOCK_OPTION=8 等,共 46 个成员
4. **返回 `list[dataclass]`**,不是 DataFrame。需要 pandas 自行转换(见 cookbook)。包本身无任何运行时依赖。
5. **实例要复用**:连接池与缓存都挂在 `TdxData` 实例上。长驻进程(Web 服务)应只创建一个实例,
不要每请求新建,否则等于每请求重建连接池且缓存全部失效。
## 主要能力分组(统一接口)
标的一律用字符串;以下均为 v0.6 统一接口,跨市场自动选路。
- **标的清单**:`get_universe`(A股 + 港股 + 美股 + 期货/期权)
- **K 线**:`get_bars`(自动并发分页、支持复权与日期区间、多标的并发)
- **技术指标**:`get_indicators`(K线 + MACD/KDJ/RSI/BOLL/MA/EMA)
- **报价**:`get_quotes`(五档,>80 只自动切批;**单连接流水线**默认开启,全市场 5,200 只 A股 ~0.33s)、`get_snapshot`(个股特征)、`get_market_stat`
- 价格标度:协议给的是整数,真实价 = `整数 / 10**小数位`。小数位由 `price_decimal_digits` 决定,
优先用**权威表**(证券清单自带的 `SecurityInfo.decimal_point`,`start()` 每日后台同步一次,
也可 `await td.sync_decimal_points()` 强制刷新),未同步时退回静态前缀规则。
债券/回购是 **4 位**、沪市 B 股 3 位 —— 这里错过两次(整批价格差 100 倍/10 倍)。
- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期,返回按时间升序;`vol`/`trade_count` 为约 3 秒切片增量而非累计;已剔除 `bs_flag=8` 竞价委托;**指数**的 `vol` 是百元、`trade_count` 是均价×1000;**可转债**的 `vol` 是手=10 张、`trade_count` 是真实笔数,故日线 `amount/vol` 是均价的 **10 倍**,算均价要再 /10)、`get_minutes`(`sampling=True` 取缩略采样;`hour` 恒为合法时钟值 0~23,美股一个交易日跨两个北京自然日,按交易日聚合用 `MinuteBar.trading_date`、取时刻用 `MinuteBar.datetime`)
- **财务 / 除权**:`get_finance`(最新快照)、`get_xdxr`、`get_price_limits`(本地计算涨跌停)
- **F10**:`get_f10`(公司资料目录 + 正文)
- **板块**:`get_boards`、`get_board_members`、`get_board_of`、`get_board_summary`、
`get_board_ranking`、`get_board_change_ranking`
- **服务器文件(下载 + 解析一步到位)**:`get_file`(原始字节)、`get_block_parsed`(板块成分)、
`get_industry_map`(通达信+申万行业)、`get_financial_file_infos`、`get_financial_records_parsed`(历史专业财报)
> 旧的分通道/市场方法(`get_kline` / `get_transactions` / `get_goods_*` 等共 33 个)保留为
> deprecated 别名,1.0 移除;完整对照见[接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/)与 CHANGELOG。
## 服务器与配置
服务器主机来源有一条优先级链(各协议独立):环境变量 → **当日测速缓存** → 包内清单
`fast_pool` → 包内清单 → 代码内置常量。
- `TdxData.start()` 会在**当日首次启动**后台触发一次全量测速,用**真实 K 线命令**判定可达
(不是只握手),结果按延迟升序写入**用户级缓存**(Windows `%LOCALAPPDATA%\pytdxdata`、
macOS `~/Library/Caches/pytdxdata`、Linux `$XDG_CACHE_HOME/pytdxdata`),当天复用、不再重测。
- 该操作对调用方**完全无感**:后台执行、不打印、不阻塞 `start()`、失败静默降级。
运行时**绝不改写包内 `servers.json`**。
- 环境变量:`PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS`(逗号分隔,手工指定,最高优先)、
`PYPYTDX_DATA_CACHE_DIR`(覆盖缓存目录)、`PYPYTDX_DATA_DISABLE_PROBE=1`(关闭测速)。
## CLI
安装后提供 `tdx` 命令,19 个子命令,不写代码即可取数:
```bash
tdx quotes sz000001 sh600000
tdx kline sz000001 --period day --count 30 --adjust qfq
tdx transactions sz000001 --date 20260811
tdx board rank --type 1 --top 10
tdx block block_gn.dat --limit 10 --codes
tdx industry 600000 --search 银行
tdx financial gpcw20260331.zip --limit 5
```
标的写法:`sz000001` / `sh600000` / `bj920992` / `hk00700` / `usAAPL` / `cffex:IFL0` / `000001`(6 位纯数字=指数)。
## 关键陷阱
- **`KlinePeriod.MIN_1` 走 MAC 通道并单连接串行分页**,这是刻意设计:并发分页在多服务器
历史深度不一致时会产生非确定性数据空洞。不要试图"优化"成并发。
- **复权 K 线走 MAC 通道**,标准通道不提供复权数据。
- **K 线 `datetime` 统一为北京时间**(v0.6.2 起)。美股原始报文的日期分量是美东交易日、
时分分量是北京时间,库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。
但**美股一个交易日横跨两个北京自然日**:按交易日聚合(分钟线合成日线、日内统计)
用 `bar.trading_date`,不要用 `bar.datetime.date()`。`bar.is_us` 判定美股。
- **标准通道部分服务器在 `count < 100` 时返回空**,分页器已强制 `min_page=100` 规避。
- **本地 Windows 上 `asyncio.new_event_loop()` 可能永久挂起**,根因是回环 `socket.socketpair()`
被本地代理/安全软件拦截。异步测试请在 Linux/WSL 运行。
- **`FinanceRecord` 与 `FinancialRecord` 不同**:前者是最新一期财务快照(标准通道),
后者是历史多报告期专业财报(服务器文件,字段为原始 float 数组)。
- 美股期权、港股期权在通达信协议内**无数据**。
- 行情为 **15 分钟延时**,不适合实时交易决策。
## 文档
- [首页](https://openbot-coder.github.io/pytdxdata/)
- [安装与配置](https://openbot-coder.github.io/pytdxdata/getting-started/)
- [场景示例](https://openbot-coder.github.io/pytdxdata/cookbook/)
- [CLI 手册](https://openbot-coder.github.io/pytdxdata/cli/)
- [接口总览](https://openbot-coder.github.io/pytdxdata/api/)
- [TdxData 方法签名](https://openbot-coder.github.io/pytdxdata/api/tdxdata/)
- [枚举速查](https://openbot-coder.github.io/pytdxdata/api/enums/)
- [数据模型](https://openbot-coder.github.io/pytdxdata/api/models/)
- [架构总览](https://openbot-coder.github.io/pytdxdata/internals/architecture/)
- [协议与命令](https://openbot-coder.github.io/pytdxdata/internals/protocol/)
- [通道与数据源](https://openbot-coder.github.io/pytdxdata/internals/routing/)
- [连接池与缓存](https://openbot-coder.github.io/pytdxdata/internals/cache-pool/)
- [常见问题](https://openbot-coder.github.io/pytdxdata/faq/)
## 可选
- [SKILL.md](https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md):面向 AI **编程**助手的技能文件(必守约定 / 枚举取值表 / 决策表 / 陷阱清单),比本文件更适合指导写代码
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
- [接口重构审查](https://openbot-coder.github.io/pytdxdata/refactor-audit/):统一接口 / 废弃别名全清单 + 数据一致性与遗漏对账
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
- [PyPI](https://pypi.org/project/pytdxdata/)