QThreadWithReturn

基于 PySide6 的多线程高度封装库，简化 GUI 应用中的多线程编程。

✨ 特性

🎯 核心优势

• 简单易用：提供类似 concurrent.futures.Future 的 API，无需二次学习
• 渐进式引入：可以在现有项目中逐步引入，无需大规模重构
• 类型安全：完整的类型提示，IDE 友好
• 内存安全：自动管理线程生命周期，防止内存泄漏
• Qt 集成：与 Qt 事件循环无缝集成，支持信号槽机制

🚀 主要功能

QThreadWithReturn

• 支持获取线程执行结果
• 灵活的回调机制（无参数、单参数、多参数）
• 支持超时控制和优雅取消
• 支持强制终止（紧急情况）
• 自动处理 Qt 事件循环
• 线程安全的状态管理

QThreadPoolExecutor

• API 兼容 concurrent.futures.ThreadPoolExecutor
• 自动管理线程池大小
• 支持任务队列和并发控制
• 支持线程初始化器和命名
• 支持池级别完成回调和任务级别失败回调
• 支持 as_completed 方法按完成顺序处理任务

🏃‍♂️ 快速开始

安装

Bash

# 使用 uv
uv add qthreadwithreturn

# 使用 pip  
pip install qthreadwithreturn
pip install PySide6  # 如果还没有安装 PySide6 的话

基础示例

Python

import time
from PySide6.QtWidgets import QApplication, QWidget, QPushButton, QLabel, QVBoxLayout
from qthreadwithreturn import QThreadWithReturn


class MyWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QThreadWithReturn 示例")
        self.setGeometry(100, 100, 300, 200)

        layout = QVBoxLayout()

        self.button = QPushButton("开始任务", self)
        self.button.clicked.connect(self.start_task)
        layout.addWidget(self.button)

        self.label = QLabel("等待任务...", self)
        layout.addWidget(self.label)

        self.setLayout(layout)

    def start_task(self):
        """启动耗时任务"""
        self.button.setEnabled(False)
        self.label.setText("任务执行中...")

        # 定义耗时任务
        def long_running_task():
            time.sleep(2)  # 模拟耗时操作
            return "任务完成！"

        # 创建线程(这里一定要用self._thread来保存线程对象，防止被垃圾回收)
        self._thread = QThreadWithReturn(long_running_task)

        # 添加成功回调
        self._thread.add_done_callback(self.on_success)

        # 添加失败回调
        self._thread.add_failure_callback(self.on_failure)

        # 启动线程
        self._thread.start()

    def on_success(self, result):
        """任务成功完成回调"""
        self.label.setText(result)
        self.button.setEnabled(True)

    def on_failure(self, error):
        """任务失败回调"""
        self.label.setText(f"任务失败: {error}")
        self.button.setEnabled(True)


if __name__ == "__main__":
    app = QApplication([])
    window = MyWindow()
    window.show()
    app.exec()

📚 文档导航

📖 API 参考

• QThreadWithReturn - 带返回值的线程类
• QThreadPoolExecutor - 线程池执行器

📖 使用指南

• 快速开始 - 快速入门指南

💡 完整示例

• QThreadWithReturn 应用示例 - QThreadWithReturn 应用示例
• QThreadPoolExecutor 应用示例 - QThreadPoolExecutor 应用示例

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目使用 MIT 许可证 - 查看 LICENSE 文件了解详情。