PyQt 多线程编程教学项目

这是一个完整的 PyQt 多线程编程教学项目，通过对比示例展示如何解决 GUI 冻结问题。项目包含从基础到高级的 PyQt 多线程编程示例，适合初学者学习和掌握多线程技术。

🎯 项目特色

• 对比教学法: 通过问题示例 vs 解决方案示例，直观理解多线程的必要性
• 渐进式学习: 从简单的GUI冻结问题到完整的企业级应用架构
• 实际应用: 包含 YOLO 目标检测等真实场景的多线程应用
• 现代并发: 展示传统 threading 与现代 concurrent.futures 的对比
• 企业级框架: 提供 UHDMSYS 多线程框架设计和实现

📁 项目结构

核心示例文件 (推荐学习路径)

python-pyqt-qthread/          # 主要教学项目
├── 1.py                     # GUI冻结问题演示
├── 2_movetothread.py        # 标准解决方案 (重点学习)
├── 3.py                     # 线程池技术
├── 4.py                     # 线程同步(QMutex)
├── 6.py                     # 完整应用示例
├── 7.py                     # UHDMSYS企业级框架
├── yolo_single_file.py      # YOLO目标检测(高级应用)
└── threading_*.py           # 现代并发编程示例

子项目

pyqt/                        # MVP架构演示项目
pyqt_math/                   # MVVM数学计算器
thread/                      # 线程编程学习项目
process/                     # 多进程编程学习项目

🚀 快速开始

环境要求

• Python 3.7+ (推荐 3.10+)
• PyQt5 或 PyQt6
• 依赖管理：uv (推荐) 或 pip

安装依赖

# 使用 uv (推荐)
uv pip install PyQt5

# 或使用传统方式
pip install PyQt5

运行示例

# 进入主项目目录
cd python-pyqt-qthread

# 1. 体验GUI冻结问题
python 1.py

# 2. 学习标准解决方案
python 2_movetothread.py

# 3. 运行完整应用
python 6.py

# 4. 体验YOLO目标检测
python yolo_single_file.py

📚 学习路径

完全初学者 (2-3小时)

1. 基础准备: 运行 1_simple.py 理解PyQt基础
2. 问题体验: 运行 1.py 体验GUI冻结
3. 核心解决方案: 详细学习 2_movetothread.py
4. 理论巩固: 阅读 pyqt_qthread_guide.md

进阶开发者 (4-6小时)

1. 高级技术: 学习 3.py 线程池, 4.py 线程同步
2. 完整应用: 分析 6.py 完整应用架构
3. 实战项目: 研究 yolo_single_file.py
4. 企业级框架: 学习 7.py UHDMSYS框架

快速参考 (有经验开发者)

1. 问题诊断: 运行 1.py 了解问题
2. 标准解决方案: 学习 2_movetothread.py 核心模式
3. 高级模式: 浏览 3.py, 4.py, 6.py
4. 实战参考: 研究 yolo_single_file.py 架构

🏗️ 技术架构

Worker-Thread 标准模式

# 标准6步法
1. 创建 QThread 对象
2. 创建 Worker 对象
3. 将 Worker 移动到线程 (moveToThread)
4. 连接信号槽（通信桥梁）
5. 启动线程
6. 资源清理（deleteLater）

UHDMSYS企业级框架

• BaseWorker基类: 标准化的Worker生命周期管理
• 4个专用Worker: HardwareWorker、VideoStreamWorker、NeuralWorker、IOWorker
• 信号槽网络: 复杂的线程间通信机制
• 资源管理: 完善的线程创建、启动、停止、清理流程

📖 详细文档

• 完整QThread教程
• 小白友好指南
• UHDMSYS框架文档
• 信号槽专题指南

🔧 核心技术要点

线程安全原则

1. UI操作限制: 工作线程绝对不能直接操作UI组件
2. 通信机制: 必须通过信号槽进行跨线程通信
3. 资源管理: 正确的线程生命周期管理

信号槽使用规范

# 定义信号
class Worker(QObject):
    finished = pyqtSignal()           # 无参数信号
    progress = pyqtSignal(int)        # 单参数信号
    status = pyqtSignal(str, int)     # 多参数信号

# 连接信号槽
self.worker.progress.connect(self.update_progress)

🎮 示例应用场景

GUI冻结问题 (1.py)

• 展示单线程GUI应用程序的局限性
• sleep(1) 阻塞主线程，导致GUI完全无响应

标准解决方案 (2_movetothread.py)

• 使用 QThread + Worker 模式解决GUI冻结
• 详细的中文注释，165行代码展示完整模式

YOLO目标检测 (yolo_single_file.py)

• 真实计算机视觉应用中的多线程技术
• 集成两种QThread模式，便于对比学习
• 实时视频处理和UI更新

🛠️ 开发工具

# 运行测试
python mydocs/test_all_examples.py

# 代码质量检查
flake8 *.py --max-line-length=119 --ignore=E203,W503
mypy *.py --ignore-missing-imports --allow-untyped-defs

📝 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个教学项目！

📞 联系方式

如有问题或建议，请通过 GitHub Issues 联系。

---

⭐ 如果这个项目对您有帮助，请给个 Star 支持一下！