通达信 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 无日期分量可承载跨日信息。
195 lines
9.2 KiB
Markdown
195 lines
9.2 KiB
Markdown
# 常见问题
|
||
|
||
## 数据与来源
|
||
|
||
??? question "数据是实时的吗?"
|
||
不是。行情来自通达信**公开**行情服务器,本身是 **15 分钟延时**数据。
|
||
|
||
需要实时数据请使用券商行情(迅投 QMT / 兴业 SMT-Q / 同花顺 等)。
|
||
本项目定位是**历史数据与研究**——日线、分钟线、逐笔、财报这些历史数据是完整且稳定的。
|
||
|
||
??? question "需要账号吗?要付费吗?"
|
||
不需要。通达信公开行情服务器无需注册,直接 TCP 连接即可。本项目也不收任何费用。
|
||
|
||
??? question "为什么 SHA 000001 和 SZ 000001 完全不一样?"
|
||
同一个 6 位代码在不同市场里是**不同标的**:
|
||
|
||
| 市场 | 代码 | 标的 |
|
||
|---|---|---|
|
||
| SH | `000001` | 上证指数 |
|
||
| SZ | `000001` | 平安银行 |
|
||
|
||
代码不唯一,**市场 + 代码**才唯一。统一接口用**字符串标的**把两者一起表达
|
||
(`sh000001` / `sz000001`),避免只写 6 位数字时的歧义。
|
||
|
||
??? question "为什么报价格式有时候是 2 位小数,有时候是 3 位?"
|
||
价格小数位按**品种**推断:股票 2 位,指数 / ETF / 可转债 3 位。
|
||
模型里的 `decimal_point` 字段就存了这个信息,需要自己格式化时以它为准。
|
||
|
||
## 连接与网络
|
||
|
||
??? question "连不上服务器 / 全部超时怎么办?"
|
||
服务器可用性会随时间变化(下线、换 IP、封禁)。本包**当日首次启动会自动后台测速**并把
|
||
可达主机按延迟排序缓存,多数情况下无需手工干预。按顺序排查:
|
||
|
||
1. **删掉当日测速缓存**,让下次启动重新测速——缓存里可能存着今天刚挂掉的节点
|
||
(路径见 [安装与配置](getting-started.md#当日自动测速无感))。
|
||
2. 手工指定主机。优先级最高,**直接跳过测速与缓存**:
|
||
```bash
|
||
PYPYTDX_DATA_STANDARD_HOSTS=1.2.3.4,5.6.7.8 python your_script.py
|
||
```
|
||
|
||
或在代码里传入(**只填主机名**,端口由 `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。
|
||
|
||
??? question "连接池要配多大?"
|
||
默认 `pool_min=3 / pool_max=12` 覆盖绝大多数场景。经验值:
|
||
|
||
| 场景 | 建议 |
|
||
|---|---|
|
||
| 偶发查询、CLI | 默认即可 |
|
||
| 批量落库(`get_bars` 传多标的) | `pool_max=16`、`concurrency=8~16` |
|
||
| Web 服务多并发 | `pool_max=24`,并确保单实例复用 |
|
||
|
||
再大只是排队,不会更快——瓶颈是对端服务器的连接上限。
|
||
|
||
## 数据正确性
|
||
|
||
??? question "K 线 `count` 给很小的时候返回空?"
|
||
已知问题:标准通道部分服务器在 `count < 100` 时返回空数据。
|
||
分页器已强制 `min_page=100` 规避,正常调用不会触发。
|
||
若你绕过分页器直接把 `start/count` 传给底层命令,需要自己处理。
|
||
|
||
??? question "1 分钟 K 线明明能并发,为什么是串行的?"
|
||
**刻意设计**。并发分页会把不同页分配到不同服务器,而各服务器的历史深度不一致;
|
||
拼接深度不同的分页,`stop_when_short` 会导致**非确定性数据丢失**。
|
||
所以 `KlinePeriod.MIN_1` 强制路由到 MAC 通道并**单连接串行分页**。
|
||
|
||
其他周期(`MIN_5` 及以上)不受影响,仍走并发分页。
|
||
|
||
??? question "为什么日线数据和券商软件对不上?"
|
||
按顺序检查:
|
||
|
||
1. **复权方式**是否一致 —— 券商常默认前复权,而本包默认 `Adjust.NONE`(不复权)
|
||
2. **是否含未收盘的那根** —— 盘中最后一根是动态的
|
||
3. 分钟线注意**数据来源深度**不同
|
||
|
||
??? question "美股分钟 K 线的时间为什么跨了两个日期?"
|
||
**已在上游修好(v0.6.2)**。通达信 EX 通道对美股返回的原生时间戳把两个时区拼在一起:
|
||
日期分量是**美东交易日**、时分分量是**北京时间**。修复前,同一交易日的 390 根会全部
|
||
落在同一个北京自然日里,并且下午半场被排在上午半场**之前**。
|
||
|
||
现在 `SecurityBar.datetime` 已统一为**北京时间**(凌晨段日期自动 +1 天),可直接排序 /
|
||
过滤 / 做增量水位线。但要注意**美股一个交易日横跨两个北京自然日**:
|
||
|
||
```python
|
||
bars = await td.get_bars("usAAPL", KlinePeriod.MIN_1, count=390)
|
||
print(bars[0].datetime, bars[-1].datetime) # 2026-10-12 21:31:00 → 2026-10-13 04:00:00
|
||
print({b.trading_date for b in bars}) # {'2026-10-12'} —— 同一个交易日
|
||
```
|
||
|
||
按**交易日**聚合(分钟线合成日线、日内统计)请用 `b.trading_date`,不要用
|
||
`b.datetime.date()`。A股 / 港股 / 期货原始即为北京时间,不受影响。
|
||
|
||
??? question "缓存会不会返回过期数据?"
|
||
缓存按数据类型分级 TTL,不会返回超出 TTL 的数据:
|
||
|
||
| 数据类型 | TTL |
|
||
|---|---|
|
||
| 实时报价 | 5s |
|
||
| 分钟 K 线 | 60s |
|
||
| 日 K 线 | 当天 |
|
||
| 复权 K 线 | 1 天 |
|
||
| 历史逐笔 | 永久 |
|
||
|
||
需要绕开缓存时,用新的 `cache_dir`,或直接不传 `cache_dir`(仅内存缓存)。
|
||
|
||
## 市场覆盖
|
||
|
||
??? question "支持哪些市场?"
|
||
**标准通道**:沪 / 深 / 北(A 股)、指数、ETF、可转债。
|
||
**EX 通道**:港股、美股、期货、期权等 **46 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
|
||
|
||
??? question "美股期权 / 港股期权能拿吗?"
|
||
不能。通达信协议内**无美股 / 港股期权数据**。
|
||
美股期权可用 CBOE 公开接口获取。
|
||
|
||
??? question "数据能存下来离线用吗?"
|
||
能。所有方法返回的都是纯 Python `dataclass`,序列化完全自主。
|
||
服务器文件类的解析方法(板块 / 行业 / 财报)尤其适合做「快照落盘」——
|
||
解析后就是普通 dataclass,落 JSON 后**完全脱网可用**。见 [场景示例](cookbook.md#offline-block-snapshot)。
|
||
|
||
## 开发与测试
|
||
|
||
??? question "本机 `uv run pytest` 报 trampoline 错误?"
|
||
Windows 上已知问题。直接调 venv 里的解释器:
|
||
|
||
=== "Windows"
|
||
|
||
```bash
|
||
.venv/Scripts/python.exe -m pytest tests/ -q
|
||
```
|
||
|
||
=== "Linux / macOS"
|
||
|
||
```bash
|
||
.venv/bin/python -m pytest tests/ -q
|
||
```
|
||
|
||
??? question "本地测试卡死 / asyncio 事件循环建不起来?"
|
||
**根因**:Windows 上 `asyncio.new_event_loop()` 内部要建一个 `socket.socketpair()`,
|
||
走的是回环 TCP;**本地代理软件 / 安全软件会拦截回环连接**,导致建循环永久挂起。
|
||
|
||
表现:`asyncio.new_event_loop()`、`asyncio.run()`、`pytest-asyncio` 全部挂起。
|
||
|
||
规避办法(任选):
|
||
|
||
1. 退出或放行本地代理软件,让 `127.0.0.1` 回环连通;
|
||
2. 在 WSL / Linux 环境里跑异步测试;
|
||
3. 对不 `await` 真实 Future 的协程,可以同步驱动验证:
|
||
```python
|
||
coro = some_coroutine()
|
||
try:
|
||
coro.send(None)
|
||
except StopIteration as e:
|
||
result = e.value
|
||
```
|
||
|
||
> 这也是 CI 放在 Linux 上跑的原因——Windows 侧无法做首轮异步验证。
|
||
|
||
??? question "和 pytdx / easy-tdx 什么关系?"
|
||
| 项目 | 关系 |
|
||
|---|---|
|
||
| [easy-tdx](https://github.com/handsomejustin/easy_tdx) | **参照实现**。协议层独立实现,不依赖其包,只参照字节级格式;解决了它无连接池、串行分页、单连接单锁的问题 |
|
||
| [pytdx](https://github.com/rainx/pytdx) | 上游生态。本包**不依赖** pytdx,但对 EX 通道(7727)沿用 pytdx 的扩展市场协议 |
|
||
|
||
## 下一步
|
||
|
||
- [参与贡献](contributing.md) — 报 bug / 提 PR / 跑测试
|
||
- [更新日志](changelog.md) — 每个版本改了什么
|