From 7e830c7579aa0b7be66210981539accf0a717b85 Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Mon, 21 Sep 2026 18:25:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E9=BD=90=E6=B5=8B=E9=80=9F?= =?UTF-8?q?=E7=BC=93=E5=AD=98=E7=9B=B8=E5=85=B3=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E5=B9=B6=E4=BF=AE=E6=8E=89=200.6.0=20=E9=81=97=E7=95=99?= =?UTF-8?q?=E7=9A=84=E8=BF=87=E6=97=B6=E6=8F=8F=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一提交只补了 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 跑测前后逐字节不变。 --- README.md | 3 ++- docs/API_REFERENCE.md | 23 ++++++++++++++++--- docs/api/enums.md | 4 ++-- docs/cookbook.md | 2 +- docs/faq.md | 42 ++++++++++++++++++++++++++-------- docs/getting-started.md | 8 +++++-- docs/index.md | 3 ++- docs/internals/architecture.md | 4 ++-- docs/internals/cache-pool.md | 1 + 9 files changed, 69 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 06b40b9..a2c7a68 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,8 @@ uv run mkdocs serve # 本地预览文档站 - 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情 - 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避 - 港股 / 美股期权在通达信协议内无数据 -- 服务器可用性随时间变化,可用 `python -m pytdxdata.server_probe` 重新探测 +- 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测); + 也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单 ## 免责声明 diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index c770d5b..54b1058 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -232,14 +232,31 @@ from pytdxdata import ( | `boll(values, period=20, mult=2.0)` | 布林带 | | `compute_indicators(high, low, close, indicators, params=None, tail=None)` | 统一入口(被 `get_stock_kline_with_indicators` 调用) | -**`pytdxdata.config`**(服务器清单) +**`pytdxdata.config`**(服务器清单与选路) -| 函数 | 说明 | +主机来源优先级链(各协议独立):`PYPYTDX_DATA_*_HOSTS` 环境变量 → **当日测速缓存** → +包内清单 `fast_pool` → 包内清单 → 代码内置常量。 + +| 函数 / 常量 | 说明 | |------|------| -| `get_standard_hosts()` | 标准通道服务器列表 | +| `get_standard_hosts()` | 标准通道服务器列表(按上述优先级链解析) | | `get_mac_hosts()` | MAC 通道服务器列表 | | `get_ex_hosts()` | EX 扩展市场服务器列表 | | `get_ex_handshakes()` | EX 握手方式映射 | +| `all_probe_candidates()` | 全量候选主机 `{standard, mac, ex}`(清单 ∪ 常量 ∪ env,**不按状态过滤**) | +| `is_valid_host(host)` | 主机名合法性校验(挡 mock 脏数据 / 非法条目) | +| `probe_cache_dir()` / `probe_cache_file()` | 用户级当日测速缓存目录 / 文件路径 | +| `load_probe_cache(today=None, path=None)` | 读当日测速缓存;缺失 / 损坏 / 非今日 / 版本不符 → `None` | +| `probe_disabled()` | 是否已用 `PYPYTDX_DATA_DISABLE_PROBE` 关闭测速 | +| `PROBE_CACHE_VERSION` | 测速缓存 payload 版本号 | + +**`pytdxdata.pool.probe_cache`**(当日测速:后台执行、对用户无感) + +| 符号 | 说明 | +|------|------| +| `ProbeCache` | 进程内协调器;`ensure_probe()` 为幂等入口(单飞 + 原子写) | +| `schedule_probe(hosts=None)` | 连接池用:挂后台 task 并返回该 task;无事件循环时返回 `None` | +| `get_probe_cache()` | 取进程级单例 | **`pytdxdata.server_probe`**(服务器探测,可 `python -m pytdxdata.server_probe` 运行) `load_servers()` / `save_servers(cfg)` / `SERVERS_FILE` diff --git a/docs/api/enums.md b/docs/api/enums.md index a257ad4..21f1351 100644 --- a/docs/api/enums.md +++ b/docs/api/enums.md @@ -18,8 +18,8 @@ from pytdxdata.models import Adjust, ExMarket, KlinePeriod, Market | `Market.BJ` | `2` | 北京(北交所) | !!! warning "代码不唯一" - **市场 + 代码**才唯一。`(SH, "000001")` 是上证指数,`(SZ, "000001")` 是平安银行。 - 所有接口的第一个参数都是 `market`,就是为了消歧。 + **市场 + 代码**才唯一。`sh000001` 是上证指数,`sz000001` 是平安银行。 + 统一接口用**字符串标的**把两者一起表达(前缀即市场),避免只写 6 位数字时的歧义。 ## KlinePeriod — K 线周期 diff --git a/docs/cookbook.md b/docs/cookbook.md index 570b584..07d2b94 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -11,7 +11,7 @@ from pytdxdata.models import Adjust, KlinePeriod ## 全市场日线批量落库 -连接池会把不同股票分配到不同服务器,这是 `*_batch` 存在的意义。 +传多标的时,连接池会把不同股票分配到不同服务器——这正是它比逐个 `await` 快的原因。 ```python async def dump_all_daily(): diff --git a/docs/faq.md b/docs/faq.md index c944a71..34986cb 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -19,7 +19,8 @@ | SH | `000001` | 上证指数 | | SZ | `000001` | 平安银行 | - 代码不唯一,**市场 + 代码**才唯一。这也是为什么所有接口的第一个参数都是 `market`。 + 代码不唯一,**市场 + 代码**才唯一。统一接口用**字符串标的**把两者一起表达 + (`sh000001` / `sz000001`),避免只写 6 位数字时的歧义。 ??? question "为什么报价格式有时候是 2 位小数,有时候是 3 位?" 价格小数位按**品种**推断:股票 2 位,指数 / ETF / 可转债 3 位。 @@ -28,17 +29,40 @@ ## 连接与网络 ??? question "连不上服务器 / 全部超时怎么办?" - 服务器可用性会随时间变化(下线、换 IP、封禁)。按顺序排查: + 服务器可用性会随时间变化(下线、换 IP、封禁)。本包**当日首次启动会自动后台测速**并把 + 可达主机按延迟排序缓存,多数情况下无需手工干预。按顺序排查: - 1. 重新探测:`python -m pytdxdata.server_probe` - 2. 手工指定清单绕过探测结果: - ```python - async with TdxData(standard_servers=[("1.2.3.4", 7709)]) as td: ... + 1. **删掉当日测速缓存**,让下次启动重新测速——缓存里可能存着今天刚挂掉的节点 + (路径见 [安装与配置](getting-started.md#当日自动测速无感))。 + 2. 手工指定主机。优先级最高,**直接跳过测速与缓存**: + ```bash + PYPYTDX_DATA_STANDARD_HOSTS=1.2.3.4,5.6.7.8 python your_script.py ``` - 3. 检查出口网络策略——标准 / MAC 端口 **7709**、EX 端口 **7727** 需要放通。 - 4. 若在用代理软件,注意有些本地代理会劫持回环 TCP,导致 asyncio 建事件循环都卡住 + + 或在代码里传入(**只填主机名**,端口由 `port=` 统一指定): + ```python + async with TdxData(standard_servers=["1.2.3.4"]) as td: ... + ``` + 3. 离线重生成随包清单(该脚本会真实拉一段 K 线,剔除「握手正常但返回空」的坏节点): + ```bash + python -m pytdxdata.server_probe + ``` + 4. 检查出口网络策略——标准 / MAC 端口 **7709**、EX 端口 **7727** 需要放通。 + 5. 若在用代理软件,注意有些本地代理会劫持回环 TCP,导致 asyncio 建事件循环都卡住 (见下方「在 Windows 上测试卡死」)。 +??? question "启动时会变慢吗?会不会在后台偷偷联网?" + 会有一次**当日首次启动测速**,但完全在后台,对调用方无感: + + - **不阻塞** `start()`、**不打印**任何东西、失败**静默降级**(绝不抛给调用方) + - 结果只缓存到用户级目录(**不写安装目录**),**当天后续启动直接复用、不再重测** + - 覆盖**全部候选**主机(含暂时被挤下去的),所以「上次慢、这次快」的节点能回来 + + 三个开关:`PYPYTDX_DATA_DISABLE_PROBE=1` 关掉测速、 + `PYPYTDX_DATA_CACHE_DIR` 改缓存位置、 + `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 强制指定主机。 + 详见 [安装与配置 → 当日自动测速](getting-started.md#当日自动测速无感)。 + ??? question "公司网络 / 代理环境下失败" 通达信协议是裸 TCP,不走 HTTP 代理。如果环境强制走代理,需要把 `7709` / `7727` 配成直连(bypass)。云服务器上常见问题是安全组只放通了 80/443。 @@ -49,7 +73,7 @@ | 场景 | 建议 | |---|---| | 偶发查询、CLI | 默认即可 | - | 批量落库(`*_batch`) | `pool_max=16`、`concurrency=8~16` | + | 批量落库(`get_bars` 传多标的) | `pool_max=16`、`concurrency=8~16` | | Web 服务多并发 | `pool_max=24`,并确保单实例复用 | 再大只是排队,不会更快——瓶颈是对端服务器的连接上限。 diff --git a/docs/getting-started.md b/docs/getting-started.md index dde9f80..2c8bcbd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -96,12 +96,16 @@ asyncio.run(main()) ```python async with TdxData( - standard_servers=[("1.2.3.4", 7709), ("5.6.7.8", 7709)], - mac_servers=[("9.10.11.12", 7709)], + 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`),由探测脚本生成: diff --git a/docs/index.md b/docs/index.md index 7fb6429..cec796e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -104,7 +104,8 @@ asyncio.run(main()) ## 数据来源与限制 - 行情来自通达信**公开**行情服务器(无需账号),**15 分钟延时**;需实时数据请使用券商行情 -- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成,可用性随时间变化 +- 服务器清单由 `python -m pytdxdata.server_probe` 探测生成;运行时**当日首次启动会自动在后台测速并缓存** + (对调用方无感,当天不再重测),可用性随时间变化 - 港股 / 美股 / 期货 / 期权走通达信 EX 通道(端口 7727),部分市场(美股期权、港股期权)协议内无数据 完整清单见 [常见问题](faq.md)。 diff --git a/docs/internals/architecture.md b/docs/internals/architecture.md index 3451415..4d1fda3 100644 --- a/docs/internals/architecture.md +++ b/docs/internals/architecture.md @@ -23,7 +23,7 @@ src/pytdxdata/ ├── api.py # 统一接口 TdxData(对外唯一入口) ├── symbols.py # 标的解析:字符串 → Symbol(parse_symbol / format_symbol / market_targets) ├── router.py # 标准 / MAC / EX 通道选路 -├── config.py # 服务器清单加载(servers.json) +├── config.py # 服务器清单加载 + 选路优先级链 + 用户级测速缓存路径 ├── indicator.py # 技术指标(纯函数,无依赖) ├── server_probe.py # 服务器探测,可 python -m 运行 ├── protocol/ # 协议层 @@ -39,7 +39,7 @@ src/pytdxdata/ │ ├── pool.py # 标准 / MAC 动态池 │ ├── ex_pool.py # EX 池 │ ├── health.py # 健康分与选路 -│ └── probe_cache.py # 探测结果缓存 +│ └── probe_cache.py # 当日全量测速 + 用户级缓存(后台、无感) ├── scheduler/ │ └── paginator.py # 并发分页调度(3 连接并行) ├── cache/ diff --git a/docs/internals/cache-pool.md b/docs/internals/cache-pool.md index 4db88fd..b2c2e45 100644 --- a/docs/internals/cache-pool.md +++ b/docs/internals/cache-pool.md @@ -110,4 +110,5 @@ count=2400 → 3 页 → 3 个连接并行 → 按序拼接 ## 下一步 - [架构总览](architecture.md) — 这些模块在整体里的位置 +- [通道与数据源](routing.md#daily-probe) — 服务器是怎么选出来的(当日测速缓存) - [常见问题](../faq.md) — 缓存与超时的排查