diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d164f0..c076a86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,48 +2,6 @@ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 -## [0.6.2] - 2026-10-13 - -### 修复 - -- **美股分钟级 K 线的 `datetime` 全部错位**(`get_bars("usAAPL", KlinePeriod.MIN_1)`)。 - - 通达信 EX 通道返回的美股分钟线时间戳,把**两个时区拼进了同一个五元组**:日期分量是 - **美东交易日**(协议里的 `zipday`),时分分量却是**北京时间**(`tminutes`)。直拼出的 - `datetime` 会把同一交易日的**下午半场排到上午半场之前**——单日 390 根不仅首末颠倒, - 而且全部落在同一个北京自然日里。于是任何依赖 `datetime` 的行为都是错的:排序、 - `count` 切片("取最新 N 根")、日期区间二分与过滤、增量更新水位线。 - - | 观测项 | 修复前 | 修复后 | - |---|---|---| - | 单日 390 根的日期分布 | **全部**落在 10-12(hour 0~23 混在一起) | 10-12 的 21:31~23:59(149 根)+ 10-13 的 00:00~04:00(241 根) | - | 时间轴 | 上午半场被排到下午半场**之前** | 严格单调递增 | - | `count=30` 是否取到真正最新的 30 根 | 否(拿到上一交易日的 23:30~23:59) | 是(当日收盘段 03:31~04:00) | - | 每组首根 `open` / 末根 `close` 对日线 | 对不上 | **逐位相同**(10-07/08/09/12 四个交易日实测) | - - 现在 `SecurityBar.datetime` **统一为北京时间**:美股凌晨段(北京 hour < 12)的日期 - 自动 +1 天(含月末 / 年末进位)。A股 / 港股 / 期货原始即为北京时间,**零行为变化**。 - - 新增两个只读属性: - - | 属性 | 用途 | - |---|---| - | `SecurityBar.trading_date` | 该 bar 归属的交易日 `YYYY-MM-DD`。美股一个交易日横跨两个北京自然日,**按交易日聚合(分钟线合成日线、日内统计)必须用它,不能用 `datetime.date()`** | - | `SecurityBar.is_us` | 是否美股(EX 通道 `US_STOCK`) | - - 归一化在 `SecurityBar.__post_init__` 中实现,因此 **EX 的两条 K 线命令路径** - (`_bars_ex` 的 0x23FF 与日期区间二分所依赖的 MAC 0x122E)自动共用同一份口径, - 不会出现"取数按一套时间、二分按另一套时间"的错位。 - -### 说明 - -- 分钟线缓存 TTL 为 **60 秒**,升级后旧缓存最多残留 1 分钟即自然失效,**无需手动清理**; - 日线(`period >= DAY`)不受本缺陷影响。 -- 本版只修 K 线。**同日发现的同类问题未包含在内**:EX 分时(`get_minutes`)对美股返回的 - `MinuteBar.hour` 是**未取模的连续分钟数**(实测可达 27,即次日 03:xx),且 `MinuteBar` - 无日期分量可承载跨日信息——修法涉及"是否新增字段 / 日期如何归属"的取舍,留待下一版决策。 -- 新增 9 项针对性回归测试(分界点、月末与年末进位、390 根整日单调性、MAC 路径同样归一化)。 - ## [0.6.1] - 2026-09-21 ### 变更 diff --git a/README.md b/README.md index 5440556..a7a0762 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md --create-dirs \ ```bash uv sync # 建虚拟环境 + 注册 tdx 命令 -uv run pytest tests/ # 191 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存) +uv run pytest tests/ # 182 个测试用例(协议 / 池 / 缓存 / 分页 / 全接口回归 / 文件解析 / CLI / 文档漂移 / 当日测速缓存) uv sync --group docs # 文档站依赖(mkdocs-material + mkdocstrings) uv run mkdocs serve # 本地预览文档站 ``` @@ -114,9 +114,6 @@ uv run mkdocs serve # 本地预览文档站 - 行情来自通达信公开服务器,**15 分钟延时**;需实时数据请使用券商行情 - 标准通道 K 线 `count < 100` 部分服务器返回空 → 分页器已强制 `min_page=100` 规避 - 港股 / 美股期权在通达信协议内无数据 -- **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文把「美东交易日日期」与「北京时间时分」 - 拼在一起,库已自动归一化,`bar.datetime` 可直接排序 / 过滤;但**美股一个交易日横跨两个北京 - 自然日**,按交易日聚合请用 `SecurityBar.trading_date`,不要用 `datetime.date()` - 服务器可用性随时间变化。**当日首次启动会自动在后台测速并缓存**(对调用方无感,当天不再重测); 也可用 `python -m pytdxdata.server_probe` 离线重生成随包清单。 缓存路径与三个开关见 [安装与配置 → 当日自动测速](https://openbot-coder.github.io/pytdxdata/getting-started/#当日自动测速无感) diff --git a/SKILL.md b/SKILL.md index 736437d..b03f5d1 100644 --- a/SKILL.md +++ b/SKILL.md @@ -164,7 +164,6 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 - **数据有 15 分钟延时**(通达信公开服务器特性)。要实时数据请用券商行情。 - **复权 K 线与 1 分钟 K 线走 MAC 通道**。`get_bars(..., adjust=Adjust.QFQ)` 自动切换。 -- **K 线时间戳统一为北京时间**(v0.6.2 起)。美股原始报文里日期是美东交易日、时分是北京时间(两个时区拼在一起),库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。但**美股一个交易日横跨两个北京自然日**,按交易日聚合(分钟线合成日线、日内统计)必须用 `bar.trading_date`。 - **`count` 很大时会自动多连接并发分页**,无需手动翻页。但标准通道 K 线 `count < 100` 部分服务器会返回空——内部已强制 `min_page=100` 规避。 - **`get_quotes` 一次 >80 只自动切批**;走 MAC 字段位通道(`fields=`)时上限为 80 只/次。 - **历史逐笔没有笔数字段**,只有当日逐笔的 `trade_count` 有效。 @@ -184,7 +183,6 @@ await td.get_bars("cffex:IFL0", KlinePeriod.DAY, count=700) # 期货合约 | 用 `get_block_info` 又自己拆二进制 | 白写解析器 | 用 `get_block_parsed`,已经解析好了 | | 循环里逐个 `await get_bars` | 慢 | 用列表传多个标的,自动并发 | | 港股/美股五档 bid/ask | 没有(协议不支持) | `fields` 字段位通道有 name 但无五档 | -| 美股分钟线用 `datetime.date()` 分组做日聚合 | 一个交易日被拆成两天(美股跨北京零点) | 用 `bar.trading_date`;`bar.datetime` 是归一化后的北京时间 | | 依赖实时性做信号 | 数据是 15 分钟前的 | 换券商实时源 | | 手动改包内 `servers.json` / 写死 IP | 容器只读、升级被覆盖、快节点捞不回来 | 日常靠内置的**当日测速缓存**自动选路;要强制指定就用 `PYPYTDX_DATA_{STANDARD,MAC,EX}_HOSTS` 环境变量 | diff --git a/docs/api/models.md b/docs/api/models.md index 1c76781..7da0fec 100644 --- a/docs/api/models.md +++ b/docs/api/models.md @@ -62,22 +62,6 @@ from pytdxdata.models import BoardInfo, MemberQuote, AuctionItem, CapitalFlow | 结构 | 具名属性(`zongguben`、`jingzichan` ...) | `fields: list[float]`,原始字段数组 | | 单位 | 万元 / 万股 | 原始 float,需自行按字段语义换算 | -!!! tip "`SecurityBar.datetime` 的时间戳口径(v0.6.2 起)" - 时间统一为**北京时间**。A股 / 港股 / 期货的原始时间戳即为北京时间;美股的原始报文 - 混用了「美东交易日日期」与「北京时间时分」两个时区,库在构造时已自动归一化 - (凌晨段日期 +1 天),因此 `bar.datetime` 可直接排序 / 比较 / 过滤。 - - 但要注意**美股一个交易日横跨两个北京自然日**,按交易日聚合请用 `bar.trading_date`: - - ```python - bars = await td.get_bars("usAAPL", KlinePeriod.MIN_1, count=390) - bars[0].datetime # 2026-10-12 21:31:00(北京时间) - bars[-1].datetime # 2026-10-13 04:00:00(次日) - bars[0].trading_date # "2026-10-12" —— 归属的美东交易日 - ``` - - `bar.is_us` 可判定是否美股。详见 [常见问题 → 美股分钟 K 线](../faq.md)。 - ## 完整字段定义 以下由 `mkdocstrings` 从源码实时渲染(**以源码为准**): diff --git a/docs/faq.md b/docs/faq.md index d262d56..34986cb 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -99,23 +99,6 @@ 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 的数据: diff --git a/docs/llms.txt b/docs/llms.txt index 8c83f38..992e501 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -93,10 +93,6 @@ tdx financial gpcw20260331.zip --limit 5 - **`KlinePeriod.MIN_1` 走 MAC 通道并单连接串行分页**,这是刻意设计:并发分页在多服务器 历史深度不一致时会产生非确定性数据空洞。不要试图"优化"成并发。 - **复权 K 线走 MAC 通道**,标准通道不提供复权数据。 -- **K 线 `datetime` 统一为北京时间**(v0.6.2 起)。美股原始报文的日期分量是美东交易日、 - 时分分量是北京时间,库已自动归一化,`bar.datetime` 可直接排序 / 比较 / 过滤。 - 但**美股一个交易日横跨两个北京自然日**:按交易日聚合(分钟线合成日线、日内统计) - 用 `bar.trading_date`,不要用 `bar.datetime.date()`。`bar.is_us` 判定美股。 - **标准通道部分服务器在 `count < 100` 时返回空**,分页器已强制 `min_page=100` 规避。 - **本地 Windows 上 `asyncio.new_event_loop()` 可能永久挂起**,根因是回环 `socket.socketpair()` 被本地代理/安全软件拦截。异步测试请在 Linux/WSL 运行。 diff --git a/pyproject.toml b/pyproject.toml index 76567d9..cfbe854 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pytdxdata" -version = "0.6.2" +version = "0.6.1" description = "通达信(TongDaXin)行情数据客户端:动态连接池 + 双层TTL缓存 + 3连接并发分页,纯asyncio零运行时依赖,支持A股/港股/美股/期货/期权" readme = "README.md" requires-python = ">=3.11" diff --git a/src/pytdxdata/__init__.py b/src/pytdxdata/__init__.py index b2eb91f..29fbd4f 100644 --- a/src/pytdxdata/__init__.py +++ b/src/pytdxdata/__init__.py @@ -16,7 +16,7 @@ from .models import ( XdxrRecord, ) -__version__ = "0.6.2" +__version__ = "0.6.1" __all__ = [ "TdxData", "Market", diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index 9f4459a..a91abef 100644 --- a/src/pytdxdata/models/__init__.py +++ b/src/pytdxdata/models/__init__.py @@ -3,7 +3,7 @@ from __future__ import annotations import struct from dataclasses import dataclass, field -from datetime import date, datetime, timedelta +from datetime import datetime from enum import IntEnum from typing import Any @@ -92,25 +92,9 @@ class Adjust(IntEnum): HFQ = 2 # 后复权 -# 扩展市场中「时间戳跨时区拼接」的市场号:通达信 EX 通道对美股返回的分钟级 K线 -# 里,日期字段是**美东交易日**、时分字段是**北京时间**,两个时区被拼进同一个 -# 五元组,必须归一化(见 SecurityBar.__post_init__)。 -_US_EX_MARKETS: frozenset[int] = frozenset({int(ExMarket.US_STOCK)}) - -# 归一化判据:北京时间 hour >= 12 的 bar 与美东交易日属同一自然日。美股常规时段 -# 09:30~16:00 EDT = 北京 21:30~次日 04:00(冬令时 22:30~次日 05:00),夏令时/ -# 冬令时下分界都稳定落在 12 点。 -_US_DAY_SPLIT_HOUR = 12 - - @dataclass(slots=True) class SecurityBar: - """K线记录(价格单位:元)。跨市场统一模型(A股/港股/美股/期货共用)。 - - 时间戳口径**统一为北京时间**:A股/港股/期货原始即为北京时间;美股原始是 - 「日期=美东交易日 + 时分=北京时间」的混合值,构造时已还原为真实北京时间 - (见 ``__post_init__``)。该 bar 归属的交易日见 :attr:`trading_date`。 - """ + """K线记录(价格单位:元)。跨市场统一模型(A股/港股/美股/期货共用)。""" market: int code: str open: float @@ -126,40 +110,10 @@ class SecurityBar: minute: int = 0 symbol: str = "" # 规范化标的串(sz000001 / hk00700),由 API 层填充 - def __post_init__(self) -> None: - """美股(EX 通道)时间戳归一化:还原成真实北京时间。 - - 原始报文里 ``zipday`` 是**美东交易日**、``tminutes`` 是**北京时间分钟数**, - 直拼出的 ``datetime`` 会把同一交易日的下午半场(北京 00:00~04:00)排到 - 上午半场(北京 21:30~23:59)**之前** —— 单日 390 根全部错位、首末颠倒。 - 这里把凌晨段(北京 hour < 12)的日期 +1 天,得到严格单调的北京时间序列。 - """ - if self.market in _US_EX_MARKETS and self.hour < _US_DAY_SPLIT_HOUR: - d = date(self.year, self.month, self.day) + timedelta(days=1) - self.year, self.month, self.day = d.year, d.month, d.day - - @property - def is_us(self) -> bool: - """是否美股(EX 通道 ``US_STOCK``)。""" - return self.market in _US_EX_MARKETS - @property def datetime(self) -> datetime: - """bar 的时刻(北京时间)。""" return datetime(self.year, self.month, self.day, self.hour, self.minute) - @property - def trading_date(self) -> str: - """该 bar 归属的交易日,``YYYY-MM-DD``。 - - 美股:``datetime`` 已还原为北京时间,凌晨段(北京 hour < 12)属于**前一天** - 的美东交易日,故回退一天;A股/港股/期货的交易日即自然日。按交易日聚合 - (如分钟线合成日线)时应当用本字段,而不是 ``datetime.date()``。 - """ - if self.is_us and self.hour < _US_DAY_SPLIT_HOUR: - return (date(self.year, self.month, self.day) - timedelta(days=1)).isoformat() - return f"{self.year:04d}-{self.month:02d}-{self.day:02d}" - @dataclass(slots=True) class IndexBar(SecurityBar): diff --git a/tests/test_protocol.py b/tests/test_protocol.py index 47c8986..8cd60e4 100644 --- a/tests/test_protocol.py +++ b/tests/test_protocol.py @@ -2,20 +2,17 @@ from __future__ import annotations import struct -from collections import Counter -from datetime import date, datetime import pytest -from pytdxdata.models import Adjust, KlinePeriod, SecurityBar +from pytdxdata.protocol.frame import FrameHeader, decompress_body, parse_header +from pytdxdata.protocol.price import get_price, put_price, decode_ohlc_diffs +from pytdxdata.protocol.volume import decode_volume from pytdxdata.protocol.commands.ex_proto import GetExInstrumentBarsCmd from pytdxdata.protocol.commands.kline import GetSecurityBarsCmd -from pytdxdata.protocol.commands.mac import MacKlineCmd from pytdxdata.protocol.commands.minute import GetHistoryMinuteTimeDataCmd from pytdxdata.protocol.commands.transaction import MacTransactionCmd -from pytdxdata.protocol.frame import FrameHeader, decompress_body, parse_header -from pytdxdata.protocol.price import decode_ohlc_diffs, get_price, put_price -from pytdxdata.protocol.volume import decode_volume + # ---------- 变长有符号整数 ---------- @@ -179,110 +176,3 @@ def test_mac_transaction_parse(): assert recs[0].trade_count == 3 assert recs[0].bs_flag == 1 assert recs[1].trade_count == 1 - - -# ---------- 跨时区时间戳归一化(美股 EX 通道) ---------- -# -# 通达信 EX 通道对美股返回的时间戳把两个时区拼在一起:日期字段是**美东交易日**、 -# 时分字段是**北京时间**。直拼出的 datetime 会把同一交易日的下午半场(北京 -# 00:00~04:00)排到上午半场(北京 21:30~23:59)之前,单日 390 根全部错位。 - -def _bar(market: int, y: int, mo: int, d: int, h: int, mi: int) -> SecurityBar: - return SecurityBar(market=market, code="X", open=1.0, high=1.0, low=1.0, - close=1.0, vol=1.0, amount=1.0, - year=y, month=mo, day=d, hour=h, minute=mi) - - -def test_us_evening_segment_keeps_date(): - # 北京 21:31 ~ 23:59 与美东交易日属同一自然日,日期不动 - b = _bar(74, 2026, 10, 12, 21, 31) - assert b.datetime == datetime(2026, 10, 12, 21, 31) - assert b.trading_date == "2026-10-12" - - -def test_us_midnight_segment_rolls_to_next_day(): - # 北京次日 00:00 ~ 04:00 实际是美东 12:00~16:00,日期要 +1 天 - b = _bar(74, 2026, 10, 12, 4, 0) - assert b.datetime == datetime(2026, 10, 13, 4, 0) - assert (b.hour, b.minute) == (4, 0) # 时分不参与归一化 - assert b.trading_date == "2026-10-12" # 仍归属美东 10-12 交易日 - - -def test_us_split_hour_boundary(): - assert _bar(74, 2026, 10, 12, 11, 59).day == 13 - assert _bar(74, 2026, 10, 12, 12, 0).day == 12 - - -def test_us_month_and_year_rollover(): - assert _bar(74, 2026, 10, 31, 4, 0).datetime == datetime(2026, 11, 1, 4, 0) - assert _bar(74, 2026, 12, 31, 4, 0).datetime == datetime(2027, 1, 1, 4, 0) - - -def test_cn_and_hk_bars_untouched(): - cn = _bar(1, 2026, 10, 12, 9, 31) # A股/标准通道 - assert (cn.year, cn.month, cn.day) == (2026, 10, 12) - assert cn.trading_date == "2026-10-12" - hk = _bar(31, 2026, 10, 12, 4, 0) # 港股同为 UTC+8,凌晨段不应 +1 - assert (hk.year, hk.month, hk.day) == (2026, 10, 12) - assert hk.trading_date == "2026-10-12" - - -def test_us_full_session_is_monotonic_and_single_trading_day(): - # 实测口径:北京 21:31~23:59(149 根)+ 次日 00:00~04:00(241 根)= 390 根 - mins = list(range(21 * 60 + 31, 24 * 60)) + list(range(4 * 60 + 1)) - assert len(mins) == 390 - bars = [_bar(74, 2026, 10, 12, m // 60, m % 60) for m in mins] - bars.sort(key=lambda b: b.datetime) - dts = [b.datetime for b in bars] - assert dts == sorted(dts) # 归一化后严格单调 - assert dts[0] == datetime(2026, 10, 12, 21, 31) - assert dts[-1] == datetime(2026, 10, 13, 4, 0) - # 全部归属于同一个美东交易日 - assert {b.trading_date for b in bars} == {"2026-10-12"} - # 但横跨两个北京自然日(这正是不能用 datetime.date() 聚合的原因) - by_day = Counter(b.datetime.date() for b in bars) - assert by_day[date(2026, 10, 12)] == 149 - assert by_day[date(2026, 10, 13)] == 241 - - -# ---------- MAC 通道 K线(0x122E)同样归一化 ---------- - -def _mac_bars_body(records: list[tuple[int, int]]) -> bytes: - """构造 0x122E 响应体:33B头(count@24) + 每条36B(4B ymd + 4B time秒 + 7float)。""" - body = bytearray(33 + len(records) * 36) - struct.pack_into("