原实现在 v0.5.0 已随包发布,但有三处会"静默失效"的缺陷,等于没真正生效: - 候选集自指:连接池把自己已过滤后的成员当探针输入,实测只重测了 9 台, 另外 20+ 台候选(含快节点)永远测不到。改为由 probe_cache 自行枚举 全量候选(包内清单 ∪ 代码常量 ∪ env),不再接受调用方传入的"当前池成员"。 - 写回安装目录:结果写回 src/pytdxdata/servers.json,容器/系统级安装下只读会 静默失败、多用户共用一个安装会互相覆盖,且污染随包分发的数据。改为写入 用户级缓存目录(Win %LOCALAPPDATA% / macOS ~/Library/Caches / Linux $XDG_CACHE_HOME), 运行时绝不再改写包内清单。 - 探测太弱:只做握手,测不出「握手正常但 K 线空响应」的坏节点。改为发真实业务 命令并要求返回非空(标准 GetSecurityBarsCmd / MAC MacKlineCmd / EX GetExInstrumentBarsCmd), EX 池(4 台,7727)也一并纳入。 无感保证:后台 task 不阻塞 start()、日志全 debug 级、绝不抛异常(取消除外)、 原子写 tmp + os.replace、进程内单例 + asyncio.Lock 单飞;全不可达时不写缓存 (否则"今天全挂"会被缓存一整天)。close() 会取消并 await 后台探针, 避免解释器退出时报 "Task was destroyed but it is pending"。 新增环境变量 PYPYTDX_DATA_CACHE_DIR(覆盖缓存目录)、 PYPYTDX_DATA_DISABLE_PROBE=1(关闭测速)。新增 tests/test_probe_cache.py(37 项)。
6.2 KiB
安装与配置
环境要求
| 项 | 要求 |
|---|---|
| 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 手册)。
可选:uvloop 加速
Linux / macOS 上可选用 uvloop 替换默认事件循环(Windows 不支持):
uv add --optional uvloop uvloop
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 / 12 |
动态连接池上下限 |
mac_pool_cap |
4 |
单台 MAC 服务器连接数上限 |
典型配置
=== "最简(仅内存缓存)"
```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", 7709), ("5.6.7.8", 7709)],
mac_servers=[("9.10.11.12", 7709)],
) as td:
...
```
服务器清单
内置清单随包发布(src/pytdxdata/servers.json),由探测脚本生成:
python -m pytdxdata.server_probe # 重新探测并覆盖 servers.json
探测逻辑不是简单握手——它会真实请求一段 K 线,把「能连上但返回空数据」的坏节点剔除。 服务器可用性会随时间变化,连不上时优先重跑探测。
pytdxdata.config 提供读取接口:
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/…) |
主机选择的优先级(各协议独立):
PYPYTDX_DATA_STANDARD_HOSTS/…_MAC_HOSTS/…_EX_HOSTS环境变量(手工指定,最高优先)- 当日测速缓存中该协议实测可达的主机(按延迟升序)
- 包内清单里
status=ok的fast_pool主机 - 包内清单里
status=ok的主机 - 代码内置常量
!!! 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():
async with TdxData() as td: # __aenter__ → start()
...
# __aexit__ → close():关闭全部连接池、flush 缓存
!!! tip "长驻进程"
池与缓存都挂在 TdxData 实例上。Web 服务 / 常驻任务应该只创建一个实例并复用,
不要每次请求都 TdxData()——否则等于每请求重建连接池,缓存也失效。
推荐在 FastAPI 的 lifespan 里创建并放进依赖。