上一提交只补了 getting-started / routing / llms.txt / SKILL.md 四处,本轮把其余 教程类页面与接口清单补齐,并顺手修正 v0.6.0 统一接口改造后遗留的过时说明。 补齐(当日测速缓存): - README「已知限制」:说明当日首次启动会自动后台测速并缓存 - FAQ 新增「启动时会变慢吗?会不会在后台偷偷联网?」:无感保证 + 三个环境变量开关 - FAQ「连不上服务器怎么办」:加入"删当日测速缓存 / 环境变量指定主机"两条前置排查 - API_REFERENCE 四、辅助模块:config 补全当日测速相关函数与优先级链说明, 新增 pytdxdata.pool.probe_cache 一节(ProbeCache / schedule_probe / get_probe_cache) - internals/architecture.md 目录树:config.py、probe_cache.py 的职责注释更新 - internals/cache-pool.md「下一步」:补「服务器是怎么选出来的」交叉链接 修正(v0.6.0 遗留过时描述): - FAQ / api/enums.md:删掉「所有接口的第一个参数都是 market」——统一接口已改为字符串标的 - FAQ / cookbook:`*_batch` 已并入 `get_bars`(多标的),不再作为批量入口 - FAQ / getting-started「自建服务器清单」:`standard_servers` 实际是 Sequence[str] 而非 (host, port) 元组(端口由统一的 port= 指定);原示例照抄会取到错的主机名 (已实测:字符串写法正确,元组写法不会被解析) 校验:check_docs.py exit 0;mkdocs build --strict 无告警;新增交叉链接 #当日自动测速无感 / #daily-probe 均正确渲染且目标锚点存在;全量 164 项通过; src/pytdxdata/servers.json 跑测前后逐字节不变。
187 lines
6.4 KiB
Markdown
187 lines
6.4 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))。
|
||
|
||
### 可选: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` / `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", "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) — 完整方法清单
|