Skip to content

图形化导入工具

Jump to bottom Edit New page
fasiondog edited this page Nov 22, 2025 · 1 revision

图形化导入工具

**本文引用的文件列表** - [importdata.py](file://hikyuu/gui/importdata.py) - [HikyuuTDX.py](file://hikyuu/gui/HikyuuTDX.py) - [MainWindow.py](file://hikyuu/gui/data/MainWindow.py) - [UseTdxImportToH5Thread.py](file://hikyuu/gui/data/UseTdxImportToH5Thread.py) - [UsePytdxImportToH5Thread.py](file://hikyuu/gui/data/UsePytdxImportToH5Thread.py) - [ImportTdxToH5Task.py](file://hikyuu/gui/data/ImportTdxToH5Task.py) - [ImportPytdxToH5Task.py](file://hikyuu/gui/data/ImportPytdxToH5Task.py) - [SchedImportThread.py](file://hikyuu/gui/data/SchedImportThread.py) - [EscapetimeThread.py](file://hikyuu/gui/data/EscapetimeThread.py) - [hku_config_template.py](file://hikyuu/data/hku_config_template.py)

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言

本文件面向使用者与开发者，系统化梳理 Hikyuu 图形化数据导入工具的 GUI 界面与后台任务调度机制。内容覆盖：

  • 如何通过可视化界面配置数据源、选择导入范围（全量/增量）、设置调度计划并监控导入进度
  • ImportPytdxToH5Task、ImportTdxToH5Task 等后台任务类的多线程执行模型（进程池、队列、异常捕获与日志）
  • SchedImportThread 如何实现定时自动导入（按日/周/月等周期）
  • 常见问题与解决方案（任务卡死、数据库连接超时等）
  • GUI 与命令行导入的适用场景对比与选型建议

项目结构

图形化导入工具主要由以下模块构成：

  • GUI 主窗口与界面布局：MainWindow.py（UI生成）、HikyuuTDX.py（业务逻辑与事件绑定）
  • 导入任务线程：UseTdxImportToH5Thread.py、UsePytdxImportToH5Thread.py
  • 具体导入任务：ImportTdxToH5Task.py、ImportPytdxToH5Task.py
  • 定时调度线程：SchedImportThread.py
  • 运行时计时线程：EscapetimeThread.py
  • 默认配置模板：hku_config_template.py
  • 命令行导入入口：importdata.py
graph TB
subgraph "GUI层"
MW["MyMainWindow<br/>界面与事件"]
UI["Ui_MainWindow<br/>界面布局"]
end
subgraph "导入线程"
UTDX["UseTdxImportToH5Thread"]
UPY["UsePytdxImportToH5Thread"]
end
subgraph "具体任务"
ITDX["ImportTdxToH5Task"]
IPY["ImportPytdxToH5Task"]
end
subgraph "调度与辅助"
SCHED["SchedImportThread"]
ESC["EscapetimeThread"]
end
subgraph "配置与模板"
CFG["hku_config_template"]
CLI["importdata.py"]
end
MW --> UI
MW --> UTDX
MW --> UPY
MW --> SCHED
MW --> ESC
UTDX --> ITDX
UPY --> IPY
MW --> CFG
CLI --> UTDX
CLI --> UPY
Loading

图表来源

  • HikyuuTDX.py
  • MainWindow.py
  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py
  • SchedImportThread.py
  • EscapetimeThread.py
  • hku_config_template.py
  • importdata.py

章节来源

  • HikyuuTDX.py
  • MainWindow.py

核心组件

  • GUI 主窗口 MyMainWindow：负责界面初始化、配置读写、导入线程生命周期管理、进度与日志展示、定时导入开关与调度线程交互
  • UseTdxImportToH5Thread / UsePytdxImportToH5Thread：导入线程，负责任务编排、进程池创建、消息汇总与进度聚合、异常捕获与日志转发
  • ImportTdxToH5Task / ImportPytdxToH5Task：具体导入任务，封装单个市场/周期的数据导入逻辑，支持进度回调与结果统计
  • SchedImportThread：定时调度线程，基于 QThread 与 QWaitCondition 实现“按日/周/月”周期的定时触发
  • EscapetimeThread：运行时计时线程，持续向 GUI 发送耗时信息，便于用户感知导入耗时
  • importdata.py：命令行入口，复用导入线程与消息处理逻辑，支持忽略K线数据的模式

章节来源

  • HikyuuTDX.py
  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py
  • SchedImportThread.py
  • EscapetimeThread.py
  • importdata.py

架构总览

GUI 通过 MyMainWindow 统一管理导入线程与调度线程；导入线程内部以进程池方式并发执行多个任务，每个任务通过队列向主线程回传进度与结果；定时线程在到达设定时刻时触发导入流程；运行时计时线程持续更新耗时信息。

sequenceDiagram
participant User as "用户"
participant MW as "MyMainWindow"
participant SCHED as "SchedImportThread"
participant UTDX as "UseTdxImportToH5Thread"
participant UPY as "UsePytdxImportToH5Thread"
participant ITDX as "ImportTdxToH5Task"
participant IPY as "ImportPytdxToH5Task"
participant ESC as "EscapetimeThread"
User->>MW : 点击“启动定时导入”
MW->>SCHED : 创建并启动
SCHED->>SCHED : 计算下次导入时间
SCHED-->>MW : 触发信号
MW->>UTDX : 启动导入线程或UPY
UTDX->>ITDX : 启动进程池
UPY->>IPY : 启动进程池
loop 进度轮询
ITDX-->>UTDX : 队列进度消息
IPY-->>UPY : 队列进度消息
UTDX-->>MW : 汇总进度与结果
UPY-->>MW : 汇总进度与结果
ESC-->>MW : 耗时更新
end
UTDX-->>MW : 导入完成
UPY-->>MW : 导入完成
SCHED-->>MW : 下次导入时间
Loading

图表来源

  • HikyuuTDX.py
  • SchedImportThread.py
  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py
  • EscapetimeThread.py

详细组件分析

GUI 界面与配置

  • 界面布局由 MainWindow.py 生成，包含“数据源与导入范围”、“目标存储”、“定时导入”、“进度与日志”等 Tab
  • MyMainWindow 负责：
    • 初始化 UI、读取/保存配置（importdata-gui.ini）
    • 控制导入线程启停、进度条与详情文本框更新
    • 定时导入按钮与 SchedImportThread 的交互
    • 日志输出重定向与多进程日志监听
  • 配置项包括：数据源（pytdx/tdx/qmt）、目标存储（hdf5/mysql/clickhouse）、导入范围（日线/分钟线/分笔/分时/权息/财务/板块）、预加载参数、定时导入时间等

章节来源

  • MainWindow.py
  • HikyuuTDX.py
  • HikyuuTDX.py
  • hku_config_template.py

导入线程与任务模型

  • UseTdxImportToH5Thread / UsePytdxImportToH5Thread：
    • 任务编排：根据配置生成任务列表（日线/分钟线/分笔/分时/权息/财务/板块等），按市场与周期拆分
    • 进程池：为每个任务创建独立进程，提高吞吐与隔离性
    • 队列通信：子进程通过队列向主线程回传进度与结果，主线程进行聚合与 UI 更新
    • 异常处理：统一捕获异常并通过消息通道通知 GUI
  • ImportTdxToH5Task / ImportPytdxToH5Task：
    • 支持进度回调，将进度写入队列
    • 根据配置选择目标存储（hdf5/mysql/clickhouse），建立连接并调用对应导入函数
    • 记录导入条数，最终通过队列发送“完成”消息
classDiagram
class UseTdxImportToH5Thread {
+message : Signal
-process_list : List[Process]
-hosts : List
-tasks : List
+init_task()
+run()
-_run()
}
class UsePytdxImportToH5Thread {
+message : Signal
-process_list : List[Process]
-hosts : List
-tasks : List
+init_task()
+run()
-_run()
}
class ImportTdxToH5Task {
+__call__()
-ProgressBar
}
class ImportPytdxToH5Task {
+__call__()
-ProgressBar
}
UseTdxImportToH5Thread --> ImportTdxToH5Task : "创建并启动进程"
UsePytdxImportToH5Thread --> ImportPytdxToH5Task : "创建并启动进程"
Loading

图表来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py

章节来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py

进度聚合与 UI 更新

  • 导入线程维护各市场的进度字典，按周期（日线/分钟线/5分钟线/分笔/分时）分别统计
  • 将子任务的进度消息汇总为平均值，再通过信号发送给 GUI
  • GUI 接收消息后更新进度条与详情文本框，并在完成后显示耗时与统计信息
flowchart TD
Start(["接收子任务进度"]) --> Update["更新各市场进度字典"]
Update --> Aggregate["按周期聚合平均进度"]
Aggregate --> Emit["发送进度信号到GUI"]
Emit --> GUIUpdate["更新进度条与详情"]
GUIUpdate --> Next["等待下一个进度消息"]
Next --> |完成| Finish["发送完成信号"]
Loading

图表来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • HikyuuTDX.py

章节来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • HikyuuTDX.py

定时导入机制（SchedImportThread）

  • 基于 QThread 与 QWaitCondition 实现阻塞等待，到达设定时间点后发出信号
  • 自动计算“下次导入时间”，考虑周末跳过（周五则加三天）
  • GUI 侧通过按钮切换启动/停止，线程停止时唤醒等待并回收资源
sequenceDiagram
participant MW as "MyMainWindow"
participant SCHED as "SchedImportThread"
MW->>SCHED : 创建并启动
SCHED->>SCHED : 计算下次导入时间
SCHED->>SCHED : 等待QWaitCondition
SCHED-->>MW : 触发信号
MW->>MW : 启动导入线程
SCHED->>SCHED : 计算下一次导入时间
SCHED->>SCHED : 等待
Loading

图表来源

  • SchedImportThread.py
  • HikyuuTDX.py

章节来源

  • SchedImportThread.py
  • HikyuuTDX.py

运行时计时（EscapetimeThread）

  • 持续每秒向 GUI 发送耗时信息，GUI 在状态栏实时显示
  • 与导入线程并行运行，互不影响

章节来源

  • EscapetimeThread.py
  • HikyuuTDX.py

命令行导入（importdata.py）

  • 提供命令行入口，复用导入线程的消息处理逻辑
  • 支持忽略 K 线数据的模式，便于快速验证其他数据导入链路

章节来源

  • importdata.py
  • importdata.py

依赖关系分析

  • GUI 与导入线程通过信号/槽解耦，导入线程内部通过队列与子进程通信
  • 任务类依赖外部数据源（pytdx/tdx）与目标存储（hdf5/mysql/clickhouse）
  • 定时线程与导入线程相互独立，通过 GUI 串联
graph TB
MW["MyMainWindow"] --> UTDX["UseTdxImportToH5Thread"]
MW --> UPY["UsePytdxImportToH5Thread"]
MW --> SCHED["SchedImportThread"]
MW --> ESC["EscapetimeThread"]
UTDX --> ITDX["ImportTdxToH5Task"]
UPY --> IPY["ImportPytdxToH5Task"]
ITDX --> PYTDX["pytdx.hq"]
IPY --> PYTDX
ITDX --> STORE["hdf5/mysql/clickhouse"]
IPY --> STORE
Loading

图表来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py

章节来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • ImportTdxToH5Task.py
  • ImportPytdxToH5Task.py

性能考量

  • 并发策略：导入线程以进程池并发执行任务，充分利用 CPU 与网络带宽
  • 进度聚合：按周期聚合平均进度，减少 UI 更新频率，降低主线程压力
  • 存储选择：hdf5 适合本地快速访问，mysql/clickhouse 适合大规模数据与查询
  • 超时与重试：导入任务对数据库连接设置了超时，网络异常时应检查服务器连通性与防火墙策略

[本节为通用指导，无需列出具体文件来源]

故障排查指南

  • 任务卡死
    • 现象：进度不再更新，但进程仍在运行
    • 排查要点：查看导入线程日志与子进程退出码；确认队列是否被阻塞；检查网络与目标存储可用性
    • 参考路径
      • UseTdxImportToH5Thread.py
      • UsePytdxImportToH5Thread.py
  • 数据库连接超时
    • 现象：导入过程中出现连接失败或超时
    • 排查要点：检查 mysql/clickhouse 地址、端口、账号密码；确认服务器可达；适当增大超时参数
    • 参考路径
      • ImportPytdxToH5Task.py
      • ImportTdxToH5Task.py
  • 定时导入未触发
    • 现象：到达设定时间未执行
    • 排查要点：确认定时导入按钮状态、SchedImportThread 是否在运行、下次导入时间计算是否正确（考虑周末跳过）
    • 参考路径
      • SchedImportThread.py
      • HikyuuTDX.py
  • 权息/财务导入异常
    • 现象：权息或财务数据导入失败或无变化
    • 排查要点：检查网络与服务器可用性；查看导入线程消息通道中的 INFO/完成信息
    • 参考路径
      • UseTdxImportToH5Thread.py
      • UsePytdxImportToH5Thread.py

章节来源

  • UseTdxImportToH5Thread.py
  • UsePytdxImportToH5Thread.py
  • SchedImportThread.py
  • HikyuuTDX.py
  • ImportPytdxToH5Task.py
  • ImportTdxToH5Task.py

结论

图形化导入工具通过清晰的分层设计实现了“可视化配置 + 多进程并发导入 + 定时调度”的完整闭环。GUI 提供直观的操作体验，导入线程保证高吞吐与稳定性，定时线程满足周期性数据更新需求。对于复杂场景，推荐使用 GUI；对于自动化脚本或批量处理，可结合命令行入口与配置模板进行部署。

[本节为总结性内容，无需列出具体文件来源]

附录

使用步骤与界面要点

  • 配置数据源与导入范围：在“数据源与导入范围”页勾选需要的行情类型与周期
  • 配置目标存储：选择 hdf5/mysql/clickhouse，并填写相应参数
  • 设置定时导入：在“定时导入”页设置时间，点击“启动定时导入”
  • 监控进度：在“导入”页查看各周期进度条与详情文本框
  • 保存配置：点击“保存配置”按钮，配置将写入 importdata-gui.ini

章节来源

  • HikyuuTDX.py
  • HikyuuTDX.py
  • HikyuuTDX.py
  • MainWindow.py

GUI 与命令行导入对比

  • GUI 优势：可视化配置、进度实时反馈、定时导入一键开启、日志集中展示
  • 命令行优势：轻量、可嵌入自动化脚本、适合批量处理与 CI/CD
  • 选型建议：日常维护与演示使用 GUI；生产环境与自动化任务使用命令行入口

章节来源

  • importdata.py
  • HikyuuTDX.py
Add a custom footer
Add a custom sidebar

Clone this wiki locally