* feat: DataFrame 直出(df="polars"/"pandas")+ 版本 0.7.0 TdxData 新增构造参数 df: - None(默认)→ 行为与 0.6.x 完全一致,返回 list[dataclass] - "polars"/"pandas" → 42 个表格型接口直接返回 DataFrame 转换层 src/pytdxdata/frames.py: - 列计划按模型缓存,列式采集(不做逐行 asdict) - 时间列替换:year/month/day/hour/minute → datetime + trading_date;Xdxr 给 date - 嵌套定型:bid/ask 展开 10 列、fields 字典 JSON 化、codes 保持列表 - 容器展开:get_indicators 合并指标、get_index_trade_stats 展开 minutes、 get_kline_batch/get_minute_batch 纵向拼接 - ContextVar 层次标记:批量/别名方法内层不二次转换,并发互不干扰 - 后端惰性加载:缺包抛 FrameBackendError(带安装命令),构造时即失败 依赖:新增 extras pandas/polars/dataframe,核心包仍零依赖;dev 组加 pandas+polars 测试:tests/test_frames.py 40 项(双后端×双格式);全量 401 项通过 文档:新增 docs/dataframe.md,同步 API_REFERENCE/SKILL/llms.txt/README/mkdocs * perf(kline): 按日期取K线贴最新时走倒推,1分钟 4.2s → 82ms 问题:start_date/end_date 一律走「探总根数 + 二分定位」。1 分钟 K 线历史 二十万根量级 = 6 次翻倍探测 + 2 次方向探测 + 两次各 ~18 次跳转,共 36+ 次 串行往返。「取今天」这个最常见的调用要 4.2 秒。 改法(_bars_backtrack 快路径): - 右端离最新不超过 _BACKTRACK_GRACE(10 天) 时,直接 start=0, count=N 拿最新 N 根再裁剪;N 按时间跨度估(_BARS_PER_DAY),一天内一次命中, 不够才翻倍,放大到 _BACKTRACK_MAX_BARS 仍不够则回落二分 - 历史中段仍走二分,结果口径完全一致(已逐条比对基准) 两个关键细节: - 偏移方向是通道级属性而非标的属性,首次探测后缓存在实例上 (_kline_dir_cache)——全市场 5,225 只批量只付一次探测成本 - K线 hour/minute 是周期**结束**时刻,最新一根可能比 now() 略大(14:29 那根还在走),「右端贴最新」必须留周期容差,否则 end_date=now() 被误判 成历史中段 实测(1 分钟,冷启动): 取今天 4,208ms → 82ms 2天前~now 2,211ms → 75ms 最近3天 2,000ms+ → 239ms 历史中段 1,512ms → 285ms 全市场5225只取今天 32.1s(1,140,699 根,精确当天口径) 注:route_for 让 MIN_1 一律走 MAC(0x122E),所以按通道做方向缓存而不是按 「标准/扩展」写死分支。 测试:新增 tests/test_kline_date.py 6 项(倒推次数上界、结束时刻容差、 中段回落二分、未来区间、反向通道、与 count 路径口径一致);全量 407 项通过 * perf(kline): 全市场1分钟K线改多连接流水线抓取(43.6s → 5~7s,盘中 2s) 瓶颈其实是**往返次数**不是带宽:单只K线一请求一标的,串行 33ms/只 ≈ 1 个 RTT。 同一台服务器 16 连接 × 深度 8 实测能跑 5.2 MB/s(此前「单 IP 限流 1.5MB/s」 是浅流水下的假象)。 - get_bars 新增 pipeline 参数(None=按单请求字节自适应 8~32,1=关闭走逐只) - 多标的(≥16 只)走 _bulk_bars:多连接 work-stealing + 单连接 execute_pipeline - 只用实测最快的 12 台:池里 24 台全用反而被慢节点拖长尾 - 盘中按交易时段只拉已走过的根数(10:00 → 35 根,数据量差 7 倍) - 标准通道(日线不复权)同样走批量:全市场 49~72s → 13s - 修 pipeline 失败时队列剩余标的静默丢失(实测 20 只只回 16 只) - 修 test_future_range_returns_empty_quickly 时间炸弹(固定日期会漂进 _BACKTRACK_GRACE) - conftest 关闭后台测速 task,避免污染「往返次数」类断言 实测(5,225 只):count=2 → 2.7s;count=35 → 2.2s;count=240 → 6.9s。 逐根一致性 30/30 相同。新增 tests/test_bulk_kline.py 12 项,合计 419 项全绿。 * test: 批量K线测试的时间锚点改用真实 now(CI 是 UTC,固定日期会漂到别的时段分支) * fix(ex): EX 通道 K 线回填成交额与结算价(0x23FF 槽位按市场分两类) 报告:EX 通道 get_bars 返回的 SecurityBar.amount 恒为 0.0。 定位属实,但实际情况比报告更细 —— 32B 记录里那 28B 行情只有**一个** 4B 槽位 可复用,语义按市场分两类(全市场实测,用 成交额/(close×vol) 逐条校验): | 市场 | 槽位5 | 槽位6 | 槽位7 | |---|---|---|---| | 港股主板31/港股基金49 | 成交额(f) | 量(手=100股) | 未知 | | 港股创业板48/新三板44/美股74 | 成交额(f) | 量(股) | 0 | | 期货/期权 7/8/9/47… | 持仓量(I) | 量 | 结算价(f) | 改前 amount 硬编码 0.0、第 7 个 float 用 `_` 丢弃 —— 于是港股/美股/新三板 明明帧内有成交额却全为 0,期货期权的结算价也拿不到。 - 新增 SecurityBar.settle(结算价,float|None):仅 EX 期货/期权日线有值, 分钟线该槽位恒 0 已归一化为 None,其它通道恒 None。 - 权益类市场回填真实 amount;港股主板/基金的 vol 单位是手(=100股), amount/vol 是均价的 100 倍,已写进模型注释与量纲表。 - 期货/期权的 amount 仍是 0.0(帧内确实没有成交额,协议限制), 已在 SecurityBar / API_REFERENCE / llms.txt / SKILL.md 写清, 避免使用者再按旧文档判断成调用方 bug。 - 港股指数27/中证指数62 该槽位量级对不上(既非额也非结算价),保守保持 0.0。 - SecurityBar.__setstate__ 兜底旧磁盘缓存:缓存键无 schema 版本,升级后读旧 pickle 缺 settle 槽位,默认反序列化不补默认值 → AttributeError,已容错; EX K 线缓存键额外加 @v2,让 amount 恒 0 的旧缓存自然失效。 - K 线 DataFrame 因此多一列 settle(0.7.0 未发布,列清单同步更新)。 测试:tests/test_ex_bars_fields.py 16 项(解析层双布局、日内 settle 归零、 API 透传、旧 pickle 兼容);全套 435 项通过。 * docs: 0.7.0 全站口径同步(DataFrame 出口 + EX 成交额限制 + 构造参数表) - 首页:特性表补「DataFrame 直出」与 K 线批量性能,导航新增 DataFrame 卡片, 统一方法数按实测修正为 35(+33 别名 = 68 个公开方法) - 安装页:补 extras(polars/pandas/dataframe)与 df 用法;构造参数表补 df / std_pool_cap / ex_pool_cap,并把 pool_max 默认值从 12 修正为 24(实际值) - 场景示例:`转成 pandas` 一节改为先推 df= 开关,手动转换降级为局部场景 - 数据模型页:不再说「刻意不提供 DataFrame」,改为 dataclass 与 DataFrame 是同一份数据、两种容器 - AI 接入页:返回值约定补 `df=` 开关的说法 - README:K 线列注释补 settle;已知限制补 EX 通道成交额/结算价的协议口径 - CHANGELOG:新增「升级」小节(升级命令、旧缓存无需清理) --------- Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
207 lines
7.3 KiB
Markdown
207 lines
7.3 KiB
Markdown
# 安装与配置
|
||
|
||
## 环境要求
|
||
|
||
| 项 | 要求 |
|
||
|---|---|
|
||
| Python | **≥ 3.11**(开发与 CI 覆盖 3.11 / 3.13) |
|
||
| 运行时依赖 | **无**(纯 stdlib:`socket` / `ssl` / `zlib` / `struct` / `sqlite3` / `asyncio`) |
|
||
| 操作系统 | 任意(Windows / Linux / macOS) |
|
||
| 网络 | 需能直连通达信行情服务器(标准/MAC 端口 **7709**,EX 端口 **7727**) |
|
||
|
||
## 安装
|
||
|
||
=== "pip"
|
||
|
||
```bash
|
||
pip install pytdxdata
|
||
```
|
||
|
||
=== "uv"
|
||
|
||
```bash
|
||
uv add pytdxdata
|
||
```
|
||
|
||
=== "源码开发"
|
||
|
||
```bash
|
||
git clone git@github.com:openbot-coder/pytdxdata.git
|
||
cd pytdxdata
|
||
uv sync # 建虚拟环境 + 装 CLI + 装测试依赖
|
||
.venv/Scripts/python.exe -c "import pytdxdata" # Windows
|
||
# .venv/bin/python -c "import pytdxdata" # Linux / macOS
|
||
```
|
||
|
||
安装后即可使用 `tdx` 命令行工具(见 [CLI 手册](cli.md))。
|
||
|
||
### 可选:DataFrame 后端(0.7.0+)
|
||
|
||
想让表格型接口**直接返回 DataFrame**,需要额外装一个后端。核心包依旧零依赖,不装就完全不受影响:
|
||
|
||
```bash
|
||
pip install "pytdxdata[polars]" # 只要 polars
|
||
pip install "pytdxdata[pandas]" # 只要 pandas
|
||
pip install "pytdxdata[dataframe]" # 两个都要
|
||
```
|
||
|
||
装上之后在构造时声明一次即可,详见 [DataFrame 输出](dataframe.md):
|
||
|
||
```python
|
||
async with TdxData(df="polars") as td: # 或 df="pandas"
|
||
df = await td.get_bars("sh600000", KlinePeriod.DAY, count=240)
|
||
```
|
||
|
||
### 可选:uvloop 加速
|
||
|
||
Linux / macOS 上可选用 `uvloop` 替换默认事件循环(Windows 不支持):
|
||
|
||
```bash
|
||
uv add --optional uvloop uvloop
|
||
```
|
||
|
||
```python
|
||
import uvloop, asyncio
|
||
uvloop.install() # 必须在 asyncio.run() 之前
|
||
asyncio.run(main())
|
||
```
|
||
|
||
## 构造参数
|
||
|
||
`TdxData` 全部参数为 **keyword-only**,都有合理默认值——99% 的场景直接 `TdxData()` 即可。
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `standard_servers` | `None` | 标准通道服务器清单;`None` = 用内置探测结果 |
|
||
| `mac_servers` | `None` | MAC 通道服务器清单;`None` = 用内置探测结果 |
|
||
| `ex_servers` | `None` | EX 扩展市场服务器清单;`None` = 用内置探测结果 |
|
||
| `port` | `7709` | 标准 / MAC 端口(EX 固定 `7727`) |
|
||
| `timeout` | `3.0` | 连接超时(秒) |
|
||
| `cache_dir` | `None` | 磁盘缓存目录;**`None` = 仅内存缓存**(进程退出即失效) |
|
||
| `default_adjust` | `Adjust.NONE` | 默认复权方式,可被单次调用覆盖 |
|
||
| `max_inflight` | `64` | single-flight 并发上限(同键请求合并) |
|
||
| `pool_min` / `pool_max` | `3` / `24` | 动态连接池上下限 |
|
||
| `mac_pool_cap` | `4` | 单台 MAC 服务器连接数上限 |
|
||
| `std_pool_cap` | `4` | 单台标准服务器连接数上限 |
|
||
| `ex_pool_cap` | `2` | 单台 EX 服务器连接数上限(EX 主机较少且较慢,压太高收益为负) |
|
||
| `df` | `None` | 表格型接口的返回形态:`None` = `list[dataclass]`(与 0.6.x 一致);`"polars"` / `"pandas"` = 直接返回 DataFrame。见 [DataFrame 输出](dataframe.md) |
|
||
|
||
### 典型配置
|
||
|
||
=== "最简(仅内存缓存)"
|
||
|
||
```python
|
||
async with TdxData() as td:
|
||
...
|
||
```
|
||
|
||
=== "生产(持久化缓存)"
|
||
|
||
```python
|
||
from pathlib import Path
|
||
|
||
async with TdxData(
|
||
cache_dir=Path.home() / ".cache" / "pytdxdata",
|
||
pool_min=4,
|
||
pool_max=16,
|
||
timeout=5.0,
|
||
) as td:
|
||
...
|
||
```
|
||
|
||
`cache_dir` 下会生成一个 SQLite 文件(WAL 模式)。**同一目录可被多个进程共享**,
|
||
适合「定时任务 + 交互式查询」并存的场景。
|
||
|
||
=== "自建服务器清单"
|
||
|
||
```python
|
||
async with TdxData(
|
||
standard_servers=["1.2.3.4", "5.6.7.8"],
|
||
mac_servers=["9.10.11.12"],
|
||
port=7709,
|
||
) as td:
|
||
...
|
||
```
|
||
|
||
主机元素**只填主机名**,端口由构造参数 `port=` 统一指定(不写在主机元素里)。
|
||
等价的免代码写法是环境变量 `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS`(逗号分隔)。
|
||
|
||
## 服务器清单
|
||
|
||
内置清单随包发布(`src/pytdxdata/servers.json`),由探测脚本生成:
|
||
|
||
```bash
|
||
python -m pytdxdata.server_probe # 重新探测并覆盖 servers.json
|
||
```
|
||
|
||
探测逻辑不是简单握手——它会**真实请求一段 K 线**,把「能连上但返回空数据」的坏节点剔除。
|
||
服务器可用性会随时间变化,连不上时优先重跑探测。
|
||
|
||
`pytdxdata.config` 提供读取接口:
|
||
|
||
```python
|
||
from pytdxdata.config import get_standard_hosts, get_mac_hosts, get_ex_hosts
|
||
|
||
print(len(get_standard_hosts()), len(get_mac_hosts()), len(get_ex_hosts()))
|
||
```
|
||
|
||
### 当日自动测速(无感)
|
||
|
||
除随包发布的静态清单外,`TdxData` 还在**当日首次启动**时做一次**后台全量测速**:
|
||
|
||
- 覆盖**全部候选**(包内清单 ∪ 代码内置常量 ∪ 环境变量覆盖),而不是只测当前池里的少数节点
|
||
——否则「上次慢、这次快」的节点永远捞不回来
|
||
- 用**真实 K 线命令**判定可达(标准 / MAC / EX 各发一条业务命令并要求非空),
|
||
能剔除「握手正常但返回空数据」的坏节点
|
||
- 结果按**实测延迟升序**写入**用户级缓存**,当天后续启动直接复用、**不再重测**
|
||
- 全程在后台进行:**不打印、不阻塞 `start()`、失败静默降级**,对调用方完全无感
|
||
|
||
缓存位置(可用 `PYPYTDX_DATA_CACHE_DIR` 覆盖):
|
||
|
||
| 平台 | 路径 |
|
||
|---|---|
|
||
| Windows | `%LOCALAPPDATA%\pytdxdata\hosts-today.json` |
|
||
| macOS | `~/Library/Caches/pytdxdata/hosts-today.json` |
|
||
| Linux / 其他 | `$XDG_CACHE_HOME/pytdxdata/hosts-today.json`(默认 `~/.cache/…`) |
|
||
|
||
主机选择的优先级(各协议独立):
|
||
|
||
1. `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS` 环境变量(手工指定,最高优先)
|
||
2. **当日测速缓存**中该协议实测可达的主机(按延迟升序)
|
||
3. 包内清单里 `status=ok` 的 `fast_pool` 主机
|
||
4. 包内清单里 `status=ok` 的主机
|
||
5. 代码内置常量
|
||
|
||
!!! note "缓存绝不写回安装目录"
|
||
测速结果只写入上面的**用户级缓存目录**。`site-packages` 在容器 / 系统级安装 / `pipx`
|
||
下可能只读,多用户共用一个安装时还会互相覆盖,因此包内 `servers.json` 不会被运行时改写。
|
||
|
||
环境变量一览:
|
||
|
||
| 变量 | 作用 |
|
||
|---|---|
|
||
| `PYPYTDX_DATA_STANDARD_HOSTS` / `…_MAC_HOSTS` / `…_EX_HOSTS` | 逗号分隔,手工指定主机(优先级最高,直接跳过测速缓存) |
|
||
| `PYPYTDX_DATA_CACHE_DIR` | 覆盖当日测速缓存目录 |
|
||
| `PYPYTDX_DATA_DISABLE_PROBE=1` | 关闭当日测速与缓存(CI / 测试用,保证确定性) |
|
||
|
||
## 生命周期
|
||
|
||
`TdxData` 必须在 `async with` 内使用,或手动 `await td.start()` / `await td.close()`:
|
||
|
||
```python
|
||
async with TdxData() as td: # __aenter__ → start()
|
||
...
|
||
# __aexit__ → close():关闭全部连接池、flush 缓存
|
||
```
|
||
|
||
!!! tip "长驻进程"
|
||
池与缓存都挂在 `TdxData` 实例上。Web 服务 / 常驻任务应该**只创建一个实例并复用**,
|
||
不要每次请求都 `TdxData()`——否则等于每请求重建连接池,缓存也失效。
|
||
推荐在 FastAPI 的 `lifespan` 里创建并放进依赖。
|
||
|
||
## 下一步
|
||
|
||
- [场景示例](cookbook.md) — 看真实用法
|
||
- [CLI 手册](cli.md) — 不写代码直接拿数据
|
||
- [接口总览](api/index.md) — 完整方法清单
|