iOpenPod 2.0.4__py3-none-any.whl

iOpenPod/GUI/presentation/photo.py

@@ -0,0 +1,47 @@
+"""Aspect-preserving Photo painting shared by cards and the inspector."""
+
+from PySide6.QtCore import QRectF, Qt
+from PySide6.QtGui import QColor, QPainter, QPainterPath, QPen, QPixmap
+
+from iOpenPod.GUI.presentation.theme.tokens import ThemeTokens
+
+
+def paint_photo_pixmap(
+    painter: QPainter,
+    rect: QRectF,
+    pixmap: QPixmap,
+    tokens: ThemeTokens,
+    radius: float,
+) -> None:
+    """Letterbox one Photo within ``rect`` while retaining its aspect ratio."""
+
+    clip = QPainterPath()
+    clip.addRoundedRect(rect, radius, radius)
+    source = QRectF(pixmap.rect())
+    if source.isEmpty():
+        return
+    scale = min(rect.width() / source.width(), rect.height() / source.height())
+    width = source.width() * scale
+    height = source.height() * scale
+    target = QRectF(
+        rect.left() + (rect.width() - width) / 2.0,
+        rect.top() + (rect.height() - height) / 2.0,
+        width,
+        height,
+    )
+
+    painter.save()
+    painter.setClipPath(clip)
+    painter.fillRect(rect, QColor(tokens.surface_alt))
+    painter.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform, True)
+    painter.drawPixmap(target, pixmap, source)
+    painter.restore()
+
+    border = QPen(QColor(tokens.border))
+    border.setWidthF(1.0)
+    painter.setPen(border)
+    painter.setBrush(Qt.BrushStyle.NoBrush)
+    painter.drawRoundedRect(rect, radius, radius)
+
+
+__all__ = ["paint_photo_pixmap"]

iOpenPod/GUI/presentation/photo_provider.py

