Files
pytdxdata/docs/faq.md
T
openbot-coder 5408903a4c fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间
通达信 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 无日期分量可承载跨日信息。
2026-10-13 15:10:22 +08:00

195 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 常见问题
## 数据与来源
??? 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) — 每个版本改了什么