verdiclip 0.2.0__py3-none-any.whl

verdiclip/__init__.py

@@ -0,0 +1,23 @@
+"""VerdiClip: fast, faithful screenshot capture and annotation for Windows."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Final
+
+APP_NAME: Final = "VerdiClip"
+
+
+class _Version:
+    """Read the installed version; pyproject.toml is the single source."""
+
+    @staticmethod
+    def installed() -> str:
+        """Return the package version, or a placeholder when not installed."""
+        try:
+            return version("verdiclip")
+        except PackageNotFoundError:
+            return "0.0.0+unknown"
+
+
+VERSION: Final = _Version.installed()

verdiclip/__main__.py

@@ -0,0 +1,163 @@
+"""Application entry point: tray app, headless capture, or open-in-editor."""
+
+from __future__ import annotations
+
+import logging
+import signal
+import sys
+import time
+from collections.abc import Sequence
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from types import FrameType
+from typing import Final
+
+from PySide6.QtCore import QTimer
+from PySide6.QtWidgets import QApplication
+
+from verdiclip import APP_NAME, VERSION
+from verdiclip.capture.grabber import MssScreenSource
+from verdiclip.cli import CliRequest, Command, CommandLine, HeadlessMode
+from verdiclip.exceptions import AppError, CaptureError
+from verdiclip.output.delivery import ImageDelivery
+from verdiclip.platform.hotkeys import HotkeyService
+from verdiclip.platform.startup import StartupRegistration
+from verdiclip.platform.windows import WindowLocator
+from verdiclip.settings import SettingsStore
+from verdiclip.shell.controller import AppController
+from verdiclip.shell.instance import SingleInstance
+
+logger = logging.getLogger(__name__)
+
+SIGNAL_POLL_MS: Final = 200
+LOG_BYTES: Final = 2 * 1024 * 1024
+
+
+class Application:
+    """Wire settings, logging, and services, then run the requested command."""
+
+    def __init__(self) -> None:
+        self._signal_timer: QTimer | None = None
+
+    @classmethod
+    def main(cls, argv: Sequence[str] | None = None) -> None:
+        """Run and exit with the resulting status code."""
+        sys.exit(cls().run(argv))
+
+    def run(self, argv: Sequence[str] | None = None) -> int:
+        """Run once and return a process exit code."""
+        request = CommandLine().parse(argv)
+        store = SettingsStore(SettingsStore.default_path())
+        self._configure_logging(request.log_level, store.path.parent / "logs")
+        try:
+            if request.command is Command.CAPTURE:
+                return self._run_capture(request, store)
+            return self._run_gui(request, store)
+        except AppError:
+            logger.exception("%s failed", APP_NAME)
+            return 1
+        except KeyboardInterrupt:
+            return 130
+
+    # Commands
+
+    def _run_gui(self, request: CliRequest, store: SettingsStore) -> int:
+        """Run the tray app, or forward to the one already running."""
+        app = QApplication.instance() or QApplication(sys.argv[:1])
+        if not isinstance(app, QApplication):
+            msg = "A non-widget Qt application is already running"
+            raise AppError(msg)
+        app.setApplicationName(APP_NAME)
+        app.setApplicationVersion(VERSION)
+        app.setQuitOnLastWindowClosed(False)
+        files = [str(p.resolve()) for p in request.files]
+        instance = SingleInstance()
+        if instance.forward(files):
+            logger.info("Forwarded to the running instance")
+            return 0
+        instance.listen()
+        controller = AppController(
+            store,
+            MssScreenSource(),
+            WindowLocator(),
+            HotkeyService(),
+            StartupRegistration(),
+        )
+        instance.message_received.connect(controller.handle_forwarded)
+        app.aboutToQuit.connect(controller.shutdown)
+        app.aboutToQuit.connect(instance.close)
+        self._install_sigint(app)
+        controller.start()
+        for path in request.files:
+            controller.open_image(path)
+        return app.exec()
+
+    def _run_capture(self, request: CliRequest, store: SettingsStore) -> int:
+        """Capture without UI, then save or copy."""
+        app = QApplication.instance() or QApplication(sys.argv[:1])
+        del app
+        if request.delay:
+            time.sleep(request.delay)
+        frozen = MssScreenSource().freeze()
+        if request.mode is HeadlessMode.SCREEN:
+            image = frozen.image
+        elif request.mode is HeadlessMode.REGION and request.region is not None:
+            image = frozen.crop(request.region)
+        else:
+            window = WindowLocator().foreground()
+            if window is None:
+                msg = "There is no active window to capture"
+                raise CaptureError(msg)
+            image = frozen.crop(window.bounds)
+        delivery = ImageDelivery(store.load().output)
+        if request.to_clipboard:
+            delivery.copy(image)
+            sys.stdout.write("Copied to clipboard\n")
+            return 0
+        path = request.output or delivery.auto_path()
+        sys.stdout.write(f"{delivery.save(image, path)}\n")
+        return 0
+
+    # Infrastructure
+
+    def _install_sigint(self, app: QApplication) -> None:
+        """Let Ctrl+C in the terminal quit promptly (UX-TRY-05)."""
+
+        def on_sigint(_signum: int, _frame: FrameType | None) -> None:
+            logger.info("Interrupted; quitting")
+            app.quit()
+
+        signal.signal(signal.SIGINT, on_sigint)
+        # Qt's event loop blocks Python signal handling; wake it periodically
+        timer = QTimer()
+        timer.timeout.connect(lambda: None)
+        timer.start(SIGNAL_POLL_MS)
+        self._signal_timer = timer
+
+    @staticmethod
+    def _configure_logging(level: str, log_dir: Path) -> None:
+        """Log to stderr and to a rotating file under the settings folder."""
+        handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+        try:
+            log_dir.mkdir(parents=True, exist_ok=True)
+            handlers.append(
+                RotatingFileHandler(
+                    log_dir / "verdiclip.log",
+                    maxBytes=LOG_BYTES,
+                    backupCount=2,
+                    encoding="utf-8",
+                )
+            )
+        except OSError as err:
+            sys.stderr.write(f"File logging disabled: {err}\n")
+        logging.basicConfig(
+            level=level,
+            format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+            datefmt="%Y-%m-%dT%H:%M:%S",
+            handlers=handlers,
+            force=True,
+        )
+
+
+if __name__ == "__main__":
+    Application.main()

verdiclip/capture/__init__.py

@@ -0,0 +1,3 @@
+"""Screen capture: freezing, selection overlay, and capture modes."""
+
+from __future__ import annotations

verdiclip/capture/grabber.py

@@ -0,0 +1,91 @@
+"""Grab screen pixels at physical resolution with mss."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Protocol
+
+import mss
+from PySide6.QtGui import QImage
+
+from verdiclip.exceptions import CaptureError
+from verdiclip.geometry import Rect
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class FrozenScreen:
+    """A snapshot of the whole virtual desktop.
+
+    ``bounds`` is the desktop rectangle in physical pixels; ``image`` pixel
+    (0, 0) corresponds to ``bounds.top_left``.
+    """
+
+    image: QImage
+    bounds: Rect
+
+    def crop(self, area: Rect) -> QImage:
+        """Return the pixels of ``area`` (physical desktop coordinates).
+
+        Raises:
+            CaptureError: If ``area`` does not overlap the desktop.
+        """
+        clipped = area.rounded().intersected(self.bounds)
+        if clipped.is_empty:
+            msg = f"Area {area} is outside the desktop {self.bounds}"
+            raise CaptureError(msg)
+        return self.image.copy(
+            int(clipped.x - self.bounds.x),
+            int(clipped.y - self.bounds.y),
+            int(clipped.width),
+            int(clipped.height),
+        )
+
+
+class ScreenSource(Protocol):
+    """Anything that can snapshot the desktop."""
+
+    def freeze(self) -> FrozenScreen:
+        """Return a snapshot of every monitor."""
+
+
+class MssScreenSource:
+    """Snapshot the desktop with mss (physical pixels, all monitors).
+
+    The mss handle is created on first use and reused; call from the GUI thread.
+    """
+
+    def __init__(self) -> None:
+        self._grabber: mss.MSS | None = None
+
+    def freeze(self) -> FrozenScreen:
+        """Return a snapshot of every monitor.
+
+        Raises:
+            CaptureError: If the screen cannot be read.
+        """
+        try:
+            if self._grabber is None:
+                self._grabber = mss.MSS()
+            desktop = self._grabber.monitors[0]
+            shot = self._grabber.grab(desktop)
+        except mss.ScreenShotError as err:
+            self.close()
+            msg = f"Could not capture the screen: {err}"
+            raise CaptureError(msg) from err
+        width, height = shot.width, shot.height
+        # Raw BGRA bytes are exactly QImage's little-endian RGB32 layout
+        image = QImage(
+            shot.raw, width, height, width * 4, QImage.Format.Format_RGB32
+        ).copy()
+        bounds = Rect(desktop["left"], desktop["top"], width, height)
+        logger.debug("Froze desktop %s", bounds)
+        return FrozenScreen(image=image, bounds=bounds)
+
+    def close(self) -> None:
+        """Release the mss handle."""
+        if self._grabber is not None:
+            self._grabber.close()
+            self._grabber = None