@@ -0,0 +1,182 @@
+"""GUI-thread conversion of lazily decoded Photo images into display pixmaps."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from math import ceil
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Signal, Slot
+from PySide6.QtGui import QImage, QPixmap, QPixmapCache
+
+from iOpenPod.app.models.photos import PhotoImage
+from iOpenPod.app.photo_controller import PhotoLoadFailure, PhotoUnavailable
+
+if TYPE_CHECKING:
+    from iOpenPod.app.photo_controller import PhotoController
+
+_CACHE_PREFIX = "iOpenPod/photo/"
+
+
+class PhotoPixmapState(StrEnum):
+    """Presentation state for one automatic or exact Photo representation."""
+
+    IDLE = "idle"
+    LOADING = "loading"
+    READY = "ready"
+    UNAVAILABLE = "unavailable"
+    FAILED = "failed"
+
+
+class PhotoPixmapProvider(QObject):
+    """Bridge owned Photo RGB pixels to Qt's bounded display-pixmap cache."""
+
+    photoChanged = Signal(object)
+    cleared = Signal()
+    capacityAvailable = Signal()
+
+    def __init__(
+        self,
+        controller: PhotoController,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self._controller = controller
+        self._qt_cache_keys: set[str] = set()
+        self._states: dict[tuple[int, int | None], PhotoPixmapState] = {}
+        self._closed = False
+        controller.photoReady.connect(self._photo_ready)
+        controller.photoUnavailable.connect(self._photo_unavailable)
+        controller.photoFailed.connect(self._photo_failed)
+        controller.generationChanged.connect(self._generation_changed)
+        controller.capacityAvailable.connect(self._capacity_available)
+
+    def pixmap(
+        self,
+        photo_id: int,
+        logical_size: int,
+        device_pixel_ratio: float,
+        *,
+        format_id: int | None = None,
+    ) -> QPixmap | None:
+        """Return a pixmap now, queuing automatic or exact-format decode on miss."""
+
+        if (
+            self._closed
+            or photo_id <= 0
+            or logical_size <= 0
+            or (format_id is not None and format_id < 0)
+        ):
+            return None
+        target_px = max(1, ceil(logical_size * max(1.0, device_pixel_ratio)))
+        image = self._controller.request(
+            photo_id,
+            target_px,
+            format_id=format_id,
+        )
+        if image is None:
+            key = (photo_id, format_id)
+            if self._states.get(key) not in (
+                PhotoPixmapState.UNAVAILABLE,
+                PhotoPixmapState.FAILED,
+            ):
+                self._states[key] = PhotoPixmapState.LOADING
+            return None
+        self._states[(photo_id, format_id)] = PhotoPixmapState.READY
+        return self._pixmap_for(image)
+
+    def state(
+        self,
+        photo_id: int,
+        *,
+        format_id: int | None = None,
+    ) -> PhotoPixmapState:
+        """Return the last observed presentation state without starting I/O."""
+
+        return self._states.get((photo_id, format_id), PhotoPixmapState.IDLE)
+
+    def retry(self, photo_id: int, *, format_id: int | None = None) -> None:
+        """Clear one terminal state so the next paint retries the request."""
+
+        if self._closed or photo_id <= 0 or (format_id is not None and format_id < 0):
+            return
+        self._controller.retry(photo_id, format_id=format_id)
+        self._states.pop((photo_id, format_id), None)
+        self.photoChanged.emit(photo_id)
+
+    def shutdown(self) -> None:
+        """Release presentation cache entries before the owning window closes."""
+
+        if self._closed:
+            return
+        self._closed = True
+        self._clear_pixmaps()
+        self._states.clear()
+
+    @Slot(object)
+    def _photo_ready(self, value: object) -> None:
+        if self._closed or not isinstance(value, PhotoImage):
+            return
+        self._pixmap_for(value)
+        for key in tuple(self._states):
+            if key[0] == value.photo_id and (
+                key[1] is None or key[1] == value.format_id
+            ):
+                self._states[key] = PhotoPixmapState.READY
+        self.photoChanged.emit(value.photo_id)
+
+    @Slot(object)
+    def _photo_unavailable(self, value: object) -> None:
+        if self._closed or not isinstance(value, PhotoUnavailable):
+            return
+        self._states[(value.photo_id, value.format_id)] = PhotoPixmapState.UNAVAILABLE
+        self.photoChanged.emit(value.photo_id)
+
+    @Slot(object)
+    def _photo_failed(self, value: object) -> None:
+        if self._closed or not isinstance(value, PhotoLoadFailure):
+            return
+        self._states[(value.photo_id, value.format_id)] = PhotoPixmapState.FAILED
+        self.photoChanged.emit(value.photo_id)
+
+    @Slot(int)
+    def _generation_changed(self, _generation: int) -> None:
+        if self._closed:
+            return
+        self._clear_pixmaps()
+        self._states.clear()
+        self.cleared.emit()
+
+    @Slot()
+    def _capacity_available(self) -> None:
+        if not self._closed:
+            self.capacityAvailable.emit()
+
+    def _clear_pixmaps(self) -> None:
+        for cache_key in self._qt_cache_keys:
+            QPixmapCache.remove(cache_key)
+        self._qt_cache_keys.clear()
+
+    def _pixmap_for(self, image: PhotoImage) -> QPixmap:
+        cache_key = f"{_CACHE_PREFIX}{image.cache_key}"
+        cached = QPixmap()
+        if QPixmapCache.find(cache_key, cached) and not cached.isNull():
+            return cached
+
+        wrapped = QImage(
+            image.rgb888,
+            image.width,
+            image.height,
+            image.width * 3,
+            QImage.Format.Format_RGB888,
+        )
+        # QImage's raw-buffer constructor borrows Python memory. Detach from that
+        # buffer before crossing into Qt's independently retained pixmap cache.
+        owned = wrapped.copy()
+        pixmap = QPixmap.fromImage(owned)
+        QPixmapCache.insert(cache_key, pixmap)
+        self._qt_cache_keys.add(cache_key)
+        return pixmap
+
+
+__all__ = ["PhotoPixmapProvider", "PhotoPixmapState"]

iOpenPod/GUI/presentation/podcast_artwork_provider.py

@@ -0,0 +1,83 @@
+"""DPR-aware GUI pixmaps for asynchronously fetched Podcast artwork."""
+
+from __future__ import annotations
+
+from math import ceil
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Signal, Slot
+from PySide6.QtGui import QImage, QPixmap, QPixmapCache
+
+from iOpenPod.app.podcasts.models import PodcastArtworkImage
+
+if TYPE_CHECKING:
+    from iOpenPod.app.podcasts.artwork_controller import PodcastArtworkController
+
+_CACHE_PREFIX = "iOpenPod/podcast-artwork/"
+
+
+class PodcastArtworkPixmapProvider(QObject):
+    """Bridge remote Podcast RGB pixels to the GUI-owned pixmap cache."""
+
+    artworkChanged = Signal(str)
+
+    def __init__(
+        self,
+        controller: PodcastArtworkController,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self._controller = controller
+        self._qt_cache_keys: set[str] = set()
+        self._closed = False
+        controller.artworkReady.connect(self._artwork_ready)
+        controller.artworkUnavailable.connect(self.artworkChanged)
+
+    def pixmap(
+        self,
+        source_url: str,
+        logical_size: int,
+        device_pixel_ratio: float,
+    ) -> QPixmap | None:
+        if self._closed or not source_url.strip() or logical_size <= 0:
+            return None
+        target_px = max(1, ceil(logical_size * max(1.0, device_pixel_ratio)))
+        image = self._controller.request(source_url, target_px)
+        return self._pixmap_for(image) if image is not None else None
+
+    def shutdown(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._controller.artworkReady.disconnect(self._artwork_ready)
+        self._controller.artworkUnavailable.disconnect(self.artworkChanged)
+        for cache_key in self._qt_cache_keys:
+            QPixmapCache.remove(cache_key)
+        self._qt_cache_keys.clear()
+
+    @Slot(object)
+    def _artwork_ready(self, value: object) -> None:
+        if self._closed or not isinstance(value, PodcastArtworkImage):
+            return
+        self._pixmap_for(value)
+        self.artworkChanged.emit(value.source_url)
+
+    def _pixmap_for(self, image: PodcastArtworkImage) -> QPixmap:
+        cache_key = f"{_CACHE_PREFIX}{image.cache_key}"
+        cached = QPixmap()
+        if QPixmapCache.find(cache_key, cached) and not cached.isNull():
+            return cached
+        wrapped = QImage(
+            image.rgb888,
+            image.width,
+            image.height,
+            image.width * 3,
+            QImage.Format.Format_RGB888,
+        )
+        pixmap = QPixmap.fromImage(wrapped.copy())
+        QPixmapCache.insert(cache_key, pixmap)
+        self._qt_cache_keys.add(cache_key)
+        return pixmap
+
+
+__all__ = ["PodcastArtworkPixmapProvider"]

iOpenPod/GUI/presentation/podcast_collection_artwork.py

@@ -0,0 +1,91 @@
+"""Shared four-cover artwork treatment for the All Podcasts projection."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRectF
+from PySide6.QtGui import QColor, QPainter, QPen
+
+from iOpenPod.app.models.artwork_seed import stable_artwork_seed
+from iOpenPod.GUI.presentation.artwork import (
+    paint_artwork_pixmap,
+    paint_artwork_placeholder,
+)
+from iOpenPod.GUI.presentation.theme.tokens import LAYOUT
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from iOpenPod.app.podcasts.models import PodcastSubscription
+    from iOpenPod.GUI.presentation.artwork_provider import ArtworkPixmapProvider
+    from iOpenPod.GUI.presentation.podcast_artwork_provider import (
+        PodcastArtworkPixmapProvider,
+    )
+    from iOpenPod.GUI.presentation.theme.tokens import ThemeTokens
+
+
+def paint_podcast_collection_artwork(
+    painter: QPainter,
+    rect: QRectF,
+    subscriptions: Sequence[PodcastSubscription],
+    provider: PodcastArtworkPixmapProvider,
+    tokens: ThemeTokens,
+    device_pixel_ratio: float,
+    device_provider: ArtworkPixmapProvider | None = None,
+) -> None:
+    """Paint the first four Podcast covers as a fixed 2-by-2 collection grid."""
+
+    gap = float(LAYOUT.space_2xs)
+    tile_size = (min(rect.width(), rect.height()) - gap) / 2.0
+    tile_radius = float(LAYOUT.space_2xs)
+    for position in range(4):
+        column = position % 2
+        row = position // 2
+        tile_rect = QRectF(
+            rect.left() + column * (tile_size + gap),
+            rect.top() + row * (tile_size + gap),
+            tile_size,
+            tile_size,
+        )
+        if position >= len(subscriptions):
+            painter.setPen(QPen(QColor(tokens.border)))
+            painter.setBrush(QColor(tokens.surface_alt))
+            painter.drawRoundedRect(tile_rect, tile_radius, tile_radius)
+            continue
+
+        subscription = subscriptions[position]
+        pixmap = provider.pixmap(
+            subscription.artwork_url,
+            round(tile_size),
+            device_pixel_ratio,
+        )
+        if (
+            pixmap is None
+            and device_provider is not None
+            and subscription.artwork_id > 0
+        ):
+            pixmap = device_provider.pixmap(
+                subscription.artwork_id,
+                round(tile_size),
+                device_pixel_ratio,
+            )
+        if pixmap is None:
+            paint_artwork_placeholder(
+                painter,
+                tile_rect,
+                stable_artwork_seed(subscription.subscription_id),
+                tokens,
+                tile_radius,
+            )
+        else:
+            paint_artwork_pixmap(
+                painter,
+                tile_rect,
+                pixmap,
+                tokens,
+                tile_radius,
+            )
+
+
+__all__ = ["paint_podcast_collection_artwork"]

iOpenPod/GUI/presentation/selection_checkbox.py

@@ -0,0 +1,148 @@
+# Hallmark · component: Library selection checkbox · genre: modern-minimal
+# theme: iOpenPod · states: unchecked · checked · mixed · hover · focus · disabled
+# contrast: pass · pre-emit critique: P5 H5 E5 S5 R5 V4
+"""Shared circular selection control for virtualized Library cards."""
+
+from PySide6.QtCore import (
+    QAbstractItemModel,
+    QEvent,
+    QLineF,
+    QModelIndex,
+    QPersistentModelIndex,
+    QRectF,
+    Qt,
+)
+from PySide6.QtGui import QColor, QKeyEvent, QMouseEvent, QPainter, QPainterPath, QPen
+from PySide6.QtWidgets import QStyle, QStyleOptionViewItem
+
+from iOpenPod.GUI.presentation.library_card import (
+    library_card_artwork_rect,
+    library_card_rect,
+)
+from iOpenPod.GUI.presentation.theme.tokens import ThemeTokens, TypographyTokens
+
+_CHECKBOX_EXTENT = 36.0
+_CHECKBOX_MARGIN = 8.0
+_CHECKBOX_BORDER_WIDTH = 2.0
+
+
+def library_card_checkbox_rect(
+    option: QStyleOptionViewItem,
+    typography: TypographyTokens,
+) -> QRectF:
+    artwork = library_card_artwork_rect(option, typography)
+    return QRectF(
+        artwork.right() - _CHECKBOX_MARGIN - _CHECKBOX_EXTENT,
+        artwork.top() + _CHECKBOX_MARGIN,
+        _CHECKBOX_EXTENT,
+        _CHECKBOX_EXTENT,
+    )
+
+
+def paint_library_card_checkbox(
+    painter: QPainter,
+    option: QStyleOptionViewItem,
+    state: Qt.CheckState,
+    tokens: ThemeTokens,
+    typography: TypographyTokens,
+) -> None:
+    checked = state is Qt.CheckState.Checked
+    partial = state is Qt.CheckState.PartiallyChecked
+    active = checked or partial
+    enabled = bool(option.state & QStyle.StateFlag.State_Enabled)
+    hovered = bool(option.state & QStyle.StateFlag.State_MouseOver)
+    focused = bool(option.state & QStyle.StateFlag.State_HasFocus)
+    rect = library_card_checkbox_rect(option, typography)
+    fill = (
+        tokens.accent_hover
+        if active and hovered
+        else tokens.accent
+        if active
+        else tokens.surface_hover
+        if hovered
+        else tokens.surface
+    )
+    if not enabled:
+        fill = tokens.surface_alt
+    border = tokens.text_disabled if not enabled else tokens.border_strong
+    mark = tokens.text_disabled if not enabled else tokens.accent_ink
+
+    painter.save()
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+    if focused:
+        painter.setPen(QPen(QColor(tokens.focus), _CHECKBOX_BORDER_WIDTH))
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.drawEllipse(rect.adjusted(-3.0, -3.0, 3.0, 3.0))
+    painter.setPen(QPen(QColor(border), _CHECKBOX_BORDER_WIDTH))
+    painter.setBrush(QColor(fill))
+    painter.drawEllipse(rect)
+    if checked:
+        path = QPainterPath()
+        path.moveTo(rect.left() + 9.0, rect.center().y())
+        path.lineTo(rect.left() + 15.0, rect.bottom() - 10.0)
+        path.lineTo(rect.right() - 8.0, rect.top() + 10.0)
+        pen = QPen(QColor(mark), 3.0)
+        pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        pen.setJoinStyle(Qt.PenJoinStyle.RoundJoin)
+        painter.setPen(pen)
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.drawPath(path)
+    elif partial:
+        pen = QPen(QColor(mark), 3.0)
+        pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        painter.setPen(pen)
+        painter.drawLine(
+            QLineF(
+                rect.left() + 9.0,
+                rect.center().y(),
+                rect.right() - 9.0,
+                rect.center().y(),
+            )
+        )
+    painter.restore()
+
+
+def handle_library_card_check_event(
+    event: QEvent,
+    model: QAbstractItemModel,
+    option: QStyleOptionViewItem,
+    index: QModelIndex | QPersistentModelIndex,
+    typography: TypographyTokens,
+    *,
+    checkbox_only: bool = True,
+) -> bool:
+    if not index.flags() & Qt.ItemFlag.ItemIsUserCheckable:
+        return False
+    activate = False
+    if isinstance(event, QMouseEvent):
+        hit_rect = (
+            library_card_checkbox_rect(option, typography)
+            if checkbox_only
+            else library_card_rect(option, typography)
+        )
+        activate = (
+            event.type() is QEvent.Type.MouseButtonRelease
+            and event.button() is Qt.MouseButton.LeftButton
+            and hit_rect.contains(event.position())
+        )
+    elif isinstance(event, QKeyEvent):
+        activate = event.type() is QEvent.Type.KeyPress and event.key() in {
+            Qt.Key.Key_Space,
+            Qt.Key.Key_Select,
+        }
+    if not activate:
+        return False
+    state = index.data(Qt.ItemDataRole.CheckStateRole)
+    next_state = (
+        Qt.CheckState.Unchecked
+        if state == Qt.CheckState.Checked
+        else Qt.CheckState.Checked
+    )
+    return model.setData(index, next_state, Qt.ItemDataRole.CheckStateRole)
+
+
+__all__ = [
+    "handle_library_card_check_event",
+    "library_card_checkbox_rect",
+    "paint_library_card_checkbox",
+]

iOpenPod/GUI/presentation/theme/backup_styles.py

@@ -0,0 +1,84 @@
+"""Semantic Qt styles for the Backup Snapshot browser."""
+
+from iOpenPod.GUI.presentation.theme.tokens import (
+    LAYOUT,
+    ThemeTokens,
+    TypographyTokens,
+)
+
+
+def render_backup_page_style(
+    tokens: ThemeTokens,
+    typography: TypographyTokens,
+) -> str:
+    """Render the archive browser using the application theme contract."""
+
+    return f"""/* Hallmark · macrostructure: Saved backup list · genre: quiet desktop utility
+ * pre-emit critique: P4 H5 E4 S5 R5 V4 · theme: iOpenPod semantic
+ * design-system: docs/gui-design-language.md
+ * structure: iPod source list · device context · compact cards with optional details
+ */
+QWidget#backupsPage,
+QWidget#backupBrowserPage,
+QWidget#backupEmptyPage,
+QWidget#backupDetail,
+QWidget#backupSnapshotHost {{
+    color: {tokens.text};
+    background-color: {tokens.window};
+}}
+QFrame#backupRecoveryBanner {{
+    color: {tokens.text};
+    background-color: {tokens.surface_selected};
+    border: none;
+    border-bottom: 1px solid {tokens.warning};
+}}
+QLabel#backupRecoveryText {{
+    color: {tokens.text};
+    font-weight: 600;
+}}
+QLabel#backupDeviceName,
+QLabel#backupEmptyTitle {{
+    color: {tokens.text};
+    font-family: "{typography.display}";
+    font-size: {typography.title_pt:g}pt;
+    font-weight: 700;
+}}
+QLabel#backupDeviceModel,
+QLabel#backupDeviceSummary,
+QLabel#backupSnapshotsCount,
+QLabel#backupSnapshotSummary,
+QLabel#backupProgressFile,
+QLabel#backupEmptyDetail,
+QLabel#backupArchiveEmpty {{
+    color: {tokens.text_secondary};
+}}
+QFrame#backupHero {{
+    color: {tokens.text};
+    background-color: {tokens.surface};
+    border-bottom: 1px solid {tokens.border};
+}}
+QLabel#backupSnapshotsLabel,
+QLabel#backupSnapshotDate,
+QLabel#backupProgressTitle {{
+    color: {tokens.text};
+    font-family: "{typography.display}";
+    font-size: {typography.heading_pt:g}pt;
+    font-weight: 700;
+}}
+QFrame#backupSnapshotCard,
+QFrame#backupProgressPanel {{
+    color: {tokens.text};
+    background-color: {tokens.surface};
+    border: 1px solid {tokens.border};
+    border-radius: {LAYOUT.radius_panel}px;
+}}
+QLabel#backupSnapshotNote {{
+    color: {tokens.text};
+}}
+QLabel#backupSnapshotInvalid {{
+    color: {tokens.danger};
+}}
+"""
+
+
+__all__ = ["render_backup_page_style"]