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/*
```