verdiclip/capture/models.py

@@ -0,0 +1,98 @@
+"""Capture results and the screen layout they are taken from."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Self
+
+from PySide6.QtGui import QGuiApplication, QImage, QScreen
+
+from verdiclip.geometry import Point, Rect
+
+
+class CaptureMode(StrEnum):
+    """How a capture was taken."""
+
+    REGION = "region"
+    WINDOW = "window"
+    FULLSCREEN = "fullscreen"
+
+
+@dataclass(frozen=True, slots=True)
+class Capture:
+    """A captured image and where it came from.
+
+    ``area`` is in physical virtual-desktop pixels so it can be re-captured.
+    """
+
+    image: QImage
+    mode: CaptureMode
+    area: Rect
+    title: str
+    taken_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ScreenGeometry:
+    """One monitor in both Qt logical and physical pixel coordinates."""
+
+    name: str
+    logical: Rect
+    physical: Rect
+    scale: float
+
+    @classmethod
+    def from_screen(cls, screen: QScreen) -> Self:
+        """Describe ``screen``.
+
+        Qt on Windows keeps each screen's top-left at its native (physical)
+        position and scales only the size, so physical size = logical size * scale.
+        """
+        geo = screen.geometry()
+        scale = screen.devicePixelRatio()
+        return cls(
+            name=screen.name(),
+            logical=Rect(geo.x(), geo.y(), geo.width(), geo.height()),
+            physical=Rect(
+                geo.x(),
+                geo.y(),
+                round(geo.width() * scale),
+                round(geo.height() * scale),
+            ),
+            scale=scale,
+        )
+
+    def to_physical(self, local: Point) -> Point:
+        """Map a widget-local logical point on this screen to physical pixels."""
+        return Point(
+            self.physical.x + local.x * self.scale,
+            self.physical.y + local.y * self.scale,
+        )
+
+    def to_local(self, physical: Point) -> Point:
+        """Map a physical point to widget-local logical coordinates."""
+        return Point(
+            (physical.x - self.physical.x) / self.scale,
+            (physical.y - self.physical.y) / self.scale,
+        )
+
+    def local_rect(self, physical: Rect) -> Rect:
+        """Map a physical rectangle to widget-local logical coordinates."""
+        top_left = self.to_local(physical.top_left)
+        return Rect(
+            top_left.x,
+            top_left.y,
+            physical.width / self.scale,
+            physical.height / self.scale,
+        )
+
+
+class ScreenLayout:
+    """The monitors currently attached."""
+
+    @staticmethod
+    def current() -> list[ScreenGeometry]:
+        """Return every screen known to Qt."""
+        return [ScreenGeometry.from_screen(s) for s in QGuiApplication.screens()]

verdiclip/capture/overlay.py

@@ -0,0 +1,322 @@
+"""Full-screen overlay on one monitor: drag a region or click a window."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Final, Protocol, override
+
+from PySide6.QtCore import QEvent, QPoint, QPointF, QRectF, Qt, Signal
+from PySide6.QtGui import (
+    QColor,
+    QCursor,
+    QFont,
+    QImage,
+    QKeyEvent,
+    QMouseEvent,
+    QPainter,
+    QPaintEvent,
+    QPen,
+    QScreen,
+)
+from PySide6.QtWidgets import QWidget
+
+from verdiclip.capture.grabber import FrozenScreen
+from verdiclip.capture.models import ScreenGeometry
+from verdiclip.geometry import Point, Rect
+
+DRAG_THRESHOLD: Final = 3.0
+MAGNIFIER_SOURCE_PX: Final = 30
+MAGNIFIER_ZOOM: Final = 4
+MAGNIFIER_OFFSET: Final = 24
+DIM: Final = QColor(0, 0, 0, 110)
+ACCENT: Final = QColor(0, 120, 215)
+
+
+class WindowTarget(Protocol):
+    """A window the user can click to capture."""
+
+    @property
+    def title(self) -> str:
+        """Window title."""
+
+    @property
+    def bounds(self) -> Rect:
+        """Window rectangle in physical desktop pixels."""
+
+
+class SelectionOverlay(QWidget):
+    """Shows the frozen screen of one monitor and reports the user's choice."""
+
+    region_chosen = Signal(object)  # Rect (physical)
+    window_chosen = Signal(object, str)  # Rect (physical), title
+    cancelled = Signal()
+
+    def __init__(
+        self,
+        geometry: ScreenGeometry,
+        screen: QScreen,
+        frozen: FrozenScreen,
+        windows: Sequence[WindowTarget],
+        *,
+        show_magnifier: bool,
+    ) -> None:
+        super().__init__(None)
+        self._geometry = geometry
+        self._frozen = frozen
+        self._image = frozen.crop(geometry.physical)
+        self._image.setDevicePixelRatio(geometry.scale)
+        self._windows = [w for w in windows if w.bounds.intersects(geometry.physical)]
+        self._show_magnifier = show_magnifier
+        self._press: Point | None = None
+        self._cursor: Point | None = None
+        self._dragging = False
+        self.setWindowFlags(
+            Qt.WindowType.FramelessWindowHint
+            | Qt.WindowType.WindowStaysOnTopHint
+            | Qt.WindowType.Tool
+        )
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+        self.setMouseTracking(True)
+        self.setCursor(Qt.CursorShape.CrossCursor)
+        self.setScreen(screen)
+        logical = geometry.logical
+        self.setGeometry(
+            int(logical.x), int(logical.y), int(logical.width), int(logical.height)
+        )
+
+    @property
+    def screen_geometry(self) -> ScreenGeometry:
+        """Return the monitor this overlay covers."""
+        return self._geometry
+
+    def hovered_window(self) -> WindowTarget | None:
+        """Return the topmost window under the cursor, if any."""
+        if self._cursor is None:
+            return None
+        physical = self._geometry.to_physical(self._cursor)
+        return next((w for w in self._windows if w.bounds.contains(physical)), None)
+
+    def selection(self) -> Rect | None:
+        """Return the dragged rectangle in local logical coordinates."""
+        if not self._dragging or self._press is None or self._cursor is None:
+            return None
+        return Rect.from_points(self._press, self._clamped(self._cursor))
+
+    # Painting
+
+    @override
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Draw the frozen screen, dimming, highlight, crosshair, and magnifier."""
+        del event
+        painter = QPainter(self)
+        try:
+            painter.drawImage(QPointF(0, 0), self._image)
+            painter.fillRect(self.rect(), DIM)
+            self._paint_target(painter)
+            self._paint_crosshair(painter)
+            if self._show_magnifier and self._cursor is not None:
+                self._paint_magnifier(painter, self._cursor)
+        finally:
+            painter.end()
+
+    def _paint_target(self, painter: QPainter) -> None:
+        """Highlight the dragged region or the hovered window."""
+        selection = self.selection()
+        if selection is not None:
+            size = self._physical_rect(selection)
+            self._reveal(painter, selection, f"{int(size.width)} × {int(size.height)}")  # noqa: RUF001
+            return
+        window = self.hovered_window()
+        if window is not None:
+            local = self._geometry.local_rect(window.bounds)
+            self._reveal(painter, local, window.title)
+
+    def _reveal(self, painter: QPainter, area: Rect, label: str) -> None:
+        """Undim ``area``, outline it, and show ``label`` beside it."""
+        rect = QRectF(area.x, area.y, area.width, area.height)
+        painter.drawImage(
+            rect,
+            self._image,
+            QRectF(
+                area.x * self._geometry.scale,
+                area.y * self._geometry.scale,
+                area.width * self._geometry.scale,
+                area.height * self._geometry.scale,
+            ),
+        )
+        painter.setPen(QPen(ACCENT, 2))
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.drawRect(rect)
+        font = QFont("Segoe UI")
+        font.setPixelSize(13)
+        painter.setFont(font)
+        metrics = painter.fontMetrics()
+        text = metrics.elidedText(label, Qt.TextElideMode.ElideRight, 480)
+        box = QRectF(0, 0, metrics.horizontalAdvance(text) + 12, metrics.height() + 6)
+        above = area.y - box.height() - 4
+        box.moveTo(max(0.0, area.x), above if above >= 0 else area.bottom + 4)
+        painter.fillRect(box, QColor(20, 20, 20, 220))
+        painter.setPen(Qt.GlobalColor.white)
+        painter.drawText(box, int(Qt.AlignmentFlag.AlignCenter.value), text)
+
+    def _paint_crosshair(self, painter: QPainter) -> None:
+        """Draw guide lines through the cursor."""
+        if self._cursor is None or self._dragging:
+            return
+        painter.setPen(QPen(QColor(255, 255, 255, 140), 1, Qt.PenStyle.DashLine))
+        x, y = round(self._cursor.x), round(self._cursor.y)
+        painter.drawLine(x, 0, x, self.height())
+        painter.drawLine(0, y, self.width(), y)
+
+    def _paint_magnifier(self, painter: QPainter, cursor: Point) -> None:
+        """Draw a 4x loupe of the pixels around the cursor (UX-CAP-06)."""
+        physical = self._geometry.to_physical(cursor)
+        half = MAGNIFIER_SOURCE_PX // 2
+        source = Rect(
+            round(physical.x) - half,
+            round(physical.y) - half,
+            MAGNIFIER_SOURCE_PX,
+            MAGNIFIER_SOURCE_PX,
+        )
+        patch = self._patch(source)
+        size = MAGNIFIER_SOURCE_PX * MAGNIFIER_ZOOM
+        x = cursor.x + MAGNIFIER_OFFSET
+        y = cursor.y + MAGNIFIER_OFFSET
+        if x + size > self.width():
+            x = cursor.x - MAGNIFIER_OFFSET - size
+        if y + size + 20 > self.height():
+            y = cursor.y - MAGNIFIER_OFFSET - size - 20
+        target = QRectF(x, y, size, size)
+        painter.save()
+        painter.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform, on=False)
+        painter.drawImage(target, patch)
+        painter.restore()
+        # Dark outer and light inner edge so the loupe reads on any content
+        painter.setPen(QPen(QColor(20, 20, 20, 230), 1))
+        painter.drawRect(target.adjusted(-2, -2, 2, 2))
+        painter.setPen(QPen(Qt.GlobalColor.white, 2))
+        painter.drawRect(target)
+        center = target.center()
+        painter.setPen(QPen(QColor(255, 0, 0, 200), 1))
+        painter.drawLine(
+            QPointF(center.x() - 8, center.y()), QPointF(center.x() + 8, center.y())
+        )
+        painter.drawLine(
+            QPointF(center.x(), center.y() - 8), QPointF(center.x(), center.y() + 8)
+        )
+        coords = QRectF(x, y + size, size, 20)
+        painter.fillRect(coords, QColor(20, 20, 20, 220))
+        painter.setPen(Qt.GlobalColor.white)
+        label = f"{int(physical.x)}, {int(physical.y)}"
+        painter.drawText(coords, int(Qt.AlignmentFlag.AlignCenter.value), label)
+
+    def _patch(self, source: Rect) -> QImage:
+        """Return ``source`` pixels from the frozen desktop, black outside it."""
+        patch = QImage(
+            int(source.width), int(source.height), QImage.Format.Format_RGB32
+        )
+        patch.fill(Qt.GlobalColor.black)
+        inside = source.intersected(self._frozen.bounds)
+        if not inside.is_empty:
+            painter = QPainter(patch)
+            painter.drawImage(
+                QPointF(inside.x - source.x, inside.y - source.y),
+                self._frozen.crop(inside),
+            )
+            painter.end()
+        return patch
+
+    # Input
+
+    @override
+    def mousePressEvent(self, event: QMouseEvent) -> None:
+        """Start a selection on left press; cancel on right press."""
+        if event.button() == Qt.MouseButton.RightButton:
+            self.cancelled.emit()
+            return
+        if event.button() == Qt.MouseButton.LeftButton:
+            self._press = self._local(event)
+            self._cursor = self._press
+            self._dragging = False
+
+    @override
+    def mouseMoveEvent(self, event: QMouseEvent) -> None:
+        """Track the cursor and start dragging past the threshold."""
+        self._cursor = self._local(event)
+        if (
+            self._press is not None
+            and self._press.distance_to(self._cursor) >= DRAG_THRESHOLD
+        ):
+            self._dragging = True
+        self.update()
+
+    @override
+    def mouseReleaseEvent(self, event: QMouseEvent) -> None:
+        """Report a dragged region, a clicked window, or this whole monitor."""
+        if event.button() != Qt.MouseButton.LeftButton or self._press is None:
+            return
+        self._cursor = self._local(event)
+        selection = self.selection()
+        self._press = None
+        self._dragging = False
+        if selection is not None:
+            area = self._physical_rect(selection)
+            if area.width >= DRAG_THRESHOLD and area.height >= DRAG_THRESHOLD:
+                self.region_chosen.emit(area)
+            self.update()
+            return
+        window = self.hovered_window()
+        if window is not None:
+            self.window_chosen.emit(
+                window.bounds.intersected(self._frozen.bounds), window.title
+            )
+        else:
+            self.region_chosen.emit(self._geometry.physical)
+
+    @override
+    def keyPressEvent(self, event: QKeyEvent) -> None:
+        """Cancel on Esc; move the cursor with arrow keys (Ctrl = 10 px)."""
+        if event.key() == Qt.Key.Key_Escape:
+            self.cancelled.emit()
+            return
+        step = 10 if event.modifiers() & Qt.KeyboardModifier.ControlModifier else 1
+        moves = {
+            Qt.Key.Key_Left: QPoint(-step, 0),
+            Qt.Key.Key_Right: QPoint(step, 0),
+            Qt.Key.Key_Up: QPoint(0, -step),
+            Qt.Key.Key_Down: QPoint(0, step),
+        }
+        delta = moves.get(Qt.Key(event.key()))
+        if delta is None:
+            super().keyPressEvent(event)
+            return
+        QCursor.setPos(QCursor.pos() + delta)
+
+    @override
+    def leaveEvent(self, event: QEvent) -> None:
+        """Hide the crosshair when the cursor moves to another monitor."""
+        del event
+        if self._press is None:
+            self._cursor = None
+            self.update()
+
+    # Internals
+
+    @staticmethod
+    def _local(event: QMouseEvent) -> Point:
+        """Return the event position in local logical coordinates."""
+        pos = event.position()
+        return Point(pos.x(), pos.y())
+
+    def _clamped(self, point: Point) -> Point:
+        """Clamp ``point`` to this overlay."""
+        return Point(
+            min(max(point.x, 0.0), float(self.width())),
+            min(max(point.y, 0.0), float(self.height())),
+        )
+
+    def _physical_rect(self, local: Rect) -> Rect:
+        """Map a local logical rectangle to whole physical pixels."""
+        a = self._geometry.to_physical(local.top_left)
+        b = self._geometry.to_physical(local.bottom_right)
+        return Rect.from_points(a, b).rounded()