通达信 EX 通道对美股返回的分钟级 K线把两个时区拼进同一个五元组:日期分量是 美东交易日(zipday),时分分量是北京时间(tminutes)。直拼出的 datetime 会把 同一交易日的下午半场排到上午半场之前——单日 390 根首末颠倒,且全部落在同一个 北京自然日里,导致排序 / count 切片 / 日期区间二分与过滤 / 增量水位线全部不可用。 在 SecurityBar.__post_init__ 统一归一化为北京时间(凌晨段日期 +1 天,含月末与 年末进位),EX 的两条 K线命令路径(_bars_ex 的 0x23FF 与二分所依赖的 MAC 0x122E) 因此共用同一口径,不会出现"取数按一套时间、二分按另一套时间"的错位。 新增两个只读属性:trading_date(归属交易日;美股一个交易日横跨两个北京自然日, 按交易日聚合必须用它,不能用 datetime.date())与 is_us。 实测(安装 wheel 0.6.2,非源码树):10-06 ~ 10-12 五个完整交易日各 390 根、 严格单调,首根 open / 末根 close 与日线逐位相同,成交量差 <= 1;A股 / 港股零回归。 - 版本 0.6.1 -> 0.6.2(pyproject / __init__ / uv.lock) - tests/test_protocol.py 新增 9 项回归测试(分界点 / 月末年末进位 / 390 根整日单调性 / MAC 路径),全量 191 passed - CHANGELOG / README / SKILL.md / docs(faq、llms.txt、api/models)同步口径说明 遗留(本版未含,待决策):EX 分时对美股返回的 MinuteBar.hour 是未取模的连续分钟数 (实测可达 27,即次日 03:xx),且 MinuteBar 无日期分量可承载跨日信息。 Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
132 lines
8.2 KiB
Plaintext
132 lines
8.2 KiB
Plaintext
# 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 只自动切批)、`get_snapshot`(个股特征)、`get_market_stat`
|
||
- **逐笔 / 分时**:`get_ticks`(含 `trade_count`,支持历史日期)、`get_minutes`(`sampling=True` 取缩略采样)
|
||
- **财务 / 除权**:`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/)
|