fry-qt6-progress-widget 0.1.0

A reusable PyQt6 QWidget for displaying task progress, messages, pause state, and time estimates.

fry-qt6-progress-widget

fry-qt6-progress-widget 是一个可复用的 PyQt6 任务进度组件。核心类是 GeneralTaskProgressWidget，它继承自 QWidget，适合直接放进任意布局；如果你的程序需要 dock，可以使用附带的 GeneralTaskProgressDock 薄包装器，或者自己把 widget 放进 QDockWidget。

安装

发布到 PyPI 后：

pip install fry-qt6-progress-widget

本地开发安装：

pip install -e ".[dev]"

最小用法

import sys

from PyQt6.QtWidgets import QApplication
from fry_qt6_progress_widget import GeneralTaskProgressWidget

app = QApplication(sys.argv)

widget = GeneralTaskProgressWidget()
widget.begin_task(project_id="demo", task_name="导入数据", total=100)
widget.update_progress(current=30, total=100, detail_info="已完成 30 条")
widget.show()

sys.exit(app.exec())

字典信号兼容用法

如果你已有任务系统会发出字典，可以直接调用 handle_task_progress：

widget.handle_task_progress(
    {
        "project_id_str": "demo",
        "task_name_str": "导入数据",
        "now_progress_num": 30,
        "total_num": 100,
        "info_type": "信息",
        "detail_info": "已完成 30 条",
    }
)

Dock 用法

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import QMainWindow
from fry_qt6_progress_widget import GeneralTaskProgressDock

window = QMainWindow()
dock = GeneralTaskProgressDock(window)
window.addDockWidget(Qt.DockWidgetArea.RightDockWidgetArea, dock)
dock.begin_task(project_id="demo", task_name="后台任务", total=10)

常用 API

• begin_task(project_id="", task_name="任务", total=None): 开始任务并重置显示。
• update_progress(current=None, total=None, task_name=None, project_id=None, info_type="信息", detail_info=""): 更新进度和详情消息。
• finish_task(project_id=None, message="任务已完成", hide=False): 标记任务完成。
• set_paused_state(is_paused): 切换暂停/恢复状态。
• append_message(info_type, message): 追加详情日志。
• set_project_filter(project_id): 只接收指定项目 ID 的进度更新。
• get_params_dict() / load_params_dict(snapshot): 保存和恢复组件状态。

示例和文档

• examples/widget_demo.py: 直接使用 QWidget。
• examples/dock_demo.py: 放进 QDockWidget。
• docs/core-concepts.md: 组件核心关键点。

开发与验证

pytest
python -m build

构建后会生成 dist/，发布前建议检查：

twine check dist/*

真正发布到 PyPI 需要维护者账号和 token：

twine upload dist/*