 openbotandopenbot-coder
|
04e0c57569
|
feat: DataFrame 直出(df="polars"/"pandas")+ 0.7.0 (#12)
* feat: DataFrame 直出(df="polars"/"pandas")+ 版本 0.7.0
TdxData 新增构造参数 df:
- None(默认)→ 行为与 0.6.x 完全一致,返回 list[dataclass]
- "polars"/"pandas" → 42 个表格型接口直接返回 DataFrame
转换层 src/pytdxdata/frames.py:
- 列计划按模型缓存,列式采集(不做逐行 asdict)
- 时间列替换:year/month/day/hour/minute → datetime + trading_date;Xdxr 给 date
- 嵌套定型:bid/ask 展开 10 列、fields 字典 JSON 化、codes 保持列表
- 容器展开:get_indicators 合并指标、get_index_trade_stats 展开 minutes、
get_kline_batch/get_minute_batch 纵向拼接
- ContextVar 层次标记:批量/别名方法内层不二次转换,并发互不干扰
- 后端惰性加载:缺包抛 FrameBackendError(带安装命令),构造时即失败
依赖:新增 extras pandas/polars/dataframe,核心包仍零依赖;dev 组加 pandas+polars
测试:tests/test_frames.py 40 项(双后端×双格式);全量 401 项通过
文档:新增 docs/dataframe.md,同步 API_REFERENCE/SKILL/llms.txt/README/mkdocs
* perf(kline): 按日期取K线贴最新时走倒推,1分钟 4.2s → 82ms
问题:start_date/end_date 一律走「探总根数 + 二分定位」。1 分钟 K 线历史
二十万根量级 = 6 次翻倍探测 + 2 次方向探测 + 两次各 ~18 次跳转,共 36+ 次
串行往返。「取今天」这个最常见的调用要 4.2 秒。
改法(_bars_backtrack 快路径):
- 右端离最新不超过 _BACKTRACK_GRACE(10 天) 时,直接 start=0, count=N
拿最新 N 根再裁剪;N 按时间跨度估(_BARS_PER_DAY),一天内一次命中,
不够才翻倍,放大到 _BACKTRACK_MAX_BARS 仍不够则回落二分
- 历史中段仍走二分,结果口径完全一致(已逐条比对基准)
两个关键细节:
- 偏移方向是通道级属性而非标的属性,首次探测后缓存在实例上
(_kline_dir_cache)——全市场 5,225 只批量只付一次探测成本
- K线 hour/minute 是周期**结束**时刻,最新一根可能比 now() 略大(14:29
那根还在走),「右端贴最新」必须留周期容差,否则 end_date=now() 被误判
成历史中段
实测(1 分钟,冷启动):
取今天 4,208ms → 82ms
2天前~now 2,211ms → 75ms
最近3天 2,000ms+ → 239ms
历史中段 1,512ms → 285ms
全市场5225只取今天 32.1s(1,140,699 根,精确当天口径)
注:route_for 让 MIN_1 一律走 MAC(0x122E),所以按通道做方向缓存而不是按
「标准/扩展」写死分支。
测试:新增 tests/test_kline_date.py 6 项(倒推次数上界、结束时刻容差、
中段回落二分、未来区间、反向通道、与 count 路径口径一致);全量 407 项通过
* perf(kline): 全市场1分钟K线改多连接流水线抓取(43.6s → 5~7s,盘中 2s)
瓶颈其实是**往返次数**不是带宽:单只K线一请求一标的,串行 33ms/只 ≈ 1 个 RTT。
同一台服务器 16 连接 × 深度 8 实测能跑 5.2 MB/s(此前「单 IP 限流 1.5MB/s」
是浅流水下的假象)。
- get_bars 新增 pipeline 参数(None=按单请求字节自适应 8~32,1=关闭走逐只)
- 多标的(≥16 只)走 _bulk_bars:多连接 work-stealing + 单连接 execute_pipeline
- 只用实测最快的 12 台:池里 24 台全用反而被慢节点拖长尾
- 盘中按交易时段只拉已走过的根数(10:00 → 35 根,数据量差 7 倍)
- 标准通道(日线不复权)同样走批量:全市场 49~72s → 13s
- 修 pipeline 失败时队列剩余标的静默丢失(实测 20 只只回 16 只)
- 修 test_future_range_returns_empty_quickly 时间炸弹(固定日期会漂进 _BACKTRACK_GRACE)
- conftest 关闭后台测速 task,避免污染「往返次数」类断言
实测(5,225 只):count=2 → 2.7s;count=35 → 2.2s;count=240 → 6.9s。
逐根一致性 30/30 相同。新增 tests/test_bulk_kline.py 12 项,合计 419 项全绿。
* test: 批量K线测试的时间锚点改用真实 now(CI 是 UTC,固定日期会漂到别的时段分支)
* fix(ex): EX 通道 K 线回填成交额与结算价(0x23FF 槽位按市场分两类)
报告:EX 通道 get_bars 返回的 SecurityBar.amount 恒为 0.0。
定位属实,但实际情况比报告更细 —— 32B 记录里那 28B 行情只有**一个** 4B 槽位
可复用,语义按市场分两类(全市场实测,用 成交额/(close×vol) 逐条校验):
| 市场 | 槽位5 | 槽位6 | 槽位7 |
|---|---|---|---|
| 港股主板31/港股基金49 | 成交额(f) | 量(手=100股) | 未知 |
| 港股创业板48/新三板44/美股74 | 成交额(f) | 量(股) | 0 |
| 期货/期权 7/8/9/47… | 持仓量(I) | 量 | 结算价(f) |
改前 amount 硬编码 0.0、第 7 个 float 用 `_` 丢弃 —— 于是港股/美股/新三板
明明帧内有成交额却全为 0,期货期权的结算价也拿不到。
- 新增 SecurityBar.settle(结算价,float|None):仅 EX 期货/期权日线有值,
分钟线该槽位恒 0 已归一化为 None,其它通道恒 None。
- 权益类市场回填真实 amount;港股主板/基金的 vol 单位是手(=100股),
amount/vol 是均价的 100 倍,已写进模型注释与量纲表。
- 期货/期权的 amount 仍是 0.0(帧内确实没有成交额,协议限制),
已在 SecurityBar / API_REFERENCE / llms.txt / SKILL.md 写清,
避免使用者再按旧文档判断成调用方 bug。
- 港股指数27/中证指数62 该槽位量级对不上(既非额也非结算价),保守保持 0.0。
- SecurityBar.__setstate__ 兜底旧磁盘缓存:缓存键无 schema 版本,升级后读旧
pickle 缺 settle 槽位,默认反序列化不补默认值 → AttributeError,已容错;
EX K 线缓存键额外加 @v2,让 amount 恒 0 的旧缓存自然失效。
- K 线 DataFrame 因此多一列 settle(0.7.0 未发布,列清单同步更新)。
测试:tests/test_ex_bars_fields.py 16 项(解析层双布局、日内 settle 归零、
API 透传、旧 pickle 兼容);全套 435 项通过。
* docs: 0.7.0 全站口径同步(DataFrame 出口 + EX 成交额限制 + 构造参数表)
- 首页:特性表补「DataFrame 直出」与 K 线批量性能,导航新增 DataFrame 卡片,
统一方法数按实测修正为 35(+33 别名 = 68 个公开方法)
- 安装页:补 extras(polars/pandas/dataframe)与 df 用法;构造参数表补
df / std_pool_cap / ex_pool_cap,并把 pool_max 默认值从 12 修正为 24(实际值)
- 场景示例:`转成 pandas` 一节改为先推 df= 开关,手动转换降级为局部场景
- 数据模型页:不再说「刻意不提供 DataFrame」,改为 dataclass 与 DataFrame
是同一份数据、两种容器
- AI 接入页:返回值约定补 `df=` 开关的说法
- README:K 线列注释补 settle;已知限制补 EX 通道成交额/结算价的协议口径
- CHANGELOG:新增「升级」小节(升级命令、旧缓存无需清理)
---------
Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
|
2026-10-28 18:22:13 +08:00 |
|
 openbotandopenbot-coder
|
b2f899df49
|
fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间 (#2)
通达信 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 无日期分量可承载跨日信息。
Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
|
2026-10-13 16:47:57 +08:00 |
|
openbot-coder
|
8193d560da
|
Revert "fix(models): 修复美股分钟K线 datetime 时区拼接错位,还原为北京时间"
This reverts commit 5408903a4c.
|
2026-10-13 16:42:41 +08:00 |
|
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 |
|
openbot-coder
|
8951ec2678
|
fix(api,codec): 修复 BUG-1 分时采样走错命令 + BUG-2 财务文件名纠正
BUG-1: A股 get_minutes(sampling=True) 原走 MacChartSamplingCmd(0x254D)
这是 EX 协议命令,7709 主机无响应(3×8s 超时≈24s)。
修复:A股采样由 MacTickChartCmd(0x122D) 分时数据派生,
EX 市场(hk)仍走 0x254D。4 个 A股 场景均<0.1s 返回 240 点。
BUG-2: tdxfin/gpcw.txt 索引声明 gpcwYYYYMMDD.zip,
但服务器实际只有 tdxfin/gpcwYYYYMMDD.dat(未压缩,~13MB),
.zip 请求返回 0-1 字节空壳。
修复:_fetch_financial_dat() 自动候选回退
tdxfin/*.zip → tdxfin/*.dat → 原始文件名,加 looks_like_gpcw_dat 校验。
实测 gpcw20260630.zip→5568 条,gpcw20260331.zip→5547 条。
新增 codec/financial.py: looks_like_gpcw_dat, extract_gpcw_dat(含 zip/未压缩双通道)。
同步更新 README/API_REFERENCE/docs/cli/cookbook/CHANGELOG 共 6 处文档。
tests: +18(总 182),ruff 无新增 findings,MkDocs strict 通过。
|
2026-09-21 20:47:48 +08:00 |
|
openbot-coder
|
b78d0fabf5
|
docs: 修正 servers.json 清理后遗留的过时描述(含一处事实反转)
servers.json 复测后三池台数已变(standard 9 / mac 22 / ex 4),但 README 与部分文档
仍停留在旧口径,且有一处因果结论被实测推翻:
- README.md
- 测试用例数 127 → 164(并补「当日测速缓存」到用例分组说明)
- 「已知限制」补测速缓存详情的文档站链接
- docs/internals/routing.md
- 三池台数:标准池「数十台」→ 9 台、MAC 池「数台」→ 22 台(EX 池 4 台不变),
并标注为 2026-09-21 离线探针实测可达数、实际以当日测速缓存为准
- **事实反转修正**:原文「MAC 池远小于标准池,这解释了逐笔/分时并发弱于日线」
与实测不符(mac 22 > standard 9)→ 已改为陈述实测台数,
并指出两通道单台连接上限默认相同(均 4)
- docs/internals/cache-pool.md
- 「为什么 MAC 池更小」小节前提已不成立 → 改为「MAC 通道的单台连接上限」,
保留 mac_pool_cap=4 的可用信息,删除错误因果
- docs/refactor-audit.md
- 历史快照的 127 passed 标注「审查当时」,避免误读为当前基线
验证:scripts/check_docs.py exit 0;mkdocs build --strict exit 0(无告警)
|
2026-09-21 19:42:06 +08:00 |
|
openbot-coder
|
7e830c7579
|
docs: 补齐测速缓存相关文档,并修掉 0.6.0 遗留的过时描述
上一提交只补了 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 跑测前后逐字节不变。
|
2026-09-21 18:26:37 +08:00 |
|
openbot-coder
|
3e0beb27a6
|
release: v0.6.0(统一对外接口重构)
按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。
- 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/
get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等),
标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0);
同名旧方法不再兼容 (market, code) 元组。
- 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除),
18 个同名升级为统一接口。公开方法共 63 个。
- 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。
- 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。
- 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。
- 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
|
2026-09-17 11:34:52 +08:00 |
|
openbot-coder
|
1bee6b0fc7
|
release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增
- 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages
- SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱)
- docs/ai.md:文档站的「AI 助手接入」页
- tests/test_check_docs.py(10 项):漂移检查器自身的自测
变更
- README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 /
扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md
- README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404)
- check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用),
并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数
- 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站
- uv.lock 同步
修复
- ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正
- docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败)
- README 标注的测试数量 85 → 109(pytest 实际收集用例数)
|
2026-09-15 14:55:07 +08:00 |
|
openbot-coder
|
02ec5b6e33
|
docs: README 顶部增加 CI 状态徽章
指向 .github/workflows/ci.yml(main 分支),展示 3.11/3.13 测试矩阵与构建校验结果。
|
2026-09-15 12:11:55 +08:00 |
|
openbot-coder
|
9183c3294f
|
v0.4.0: 初始开源发布
通达信(TDX)行情数据客户端 —— 动态连接池 + 双层TTL缓存 + 3连接并发分页,
纯 asyncio、零运行时依赖。一套接口覆盖 A股(沪/深/北) / 港股 / 美股 / 期货 / 期权。
主要能力:
- 四层架构:api → pool(标准/MAC/EX 三池) → protocol(16 命令模块) → cache(内存+SQLite)
- TdxData 提供 51 个公开异步方法;CLI(tdx) 提供 19 个子命令
- 服务器文件下载 + 解析:板块 block_*.dat / 行业 tdxhy.cfg / 历史财报 gpcw*.zip
- 85 个离线测试(协议 / 连接池 / 缓存 / 分页 / API / 文件解析 / CLI)
协议层参照 easy-tdx 的字节级格式独立实现,不依赖 easy-tdx 包。
|
2026-09-15 11:38:44 +08:00 |
|