fry-qt6-progress-widget 0.1.0__tar.gz

fry_qt6_progress_widget-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py

fry_qt6_progress_widget-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: fry-qt6-progress-widget
+Version: 0.1.0
+Summary: A reusable PyQt6 QWidget for displaying task progress, messages, pause state, and time estimates.
+Author: fry
+Project-URL: Homepage, https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_qt6_progress_widget
+Project-URL: Source, https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_qt6_progress_widget
+Keywords: pyqt6,qt,progress,widget,task
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyQt6>=6.5
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+
+# fry-qt6-progress-widget
+
+`fry-qt6-progress-widget` 是一个可复用的 PyQt6 任务进度组件。核心类是 `GeneralTaskProgressWidget`，它继承自 `QWidget`，适合直接放进任意布局；如果你的程序需要 dock，可以使用附带的 `GeneralTaskProgressDock` 薄包装器，或者自己把 widget 放进 `QDockWidget`。
+
+## 安装
+
+发布到 PyPI 后：
+
+```bash
+pip install fry-qt6-progress-widget
+```
+
+本地开发安装：
+
+```bash
+pip install -e ".[dev]"
+```
+
+## 最小用法
+
+```python
+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`：
+
+```python
+widget.handle_task_progress(
+    {
+        "project_id_str": "demo",
+        "task_name_str": "导入数据",
+        "now_progress_num": 30,
+        "total_num": 100,
+        "info_type": "信息",
+        "detail_info": "已完成 30 条",
+    }
+)
+```
+
+## Dock 用法
+
+```python
+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](examples/widget_demo.py): 直接使用 QWidget。
+- [examples/dock_demo.py](examples/dock_demo.py): 放进 QDockWidget。
+- [docs/core-concepts.md](docs/core-concepts.md): 组件核心关键点。
+
+## 开发与验证
+
+```bash
+pytest
+python -m build
+```
+
+构建后会生成 `dist/`，发布前建议检查：
+
+```bash
+twine check dist/*
+```
+
+真正发布到 PyPI 需要维护者账号和 token：
+
+```bash
+twine upload dist/*
+```

fry_qt6_progress_widget-0.1.0/README.md

@@ -0,0 +1,100 @@
+# fry-qt6-progress-widget
+
+`fry-qt6-progress-widget` 是一个可复用的 PyQt6 任务进度组件。核心类是 `GeneralTaskProgressWidget`，它继承自 `QWidget`，适合直接放进任意布局；如果你的程序需要 dock，可以使用附带的 `GeneralTaskProgressDock` 薄包装器，或者自己把 widget 放进 `QDockWidget`。
+
+## 安装
+
+发布到 PyPI 后：
+
+```bash
+pip install fry-qt6-progress-widget
+```
+
+本地开发安装：
+
+```bash
+pip install -e ".[dev]"
+```
+
+## 最小用法
+
+```python
+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`：
+
+```python
+widget.handle_task_progress(
+    {
+        "project_id_str": "demo",
+        "task_name_str": "导入数据",
+        "now_progress_num": 30,
+        "total_num": 100,
+        "info_type": "信息",
+        "detail_info": "已完成 30 条",
+    }
+)
+```
+
+## Dock 用法
+
+```python
+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](examples/widget_demo.py): 直接使用 QWidget。
+- [examples/dock_demo.py](examples/dock_demo.py): 放进 QDockWidget。
+- [docs/core-concepts.md](docs/core-concepts.md): 组件核心关键点。
+
+## 开发与验证
+
+```bash
+pytest
+python -m build
+```
+
+构建后会生成 `dist/`，发布前建议检查：
+
+```bash
+twine check dist/*
+```
+
+真正发布到 PyPI 需要维护者账号和 token：
+
+```bash
+twine upload dist/*
+```

fry_qt6_progress_widget-0.1.0/docs/core-concepts.md

@@ -0,0 +1,97 @@
+# fry-qt6-progress-widget 核心关键点
+
+## 1. Widget 是核心，Dock 只是包装
+
+这个包的主类是 `GeneralTaskProgressWidget`，继承自 `QWidget`。它不依赖 `QMainWindow`、全局数据中心或任何业务工程里的基类，所以可以直接放到普通布局、弹窗、侧边栏、Tab 页或自定义容器里。
+
+如果调用方需要 dock，可以使用 `GeneralTaskProgressDock`，也可以自己写：
+
+```python
+dock = QDockWidget("任务进度", main_window)
+dock.setWidget(GeneralTaskProgressWidget())
+```
+
+## 2. 进度数据模型
+
+组件内部维护四类状态：
+
+- `current_project_id`: 当前项目 ID。
+- `current_task_name`: 当前任务名称。
+- `current_progress` / `total_progress`: 当前进度和总量。
+- `is_paused`: 暂停状态。
+
+`total_progress <= 0` 时，进度条会进入 Qt 的 busy/indeterminate 模式，适合总量未知的任务。
+
+## 3. 推荐调用流程
+
+```python
+widget.begin_task(project_id="p1", task_name="导入数据", total=100)
+widget.update_progress(current=20, detail_info="读取文件")
+widget.update_progress(current=80, detail_info="写入数据库")
+widget.finish_task(message="导入完成")
+```
+
+如果任务系统已经按字典广播进度，可以使用兼容入口：
+
+```python
+widget.handle_task_progress(
+    {
+        "project_id_str": "p1",
+        "task_name_str": "导入数据",
+        "now_progress_num": 20,
+        "total_num": 100,
+        "info_type": "信息",
+        "detail_info": "读取文件",
+    }
+)
+```
+
+## 4. 项目过滤
+
+多项目场景下可以设置项目过滤器：
+
+```python
+widget.set_project_filter("p1")
+```
+
+设置后，只有 `project_id == "p1"` 的 begin/update/finish 调用会被处理，其他项目会返回 `ProgressResult(status="info", ...)`，组件 UI 不会被改动。
+
+## 5. 返回对象
+
+公开的变更方法返回 `ProgressResult`：
+
+- `status`: `success`、`info`、`warning`、`failed`。
+- `message`: 便于日志记录的说明。
+- `data`: 通常是 `get_params_dict()` 的快照。
+- `ok`: 只要不是 `failed` 就为 `True`。
+
+这样调用方不需要依赖原工程里的 `FryReturnObj`。
+
+## 6. 信号
+
+组件提供这些 Qt 信号，方便调用方联动其他 UI：
+
+- `taskStarted(project_id, task_name)`
+- `progressChanged(snapshot_dict)`
+- `taskFinished(project_id)`
+- `messageAppended(info_type, message)`
+- `pausedChanged(is_paused)`
+
+## 7. HTML 安全
+
+详情区使用 `QTextEdit.insertHtml()` 展示彩色消息。组件会对 `info_type` 和 `message` 做 `html.escape()`，所以外部传入的 `<script>`、`<b>` 等文本会按普通文本显示，不会当作 HTML 执行或改变排版。
+
+## 8. 时间预估
+
+组件按任务名记录第一次进度和当前进度，通过消耗时间估算：
+
+```text
+平均耗时 = 已用时间 / 已完成单位数
+预计剩余 = 平均耗时 * 剩余单位数
+```
+
+首次进度、进度未增长、总量未知时会显示“正在计算预估时间...”。
+
+## 9. 状态保存与恢复
+
+`get_params_dict()` 会返回可序列化快照；`load_params_dict(snapshot)` 可以恢复主要 UI 状态。这个能力适合应用重载、切换页面、保存窗口状态等场景。

fry_qt6_progress_widget-0.1.0/examples/dock_demo.py

@@ -0,0 +1,42 @@
+import sys
+
+from PyQt6.QtCore import Qt, QTimer
+from PyQt6.QtWidgets import QApplication, QLabel, QMainWindow
+
+from fry_qt6_progress_widget import GeneralTaskProgressDock
+
+
+class MainWindow(QMainWindow):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setWindowTitle("Dock demo")
+        self.resize(720, 480)
+        self.setCentralWidget(QLabel("主窗口内容区域"))
+
+        self.progress_dock = GeneralTaskProgressDock(self)
+        self.addDockWidget(Qt.DockWidgetArea.RightDockWidgetArea, self.progress_dock)
+
+        self.current = 0
+        self.timer = QTimer(self)
+        self.timer.timeout.connect(self._tick)
+
+        self.progress_dock.begin_task(project_id="dock-demo", task_name="后台同步", total=50)
+        self.timer.start(150)
+
+    def _tick(self) -> None:
+        self.current += 1
+        self.progress_dock.update_progress(
+            current=self.current,
+            total=50,
+            detail_info=f"同步第 {self.current} 批数据",
+        )
+        if self.current >= 50:
+            self.timer.stop()
+            self.progress_dock.finish_task(message="后台同步完成")
+
+
+if __name__ == "__main__":
+    app = QApplication(sys.argv)
+    window = MainWindow()
+    window.show()
+    sys.exit(app.exec())

fry_qt6_progress_widget-0.1.0/examples/widget_demo.py

@@ -0,0 +1,59 @@
+import sys
+
+from PyQt6.QtCore import QTimer
+from PyQt6.QtWidgets import QApplication, QPushButton, QVBoxLayout, QWidget
+
+from fry_qt6_progress_widget import GeneralTaskProgressWidget
+
+
+class DemoWindow(QWidget):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setWindowTitle("fry-qt6-progress-widget demo")
+        self.resize(460, 560)
+
+        self.progress = GeneralTaskProgressWidget()
+        self.start_button = QPushButton("开始示例任务")
+        self.pause_button = QPushButton("暂停/恢复")
+
+        layout = QVBoxLayout(self)
+        layout.addWidget(self.progress)
+        layout.addWidget(self.start_button)
+        layout.addWidget(self.pause_button)
+
+        self.timer = QTimer(self)
+        self.timer.timeout.connect(self._tick)
+        self.current = 0
+
+        self.start_button.clicked.connect(self.start_task)
+        self.pause_button.clicked.connect(self.toggle_pause)
+
+    def start_task(self) -> None:
+        self.current = 0
+        self.progress.begin_task(project_id="demo", task_name="生成报表", total=100)
+        self.timer.start(120)
+
+    def toggle_pause(self) -> None:
+        self.progress.set_paused_state(not self.progress.is_paused)
+
+    def _tick(self) -> None:
+        if self.progress.is_paused:
+            return
+
+        self.current += 5
+        self.progress.update_progress(
+            current=self.current,
+            total=100,
+            detail_info=f"已处理 {self.current} / 100",
+        )
+
+        if self.current >= 100:
+            self.timer.stop()
+            self.progress.finish_task(message="示例任务完成")
+
+
+if __name__ == "__main__":
+    app = QApplication(sys.argv)
+    window = DemoWindow()
+    window.show()
+    sys.exit(app.exec())

fry_qt6_progress_widget-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fry-qt6-progress-widget"
+version = "0.1.0"
+description = "A reusable PyQt6 QWidget for displaying task progress, messages, pause state, and time estimates."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "fry" }
+]
+keywords = ["pyqt6", "qt", "progress", "widget", "task"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: User Interfaces",
+]
+dependencies = [
+    "PyQt6>=6.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.0",
+    "pytest>=7.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_qt6_progress_widget"
+Source = "https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_qt6_progress_widget"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fry_qt6_progress_widget = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

fry_qt6_progress_widget-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fry_qt6_progress_widget-0.1.0/src/fry_qt6_progress_widget/__init__.py

@@ -0,0 +1,16 @@
+from .dock import GeneralTaskProgressDock
+from .progress_widget import GeneralTaskProgressWidget, InfoTypeConfig, ProgressResult
+
+__version__ = "0.1.0"
+
+TaskProgressWidget = GeneralTaskProgressWidget
+TaskProgressDock = GeneralTaskProgressDock
+
+__all__ = [
+    "GeneralTaskProgressWidget",
+    "GeneralTaskProgressDock",
+    "TaskProgressWidget",
+    "TaskProgressDock",
+    "InfoTypeConfig",
+    "ProgressResult",
+]

fry_qt6_progress_widget-0.1.0/src/fry_qt6_progress_widget/dock.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from PyQt6.QtCore import Qt, pyqtSlot
+from PyQt6.QtWidgets import QDockWidget, QWidget
+
+from .progress_widget import GeneralTaskProgressWidget, ProgressResult
+
+
+class GeneralTaskProgressDock(QDockWidget):
+    """Thin QDockWidget wrapper around GeneralTaskProgressWidget."""
+
+    def __init__(
+        self,
+        parent: Optional[QWidget] = None,
+        *,
+        title: str = "任务进度",
+        widget: Optional[GeneralTaskProgressWidget] = None,
+        allowed_areas: Optional[Qt.DockWidgetArea] = None,
+        **widget_kwargs: Any,
+    ) -> None:
+        super().__init__(title, parent)
+        self.progress_widget = widget or GeneralTaskProgressWidget(parent=self, title=title, **widget_kwargs)
+        self.setWidget(self.progress_widget)
+        self.setAllowedAreas(
+            allowed_areas
+            or (Qt.DockWidgetArea.LeftDockWidgetArea | Qt.DockWidgetArea.RightDockWidgetArea)
+        )
+
+    def begin_task(self, *args: Any, **kwargs: Any) -> ProgressResult:
+        return self.progress_widget.begin_task(*args, **kwargs)
+
+    def update_progress(self, *args: Any, **kwargs: Any) -> ProgressResult:
+        return self.progress_widget.update_progress(*args, **kwargs)
+
+    def finish_task(self, *args: Any, **kwargs: Any) -> ProgressResult:
+        return self.progress_widget.finish_task(*args, **kwargs)
+
+    def append_message(self, *args: Any, **kwargs: Any) -> ProgressResult:
+        return self.progress_widget.append_message(*args, **kwargs)
+
+    def clear_info(self) -> ProgressResult:
+        return self.progress_widget.clear_info()
+
+    def set_paused_state(self, is_paused: bool) -> ProgressResult:
+        return self.progress_widget.set_paused_state(is_paused)
+
+    def set_project_filter(self, project_id: Optional[str]) -> ProgressResult:
+        return self.progress_widget.set_project_filter(project_id)
+
+    def get_params_dict(self) -> Dict[str, Any]:
+        return self.progress_widget.get_params_dict()
+
+    def load_params_dict(self, params_dict: Mapping[str, Any]) -> ProgressResult:
+        return self.progress_widget.load_params_dict(params_dict)
+
+    def fry_reload(self, params_dict: Optional[Mapping[str, Any]] = None) -> ProgressResult:
+        return self.progress_widget.fry_reload(params_dict)
+
+    def fry_reset(self) -> ProgressResult:
+        return self.progress_widget.fry_reset()
+
+    @pyqtSlot(str, str)
+    def handle_task_begin(self, project_id: str, total_task_name: str) -> ProgressResult:
+        return self.progress_widget.handle_task_begin(project_id, total_task_name)
+
+    @pyqtSlot(dict)
+    def handle_task_progress(self, task_data_dict: Dict[str, Any]) -> ProgressResult:
+        return self.progress_widget.handle_task_progress(task_data_dict)
+
+    @pyqtSlot(str)
+    def handle_task_finished(self, project_id: str) -> ProgressResult:
+        return self.progress_widget.handle_task_finished(project_id)