fry-qt6-progress-widget 0.1.0__py3-none-any.whl

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/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)

fry_qt6_progress_widget/progress_widget.py

@@ -0,0 +1,743 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from html import escape
+import math
+import time
+from typing import Any, Callable, ClassVar, Dict, Mapping, Optional, Tuple
+
+from PyQt6.QtCore import Qt, pyqtSignal, pyqtSlot
+from PyQt6.QtGui import QTextCursor
+from PyQt6.QtWidgets import (
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QProgressBar,
+    QScrollArea,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+
+@dataclass(frozen=True)
+class ProgressResult:
+    """Small result object returned by public mutating methods."""
+
+    status: str
+    message: str = ""
+    data: Optional[Dict[str, Any]] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.status != "failed"
+
+    @classmethod
+    def success(cls, message: str = "", data: Optional[Dict[str, Any]] = None) -> "ProgressResult":
+        return cls(status="success", message=message, data=data)
+
+    @classmethod
+    def info(cls, message: str = "", data: Optional[Dict[str, Any]] = None) -> "ProgressResult":
+        return cls(status="info", message=message, data=data)
+
+    @classmethod
+    def warning(cls, message: str = "", data: Optional[Dict[str, Any]] = None) -> "ProgressResult":
+        return cls(status="warning", message=message, data=data)
+
+    @classmethod
+    def failed(cls, message: str = "", data: Optional[Dict[str, Any]] = None) -> "ProgressResult":
+        return cls(status="failed", message=message, data=data)
+
+
+@dataclass(frozen=True)
+class InfoTypeConfig:
+    """Display colors for detail messages."""
+
+    color: str
+    icon: str
+    icon_color: str
+
+    TYPE_CONFIGS: ClassVar[Dict[str, Tuple[str, str, str]]] = {
+        "信息": ("#1F2937", "info-circle", "#4C566A"),
+        "成功": ("#2E7D32", "check-circle", "#2E7D32"),
+        "失败": ("#C62828", "times-circle", "#C62828"),
+        "异常": ("#C62828", "exclamation-triangle", "#C62828"),
+        "警告": ("#B45309", "exclamation-circle", "#B45309"),
+        "调试": ("#6D28D9", "bug", "#6D28D9"),
+        "重要": ("#1D4ED8", "star", "#1D4ED8"),
+        "info": ("#1F2937", "info-circle", "#4C566A"),
+        "success": ("#2E7D32", "check-circle", "#2E7D32"),
+        "error": ("#C62828", "times-circle", "#C62828"),
+        "warning": ("#B45309", "exclamation-circle", "#B45309"),
+        "debug": ("#6D28D9", "bug", "#6D28D9"),
+    }
+
+    @classmethod
+    def get_config(cls, info_type: str) -> "InfoTypeConfig":
+        config = cls.TYPE_CONFIGS.get(info_type, cls.TYPE_CONFIGS["信息"])
+        return cls(color=config[0], icon=config[1], icon_color=config[2])
+
+
+class GeneralTaskProgressWidget(QWidget):
+    """A reusable PyQt6 widget for showing long-running task progress."""
+
+    taskStarted = pyqtSignal(str, str)
+    progressChanged = pyqtSignal(dict)
+    taskFinished = pyqtSignal(str)
+    messageAppended = pyqtSignal(str, str)
+    pausedChanged = pyqtSignal(bool)
+
+    def __init__(
+        self,
+        parent: Optional[QWidget] = None,
+        *,
+        title: str = "任务进度",
+        accepted_project_id: Optional[str] = None,
+        auto_show: bool = False,
+        max_detail_blocks: int = 500,
+        logger: Optional[Callable[[str, str], None]] = None,
+        clock: Optional[Callable[[], float]] = None,
+    ) -> None:
+        super().__init__(parent)
+        self.title = title
+        self.accepted_project_id = accepted_project_id
+        self.auto_show = auto_show
+        self.max_detail_blocks = max_detail_blocks
+        self.logger = logger
+        self._clock = clock or time.monotonic
+
+        self.current_project_id = ""
+        self.current_task_name = ""
+        self.current_progress = 0
+        self.total_progress = 0
+        self.is_paused = False
+        self._task_time_records: Dict[str, Dict[str, Any]] = {}
+        # 滑动窗口大小：用最近这么多个进度样本估算吞吐率（越大越平滑，越小越灵敏）
+        self._eta_window_size = 20
+
+        self.setObjectName("FryTaskProgressWidget")
+        self._setup_ui()
+        self._apply_styles()
+        self.clear_info()
+
+    def set_project_filter(self, project_id: Optional[str]) -> ProgressResult:
+        """Accept only updates for project_id. Pass None to accept all projects."""
+        self.accepted_project_id = project_id
+        return ProgressResult.success("项目过滤器已更新")
+
+    def begin_task(
+        self,
+        project_id: str = "",
+        task_name: str = "任务",
+        total: Optional[Any] = None,
+        *,
+        clear: bool = True,
+    ) -> ProgressResult:
+        """Start a task and reset the visible progress state."""
+        try:
+            if not self._should_accept_project(project_id):
+                return ProgressResult.info("忽略其他项目的任务开始信号")
+
+            if clear:
+                self.clear_info()
+
+            self.current_project_id = str(project_id or "")
+            self.current_task_name = str(task_name or "任务")
+            self.current_progress = 0
+            self.total_progress = self._coerce_int(total, 0)
+            self.is_paused = False
+            self._task_time_records.clear()
+
+            self.project_id_value.setText(self.current_project_id or "无")
+            self.task_name_value.setText(self.current_task_name)
+            self._set_status("running", "运行中")
+            self._render_progress()
+            self._append_detail_info("信息", f"任务开始: {self.current_task_name}", log=False)
+
+            if self.auto_show:
+                self.show()
+
+            self.taskStarted.emit(self.current_project_id, self.current_task_name)
+            self.progressChanged.emit(self.get_params_dict())
+            return ProgressResult.success("任务已开始", self.get_params_dict())
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"任务开始失败: {exc}")
+
+    def update_progress(
+        self,
+        current: Optional[Any] = None,
+        total: Optional[Any] = None,
+        *,
+        task_name: Optional[str] = None,
+        project_id: Optional[str] = None,
+        info_type: str = "信息",
+        detail_info: str = "",
+    ) -> ProgressResult:
+        """Update progress and optionally append one detail message."""
+        try:
+            resolved_project_id = self.current_project_id if project_id is None else str(project_id or "")
+            if not self._should_accept_project(resolved_project_id):
+                return ProgressResult.info("忽略其他项目的任务进度")
+
+            if resolved_project_id:
+                self.current_project_id = resolved_project_id
+                self.project_id_value.setText(resolved_project_id)
+
+            if task_name:
+                self.current_task_name = str(task_name)
+                self.task_name_value.setText(self.current_task_name)
+
+            if total is not None:
+                self.total_progress = self._coerce_int(total, self.total_progress)
+
+            if current is not None:
+                self.current_progress = self._coerce_int(current, self.current_progress)
+
+            self.current_progress = max(0, self.current_progress)
+            self.total_progress = max(0, self.total_progress)
+            if self.total_progress:
+                self.current_progress = min(self.current_progress, self.total_progress)
+
+            self._set_status("paused" if self.is_paused else "running", "已暂停" if self.is_paused else "运行中")
+            self._render_progress()
+            self._update_time_estimate()
+
+            if detail_info:
+                self._append_detail_info(info_type, detail_info)
+
+            if self.auto_show:
+                self.show()
+
+            self.progressChanged.emit(self.get_params_dict())
+            return ProgressResult.success("任务进度已更新", self.get_params_dict())
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            self._log("异常", f"处理任务进度更新失败: {exc}")
+            return ProgressResult.failed(f"任务进度更新失败: {exc}")
+
+    def finish_task(
+        self,
+        project_id: Optional[str] = None,
+        *,
+        message: str = "任务已完成",
+        hide: bool = False,
+    ) -> ProgressResult:
+        """Mark the current task as finished."""
+        try:
+            resolved_project_id = self.current_project_id if project_id is None else str(project_id or "")
+            if not self._should_accept_project(resolved_project_id):
+                return ProgressResult.info("忽略其他项目的任务完成信号")
+
+            if self.total_progress > 0:
+                self.current_progress = self.total_progress
+
+            self.is_paused = False
+            self._set_status("success", "已完成")
+            self._render_progress()
+            self._update_time_estimate(force_done=True)
+            self._append_detail_info("成功", message)
+            self._task_time_records.clear()
+
+            if hide:
+                self.hide()
+
+            self.taskFinished.emit(resolved_project_id)
+            self.progressChanged.emit(self.get_params_dict())
+            return ProgressResult.success("任务已完成", self.get_params_dict())
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"任务完成处理失败: {exc}")
+
+    def append_message(self, info_type: str, message: str) -> ProgressResult:
+        """Append a message to the detail area."""
+        return self._append_detail_info(info_type, message)
+
+    def clear_info(self) -> ProgressResult:
+        """Reset all visible values."""
+        try:
+            self.current_project_id = ""
+            self.current_task_name = ""
+            self.current_progress = 0
+            self.total_progress = 0
+            self.is_paused = False
+            self._task_time_records.clear()
+
+            self.project_id_value.setText("无")
+            self.task_name_value.setText("无")
+            self.progress_label.setText("进度: 0 / 0")
+            self.progress_percent.setText("0%")
+            self.progress_bar.setRange(0, 100)
+            self.progress_bar.setValue(0)
+            self.progress_bar.setStyleSheet("")
+            self.time_estimate_label.setText("")
+            self.detail_text.clear()
+            self._set_status("idle", "未开始")
+            return ProgressResult.success("信息已清空")
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"清空信息失败: {exc}")
+
+    def set_paused_state(self, is_paused: bool) -> ProgressResult:
+        """Switch between running and paused visual states."""
+        try:
+            self.is_paused = bool(is_paused)
+            if self.is_paused:
+                self._set_status("paused", "已暂停")
+                self._set_progress_bar_color("#D97706", "#F59E0B")
+                self._append_detail_info("警告", "任务已暂停")
+            else:
+                self._set_status("running", "运行中")
+                self.progress_bar.setStyleSheet("")
+                self._append_detail_info("信息", "任务已恢复")
+
+            self.pausedChanged.emit(self.is_paused)
+            self.progressChanged.emit(self.get_params_dict())
+            return ProgressResult.success(f"暂停状态已设置为: {self.is_paused}")
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"设置暂停状态失败: {exc}")
+
+    def get_params_dict(self) -> Dict[str, Any]:
+        """Return a serializable snapshot of the widget state."""
+        percent = self._current_percent()
+        return {
+            "current_project_id": self.current_project_id,
+            "project_id_value": self.project_id_value.text(),
+            "task_name_value": self.task_name_value.text(),
+            "current_progress": self.current_progress,
+            "total_progress": self.total_progress,
+            "progress_value": self.progress_bar.value(),
+            "progress_percent_num": percent,
+            "progress_label": self.progress_label.text(),
+            "progress_percent": self.progress_percent.text(),
+            "status": self.status_value.text(),
+            "is_paused": self.is_paused,
+            "time_estimate": self.time_estimate_label.text(),
+            "detail_text": self.detail_text.toHtml(),
+            "detail_plain_text": self.detail_text.toPlainText(),
+        }
+
+    def load_params_dict(self, params_dict: Mapping[str, Any]) -> ProgressResult:
+        """Restore a snapshot created by get_params_dict."""
+        try:
+            if not params_dict:
+                return ProgressResult.info("参数字典为空，跳过加载")
+
+            self.current_project_id = str(params_dict.get("current_project_id", self.current_project_id))
+            self.current_task_name = str(params_dict.get("task_name_value", self.current_task_name))
+            self.current_progress = self._coerce_int(params_dict.get("current_progress"), self.current_progress)
+            self.total_progress = self._coerce_int(params_dict.get("total_progress"), self.total_progress)
+            self.is_paused = bool(params_dict.get("is_paused", self.is_paused))
+
+            self.project_id_value.setText(str(params_dict.get("project_id_value", self.current_project_id or "无")))
+            self.task_name_value.setText(str(params_dict.get("task_name_value", self.current_task_name or "无")))
+            self.progress_label.setText(str(params_dict.get("progress_label", "进度: 0 / 0")))
+            self.progress_percent.setText(str(params_dict.get("progress_percent", "0%")))
+            self.time_estimate_label.setText(str(params_dict.get("time_estimate", "")))
+
+            progress_value = self._coerce_int(params_dict.get("progress_value"), 0)
+            self.progress_bar.setRange(0, 100)
+            self.progress_bar.setValue(max(0, min(progress_value, 100)))
+
+            if "detail_text" in params_dict:
+                self.detail_text.setHtml(str(params_dict["detail_text"]))
+
+            status_text = str(params_dict.get("status", "已暂停" if self.is_paused else "未开始"))
+            self._set_status("paused" if self.is_paused else "idle", status_text)
+            return ProgressResult.success("参数字典已加载")
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"加载参数字典失败: {exc}")
+
+    def fry_reload(self, params_dict: Optional[Mapping[str, Any]] = None) -> ProgressResult:
+        """Compatibility alias for applications that use fry_reload."""
+        if params_dict is None:
+            return self.fry_reset()
+        return self.load_params_dict(params_dict)
+
+    def fry_reset(self) -> ProgressResult:
+        """Compatibility alias for resetting the widget."""
+        return self.clear_info()
+
+    @pyqtSlot(str, str)
+    def handle_task_begin(self, project_id: str, total_task_name: str) -> ProgressResult:
+        """Qt slot compatible with the original dock implementation."""
+        return self.begin_task(project_id=project_id, task_name=total_task_name)
+
+    @pyqtSlot(dict)
+    def handle_task_progress(self, task_data_dict: Dict[str, Any]) -> ProgressResult:
+        """Qt slot accepting the original task progress dictionary keys."""
+        task_data_dict = task_data_dict or {}
+        project_id = task_data_dict.get("project_id_str", task_data_dict.get("project_id"))
+        task_name = task_data_dict.get("task_name_str", task_data_dict.get("task_name"))
+        current = task_data_dict.get("now_progress_num", task_data_dict.get("current_progress"))
+        total = task_data_dict.get("total_num", task_data_dict.get("total_progress"))
+        info_type = task_data_dict.get("info_type", "信息")
+        detail_info = task_data_dict.get("detail_info", task_data_dict.get("message", ""))
+        return self.update_progress(
+            current=current,
+            total=total,
+            task_name=task_name,
+            project_id=project_id,
+            info_type=info_type,
+            detail_info=detail_info,
+        )
+
+    @pyqtSlot(str)
+    def handle_task_finished(self, project_id: str) -> ProgressResult:
+        """Qt slot compatible with the original dock implementation."""
+        return self.finish_task(project_id=project_id)
+
+    def _setup_ui(self) -> None:
+        self.setMinimumWidth(320)
+
+        root_layout = QVBoxLayout(self)
+        root_layout.setContentsMargins(0, 0, 0, 0)
+        root_layout.setSpacing(0)
+
+        scroll_area = QScrollArea()
+        scroll_area.setWidgetResizable(True)
+        scroll_area.setFrameShape(QFrame.Shape.NoFrame)
+        scroll_area.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAsNeeded)
+        scroll_area.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAsNeeded)
+
+        main_widget = QWidget()
+        main_widget.setObjectName("FryProgressContent")
+        main_layout = QVBoxLayout(main_widget)
+        main_layout.setContentsMargins(12, 12, 12, 12)
+        main_layout.setSpacing(10)
+
+        title_label = QLabel(self.title)
+        title_label.setObjectName("FryProgressTitle")
+        main_layout.addWidget(title_label)
+
+        self._create_project_info_section(main_layout)
+        self._add_separator(main_layout)
+        self._create_task_info_section(main_layout)
+        self._add_separator(main_layout)
+        self._create_progress_section(main_layout)
+        self._add_separator(main_layout)
+        self._create_detail_info_section(main_layout)
+
+        main_layout.addStretch()
+        scroll_area.setWidget(main_widget)
+        root_layout.addWidget(scroll_area)
+
+    def _create_project_info_section(self, parent_layout: QVBoxLayout) -> None:
+        project_label = QLabel("项目 ID:")
+        project_label.setObjectName("FrySectionLabel")
+        self.project_id_value = QLabel("无")
+        self.project_id_value.setWordWrap(True)
+        self.project_id_value.setObjectName("FryValueLabel")
+        parent_layout.addWidget(project_label)
+        parent_layout.addWidget(self.project_id_value)
+
+    def _create_task_info_section(self, parent_layout: QVBoxLayout) -> None:
+        status_layout = QHBoxLayout()
+        status_label = QLabel("状态:")
+        status_label.setObjectName("FrySectionLabel")
+        self.status_value = QLabel("未开始")
+        self.status_value.setObjectName("FryStatusValue")
+        status_layout.addWidget(status_label)
+        status_layout.addWidget(self.status_value)
+        status_layout.addStretch()
+        parent_layout.addLayout(status_layout)
+
+        task_layout = QHBoxLayout()
+        task_label = QLabel("任务名称:")
+        task_label.setObjectName("FrySectionLabel")
+        self.task_name_value = QLabel("无")
+        self.task_name_value.setObjectName("FryValueLabel")
+        self.task_name_value.setWordWrap(True)
+        task_layout.addWidget(task_label)
+        task_layout.addWidget(self.task_name_value, 1)
+        parent_layout.addLayout(task_layout)
+
+    def _create_progress_section(self, parent_layout: QVBoxLayout) -> None:
+        progress_info_layout = QHBoxLayout()
+        self.progress_label = QLabel("进度: 0 / 0")
+        self.progress_label.setMinimumWidth(150)
+        self.progress_label.setObjectName("FrySectionLabel")
+
+        self.progress_percent = QLabel("0%")
+        self.progress_percent.setObjectName("FryPercentLabel")
+
+        progress_info_layout.addWidget(self.progress_label)
+        progress_info_layout.addStretch()
+        progress_info_layout.addWidget(self.progress_percent)
+        parent_layout.addLayout(progress_info_layout)
+
+        self.progress_bar = QProgressBar()
+        self.progress_bar.setRange(0, 100)
+        self.progress_bar.setValue(0)
+        self.progress_bar.setTextVisible(False)
+        self.progress_bar.setMinimumHeight(24)
+        parent_layout.addWidget(self.progress_bar)
+
+        self.time_estimate_label = QLabel("")
+        self.time_estimate_label.setObjectName("FryTimeEstimate")
+        self.time_estimate_label.setWordWrap(True)
+        parent_layout.addWidget(self.time_estimate_label)
+
+    def _create_detail_info_section(self, parent_layout: QVBoxLayout) -> None:
+        detail_label = QLabel("详细信息:")
+        detail_label.setObjectName("FrySectionLabel")
+        parent_layout.addWidget(detail_label)
+
+        self.detail_text = QTextEdit()
+        self.detail_text.setReadOnly(True)
+        self.detail_text.setMinimumHeight(150)
+        self.detail_text.setMaximumHeight(320)
+        self.detail_text.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn)
+        self.detail_text.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAsNeeded)
+        self.detail_text.document().setMaximumBlockCount(max(0, int(self.max_detail_blocks)))
+        parent_layout.addWidget(self.detail_text)
+
+    def _add_separator(self, parent_layout: QVBoxLayout) -> None:
+        separator = QFrame()
+        separator.setFrameShape(QFrame.Shape.HLine)
+        separator.setFrameShadow(QFrame.Shadow.Sunken)
+        parent_layout.addWidget(separator)
+
+    def _apply_styles(self) -> None:
+        self.setStyleSheet(
+            """
+            QWidget#FryTaskProgressWidget,
+            QWidget#FryProgressContent {
+                background-color: #F8FAFC;
+                color: #111827;
+                font-family: "Microsoft YaHei", "Segoe UI", sans-serif;
+            }
+            QLabel#FryProgressTitle {
+                color: #111827;
+                font-size: 16px;
+                font-weight: 700;
+                padding-bottom: 2px;
+            }
+            QLabel#FrySectionLabel {
+                color: #4B5563;
+                font-size: 12px;
+                font-weight: 700;
+            }
+            QLabel#FryValueLabel {
+                color: #111827;
+                font-size: 12px;
+                padding: 3px 0;
+            }
+            QLabel#FryPercentLabel {
+                color: #1D4ED8;
+                font-size: 12px;
+                font-weight: 700;
+            }
+            QLabel#FryTimeEstimate {
+                color: #2563EB;
+                font-size: 11px;
+                font-style: italic;
+            }
+            QLabel#FryStatusValue {
+                border-radius: 4px;
+                color: white;
+                font-size: 11px;
+                font-weight: 700;
+                padding: 2px 8px;
+            }
+            QScrollArea {
+                background-color: #F8FAFC;
+                border: none;
+            }
+            QProgressBar {
+                background-color: #E5E7EB;
+                border: 1px solid #CBD5E1;
+                border-radius: 5px;
+                text-align: center;
+            }
+            QProgressBar::chunk {
+                background-color: qlineargradient(
+                    x1:0, y1:0, x2:1, y2:0,
+                    stop:0 #2563EB,
+                    stop:1 #38BDF8
+                );
+                border-radius: 4px;
+            }
+            QTextEdit {
+                background-color: #FFFFFF;
+                border: 1px solid #CBD5E1;
+                border-radius: 4px;
+                color: #111827;
+                padding: 5px;
+            }
+            QFrame {
+                color: #E5E7EB;
+            }
+            """
+        )
+
+    def _render_progress(self) -> None:
+        if self.total_progress <= 0:
+            self.progress_bar.setRange(0, 0)
+            self.progress_label.setText(f"进度: {self.current_progress} / 未知")
+            self.progress_percent.setText("计算中")
+            return
+
+        percent = self._current_percent()
+        self.progress_bar.setRange(0, 100)
+        self.progress_bar.setValue(int(round(percent)))
+        self.progress_label.setText(f"进度: {self.current_progress} / {self.total_progress}")
+        self.progress_percent.setText(f"{percent:g}%")
+
+    def _update_time_estimate(self, *, force_done: bool = False) -> None:
+        """更新预估时间。
+
+        优化点：剩余时间用「滑动窗口内的最近吞吐率」估算，而非自起点的累计平均。
+        当任务速度随时间变化时（前慢后快 / 前快后慢），窗口估计更灵敏、更接近真实。
+        窗口不足时自动回退到累计平均。
+        """
+        task_key = self.current_task_name or "__default__"
+        now = self._clock()
+        cur = float(self.current_progress)
+        record = self._task_time_records.get(task_key)
+
+        if record is None:
+            self._task_time_records[task_key] = {
+                "first_time": now,
+                "first_progress": cur,
+                "samples": [(now, cur)],  # 滑动窗口样本 (时间, 进度)
+            }
+            self.time_estimate_label.setText("正在计算预估时间...")
+            return
+
+        # 追加样本并裁剪窗口（最多保留最近 self._eta_window_size 个样本）
+        samples = record["samples"]
+        samples.append((now, cur))
+        if len(samples) > self._eta_window_size:
+            del samples[: len(samples) - self._eta_window_size]
+
+        elapsed_total = max(0.0, now - record["first_time"])
+        if force_done or (self.total_progress > 0 and self.current_progress >= self.total_progress):
+            self.time_estimate_label.setText(f"已完成，用时: {self._format_time(elapsed_total)}")
+            return
+
+        if self.total_progress <= 0:
+            self.time_estimate_label.setText("正在计算预估时间...")
+            return
+
+        # 优先用窗口内（最早样本 -> 当前）的速率；不足则回退到累计平均
+        win_time0, win_prog0 = samples[0]
+        win_elapsed = now - win_time0
+        win_diff = cur - win_prog0
+        if win_diff > 0 and win_elapsed > 0:
+            time_per_unit = win_elapsed / win_diff
+        else:
+            cum_elapsed = elapsed_total
+            cum_diff = cur - record["first_progress"]
+            if cum_diff <= 0 or cum_elapsed <= 0:
+                self.time_estimate_label.setText("正在计算预估时间...")
+                return
+            time_per_unit = cum_elapsed / cum_diff
+
+        remaining_progress = max(0, self.total_progress - self.current_progress)
+        remaining_seconds = time_per_unit * remaining_progress
+        self.time_estimate_label.setText(
+            f"平均耗时: {self._format_time(time_per_unit)}/单位  |  预计剩余: {self._format_time(remaining_seconds)}"
+        )
+
+    def _format_time(self, seconds: float) -> str:
+        seconds = max(0.0, float(seconds))
+        if seconds < 1:
+            return f"{seconds:.2f} 秒"
+        if seconds < 60:
+            return f"{seconds:.1f} 秒"
+        if seconds < 3600:
+            return f"{seconds / 60:.1f} 分钟"
+        return f"{seconds / 3600:.1f} 小时"
+
+    def _append_detail_info(self, info_type: str, message: str, *, log: bool = True) -> ProgressResult:
+        try:
+            info_type = str(info_type or "信息")
+            message = str(message or "")
+            config = InfoTypeConfig.get_config(info_type)
+            timestamp = datetime.now().strftime("%H:%M:%S")
+
+            cursor = self.detail_text.textCursor()
+            cursor.movePosition(QTextCursor.MoveOperation.End)
+            self.detail_text.setTextCursor(cursor)
+
+            safe_type = escape(info_type)
+            safe_message = escape(message).replace("\n", "<br>")
+            html_text = (
+                f'<div style="margin: 2px 0;">'
+                f'<span style="color: #6B7280;">[{timestamp}]</span> '
+                f'<span style="color: {config.color}; font-weight: 600;">[{safe_type}]</span> '
+                f'<span style="color: {config.color};">{safe_message}</span>'
+                f"</div>"
+            )
+            self.detail_text.insertHtml(html_text)
+
+            scrollbar = self.detail_text.verticalScrollBar()
+            scrollbar.setValue(scrollbar.maximum())
+
+            if log:
+                self._log(info_type, message)
+
+            self.messageAppended.emit(info_type, message)
+            return ProgressResult.success("详细信息已追加")
+        except Exception as exc:  # pragma: no cover - defensive Qt boundary
+            return ProgressResult.failed(f"追加详细信息失败: {exc}")
+
+    def _set_status(self, status: str, text: str) -> None:
+        colors = {
+            "idle": "#64748B",
+            "running": "#2563EB",
+            "paused": "#D97706",
+            "success": "#16A34A",
+            "warning": "#B45309",
+            "error": "#DC2626",
+        }
+        color = colors.get(status, colors["idle"])
+        self.status_value.setText(text)
+        self.status_value.setStyleSheet(f"background-color: {color};")
+
+    def _set_progress_bar_color(self, start_color: str, end_color: str) -> None:
+        self.progress_bar.setStyleSheet(
+            f"""
+            QProgressBar {{
+                background-color: #E5E7EB;
+                border: 1px solid #CBD5E1;
+                border-radius: 5px;
+                text-align: center;
+            }}
+            QProgressBar::chunk {{
+                background-color: qlineargradient(
+                    x1:0, y1:0, x2:1, y2:0,
+                    stop:0 {start_color},
+                    stop:1 {end_color}
+                );
+                border-radius: 4px;
+            }}
+            """
+        )
+
+    def _current_percent(self) -> float:
+        if self.total_progress <= 0:
+            return 0.0
+        percent = self.current_progress * 100.0 / self.total_progress
+        if math.isnan(percent) or math.isinf(percent):
+            return 0.0
+        return round(max(0.0, min(percent, 100.0)), 2)
+
+    def _should_accept_project(self, project_id: Optional[str]) -> bool:
+        if self.accepted_project_id is None:
+            return True
+        return str(project_id or "") == str(self.accepted_project_id)
+
+    def _coerce_int(self, value: Optional[Any], default: int = 0) -> int:
+        if value is None:
+            return int(default)
+        try:
+            return int(float(value))
+        except (TypeError, ValueError):
+            return int(default)
+
+    def _log(self, info_type: str, message: str) -> None:
+        if self.logger is None:
+            return
+        try:
+            self.logger(info_type, message)
+        except Exception:
+            pass

fry_qt6_progress_widget/py.typed

@@ -0,0 +1 @@
+

fry_qt6_progress_widget-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+fry_qt6_progress_widget/__init__.py,sha256=mJ7TE7vi2PqbjYcfJOBYGZIfHkuqnTSrlGGLPhDtCgg,432
+fry_qt6_progress_widget/dock.py,sha256=YHNVJffy9CuzNeVoCsKnlVAHh0sr5NvehFNt2Qyd8mo,3049
+fry_qt6_progress_widget/progress_widget.py,sha256=6eWxSxb8QFHEPDMdQAdwW2uYMGKXqvUjzdr6psVj6GY,31246
+fry_qt6_progress_widget/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+fry_qt6_progress_widget-0.1.0.dist-info/METADATA,sha256=OsZKNFMJgxwuEhk2BITow4GiZlxS4aHOwFf3ELdN_r0,4032
+fry_qt6_progress_widget-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fry_qt6_progress_widget-0.1.0.dist-info/top_level.txt,sha256=lh3Q_guArX17kDSWcZjuWLyUGWK5_FjLxhmHtTDsvO4,24
+fry_qt6_progress_widget-0.1.0.dist-info/RECORD,,

fry_qt6_progress_widget-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fry_qt6_progress_widget-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fry_qt6_progress_widget