pyvisionauto 0.1.0__py3-none-any.whl

pyvisionauto/__init__.py

@@ -0,0 +1,36 @@
+from .config import DEFAULT_CONFIDENCE, DEFAULT_POLL_INTERVAL
+from .envcheck import EnvCheck
+from .errors import (
+    EnvironmentNotSupportedError,
+    OverlayError,
+    PyVisionAutoError,
+    RecorderError,
+    TemplateNotFoundError,
+    VanishTimeoutError,
+    WaitTimeoutError,
+)
+from .highlighter import Highlighter
+from .input import Input
+from .models import EnvironmentReport, Match, TimingProfile
+from .recorder import Recorder
+from .screen import Screen
+
+__all__ = [
+    "DEFAULT_CONFIDENCE",
+    "DEFAULT_POLL_INTERVAL",
+    "EnvCheck",
+    "EnvironmentNotSupportedError",
+    "EnvironmentReport",
+    "Highlighter",
+    "Input",
+    "Match",
+    "OverlayError",
+    "PyVisionAutoError",
+    "Recorder",
+    "RecorderError",
+    "Screen",
+    "TemplateNotFoundError",
+    "TimingProfile",
+    "VanishTimeoutError",
+    "WaitTimeoutError",
+]

pyvisionauto/config.py

@@ -0,0 +1,23 @@
+from .models import TimingProfile
+
+DEFAULT_CONFIDENCE = 0.88
+DEFAULT_POLL_INTERVAL = 0.5
+
+HIGHLIGHT_ENABLED = True
+HIGHLIGHT_COLOR = "#ff0000"
+HIGHLIGHT_THICKNESS = 3
+HIGHLIGHT_DURATION_MS = 700
+
+DEFAULT_TIMING = TimingProfile(
+    typing_delay_min=0.04,
+    typing_delay_max=0.12,
+    special_char_extra_delay=0.03,
+    key_press_delay_min=0.01,
+    key_press_delay_max=0.04,
+    key_post_delay_min=0.03,
+    key_post_delay_max=0.08,
+    hotkey_gap_min=0.02,
+    hotkey_gap_max=0.06,
+    human_like_default=True,
+    deterministic_mode=False,
+)

pyvisionauto/envcheck.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+
+from .errors import EnvironmentNotSupportedError
+from .models import EnvironmentReport
+
+
+class EnvCheck:
+    """Validate runtime prerequisites for PyVisionAuto on Linux desktops."""
+
+    def check(self, strict: bool = True) -> EnvironmentReport:
+        """Run platform and dependency checks.
+
+        Args:
+            strict: If ``True``, raise when environment is not supported.
+
+        Returns:
+            Structured environment report.
+
+        Raises:
+            EnvironmentNotSupportedError: If ``strict=True`` and checks fail.
+        """
+        is_linux = platform.system().lower() == "linux"
+        has_display = bool(os.environ.get("DISPLAY"))
+
+        x11_ok = False
+        if has_display:
+            try:
+                out = subprocess.run(
+                    ["sh", "-lc", "echo ${XDG_SESSION_TYPE:-unknown}"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                x11_ok = out.stdout.strip().lower() in {"x11", "unknown"}
+            except Exception:
+                x11_ok = False
+
+        tk_ok = True
+        try:
+            import tkinter  # noqa: F401
+        except Exception:
+            tk_ok = False
+
+        xdotool_ok = shutil.which("xdotool") is not None
+        wmctrl_ok = shutil.which("wmctrl") is not None
+        ibus_ok = shutil.which("ibus") is not None
+        ffmpeg_ok = shutil.which("ffmpeg") is not None
+
+        messages: list[str] = []
+        if not is_linux:
+            messages.append("Only Linux is supported in v0.1")
+        if not has_display:
+            messages.append("DISPLAY is missing")
+        if not x11_ok:
+            messages.append("X11 session not detected")
+        if not tk_ok:
+            messages.append("tkinter is unavailable (install python3-tk)")
+        if not (xdotool_ok or wmctrl_ok):
+            messages.append("Neither xdotool nor wmctrl is installed")
+
+        supported = is_linux and has_display and x11_ok and tk_ok and (xdotool_ok or wmctrl_ok)
+        report = EnvironmentReport(
+            is_supported=supported,
+            platform_ok=is_linux,
+            display_ok=has_display,
+            x11_ok=x11_ok,
+            tk_ok=tk_ok,
+            xdotool_ok=xdotool_ok,
+            wmctrl_ok=wmctrl_ok,
+            ibus_ok=ibus_ok,
+            ffmpeg_ok=ffmpeg_ok,
+            messages=messages,
+        )
+
+        if strict and not report.is_supported:
+            raise EnvironmentNotSupportedError("; ".join(report.messages) or "Unsupported environment")
+        return report
+
+
+def check_env(strict: bool = True) -> EnvironmentReport:
+    """Convenience wrapper for :meth:`EnvCheck.check`."""
+    return EnvCheck().check(strict=strict)

pyvisionauto/errors.py

@@ -0,0 +1,26 @@
+class PyVisionAutoError(Exception):
+    """Base exception for PyVisionAuto."""
+
+
+class TemplateNotFoundError(PyVisionAutoError):
+    """Raised when an image template file path does not exist."""
+
+
+class WaitTimeoutError(PyVisionAutoError):
+    """Raised when waiting for a match times out."""
+
+
+class VanishTimeoutError(PyVisionAutoError):
+    """Raised when waiting for an image to vanish times out."""
+
+
+class EnvironmentNotSupportedError(PyVisionAutoError):
+    """Raised when runtime prerequisites are not met."""
+
+
+class OverlayError(PyVisionAutoError):
+    """Raised when highlight overlay cannot be rendered."""
+
+
+class RecorderError(PyVisionAutoError):
+    """Raised when recording actions fail."""

pyvisionauto/highlighter.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import HIGHLIGHT_COLOR, HIGHLIGHT_DURATION_MS, HIGHLIGHT_THICKNESS
+from .errors import OverlayError
+from .models import Match
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Highlighter:
+    """Overlay helper used to draw temporary highlight borders for matches."""
+
+    def __init__(self) -> None:
+        """Initialize overlay script path."""
+        self._overlay_script = Path(__file__).with_name("overlay.py")
+
+    def show(
+        self,
+        match: Match,
+        duration_ms: int | None = None,
+        color: str | None = None,
+        thickness: int | None = None,
+    ) -> None:
+        """Spawn overlay process to highlight one match rectangle.
+
+        Args:
+            match: Match rectangle to visualize.
+            duration_ms: Overlay lifetime in milliseconds. ``None`` uses default.
+            color: Border color. ``None`` uses default.
+            thickness: Border width in pixels. ``None`` uses default.
+
+        Raises:
+            OverlayError: If the overlay process cannot be started.
+        """
+        resolved_duration = duration_ms if duration_ms is not None else HIGHLIGHT_DURATION_MS
+        resolved_color = color if color is not None else HIGHLIGHT_COLOR
+        resolved_thickness = thickness if thickness is not None else HIGHLIGHT_THICKNESS
+
+        try:
+            subprocess.Popen(
+                [
+                    sys.executable,
+                    str(self._overlay_script),
+                    str(match.x),
+                    str(match.y),
+                    str(match.w),
+                    str(match.h),
+                    str(resolved_duration),
+                    resolved_color,
+                    str(resolved_thickness),
+                ],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except Exception as exc:  # pragma: no cover
+            raise OverlayError(str(exc)) from exc
+
+    def safe_show(
+        self,
+        match: Match,
+        duration_ms: int | None = None,
+        color: str | None = None,
+        thickness: int | None = None,
+    ) -> None:
+        """Best-effort highlight wrapper that never interrupts user actions."""
+        try:
+            self.show(match, duration_ms=duration_ms, color=color, thickness=thickness)
+        except OverlayError as exc:
+            LOGGER.warning("Highlight failed but action continues: %s", exc)

pyvisionauto/input.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import importlib
+import random
+import time
+
+from .config import DEFAULT_TIMING
+from .models import TimingProfile
+
+
+class Input:
+    """Keyboard text/input helper with optional human-like timing behavior."""
+
+    def __init__(self, timing: TimingProfile | None = None, deterministic: bool | None = None) -> None:
+        """Create input helper.
+
+        Args:
+            timing: Timing profile. ``None`` uses ``DEFAULT_TIMING``.
+            deterministic: Override deterministic mode. ``None`` follows timing profile.
+        """
+        self.timing = timing or DEFAULT_TIMING
+        self.deterministic = self.timing.deterministic_mode if deterministic is None else deterministic
+
+    def _get_pyautogui(self):
+        """Lazily import pyautogui to reduce module import constraints."""
+        return importlib.import_module("pyautogui")
+
+    def _pause(self, low: float, high: float) -> None:
+        """Sleep for a delay interval, deterministic or random based on settings."""
+        if self.deterministic:
+            time.sleep((low + high) / 2.0)
+            return
+        time.sleep(random.uniform(low, high))
+
+    def type_text(
+        self,
+        text: str,
+        human_like: bool | None = None,
+        delay_min: float | None = None,
+        delay_max: float | None = None,
+    ) -> None:
+        """Type text into the active UI control.
+
+        Args:
+            text: Text content to type.
+            human_like: Whether to use per-character delays. ``None`` uses timing default.
+            delay_min: Minimum delay between characters in seconds.
+            delay_max: Maximum delay between characters in seconds.
+        """
+        pyautogui = self._get_pyautogui()
+        use_human = self.timing.human_like_default if human_like is None else human_like
+        if not use_human:
+            pyautogui.write(text)
+            return
+
+        low = self.timing.typing_delay_min if delay_min is None else delay_min
+        high = self.timing.typing_delay_max if delay_max is None else delay_max
+
+        for ch in text:
+            pyautogui.write(ch)
+            self._pause(low, high)
+            if ch in "/-_.":
+                time.sleep(self.timing.special_char_extra_delay)
+
+    def press(self, key: str, human_like: bool | None = None) -> None:
+        """Press one key.
+
+        Args:
+            key: Key name understood by pyautogui (for example ``"enter"``).
+            human_like: Whether to apply pre/post action delays.
+        """
+        pyautogui = self._get_pyautogui()
+        use_human = self.timing.human_like_default if human_like is None else human_like
+        if use_human:
+            self._pause(self.timing.key_press_delay_min, self.timing.key_press_delay_max)
+        pyautogui.press(key)
+        if use_human:
+            self._pause(self.timing.key_post_delay_min, self.timing.key_post_delay_max)
+
+    def hotkey(self, *keys: str, human_like: bool | None = None) -> None:
+        """Send a key combination.
+
+        Args:
+            *keys: Ordered key sequence, for example ``("ctrl", "v")``.
+            human_like: Whether to apply delay between key down/up events.
+        """
+        pyautogui = self._get_pyautogui()
+        use_human = self.timing.human_like_default if human_like is None else human_like
+        if not use_human:
+            pyautogui.hotkey(*keys)
+            return
+
+        for key in keys:
+            pyautogui.keyDown(key)
+            self._pause(self.timing.hotkey_gap_min, self.timing.hotkey_gap_max)
+        for key in reversed(keys):
+            pyautogui.keyUp(key)
+            self._pause(self.timing.hotkey_gap_min, self.timing.hotkey_gap_max)
+
+    def clear_text(self) -> None:
+        """Clear active input field using Ctrl+A followed by Backspace."""
+        self.hotkey("ctrl", "a")
+        self.press("backspace")

pyvisionauto/models.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Match:
+    """Rectangle and confidence returned by template matching.
+
+    Attributes:
+        x: Absolute screen X of the matched top-left corner.
+        y: Absolute screen Y of the matched top-left corner.
+        w: Matched width in pixels.
+        h: Matched height in pixels.
+        score: Normalized confidence score in [0.0, 1.0].
+    """
+
+    x: int
+    y: int
+    w: int
+    h: int
+    score: float
+
+    @property
+    def center(self) -> tuple[int, int]:
+        """Return center point ``(x + w // 2, y + h // 2)``."""
+        return (self.x + self.w // 2, self.y + self.h // 2)
+
+
+@dataclass(frozen=True)
+class TimingProfile:
+    """Timing configuration used by :class:`pyvisionauto.input.Input`."""
+
+    typing_delay_min: float
+    typing_delay_max: float
+    special_char_extra_delay: float
+    key_press_delay_min: float
+    key_press_delay_max: float
+    key_post_delay_min: float
+    key_post_delay_max: float
+    hotkey_gap_min: float
+    hotkey_gap_max: float
+    human_like_default: bool = True
+    deterministic_mode: bool = False
+
+
+@dataclass
+class EnvironmentReport:
+    """Result container for environment compatibility checks."""
+
+    is_supported: bool
+    platform_ok: bool
+    display_ok: bool
+    x11_ok: bool
+    tk_ok: bool
+    xdotool_ok: bool
+    wmctrl_ok: bool
+    ibus_ok: bool
+    ffmpeg_ok: bool
+    messages: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Region:
+    """Search/capture rectangle in absolute screen coordinates.
+
+    Attributes:
+        x: Absolute screen X of the region top-left corner.
+        y: Absolute screen Y of the region top-left corner.
+        w: Region width in pixels.
+        h: Region height in pixels.
+    """
+
+    x: int
+    y: int
+    w: int
+    h: int

pyvisionauto/overlay.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import sys
+import tkinter as tk
+
+
+def main() -> int:
+    if len(sys.argv) != 8:
+        return 2
+
+    x = int(sys.argv[1])
+    y = int(sys.argv[2])
+    w = int(sys.argv[3])
+    h = int(sys.argv[4])
+    duration_ms = int(sys.argv[5])
+    color = sys.argv[6]
+    thickness = int(sys.argv[7])
+
+    # Keep center visually transparent by drawing border only on a canvas.
+    root = tk.Tk()
+    root.overrideredirect(True)
+    root.attributes("-topmost", True)
+    root.geometry(f"{w}x{h}+{x}+{y}")
+
+    bg = "black"
+    root.configure(bg=bg)
+    try:
+        root.wm_attributes("-transparentcolor", bg)
+    except tk.TclError:
+        # Some X11 window managers do not support transparentcolor.
+        root.attributes("-alpha", 0.35)
+
+    canvas = tk.Canvas(root, width=w, height=h, highlightthickness=0, bg=bg)
+    canvas.pack(fill="both", expand=True)
+    inset = max(1, thickness // 2)
+    canvas.create_rectangle(
+        inset,
+        inset,
+        max(inset + 1, w - inset),
+        max(inset + 1, h - inset),
+        outline=color,
+        width=thickness,
+    )
+
+    root.after(duration_ms, root.destroy)
+    root.mainloop()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyvisionauto/recorder.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .errors import RecorderError
+
+
+class Recorder:
+    """Simple ffmpeg-based screen recorder for X11 sessions."""
+
+    def __init__(self, display: str | None = None) -> None:
+        """Create recorder.
+
+        Args:
+            display: X11 display string (for example ``":0"``). ``None`` reads ``DISPLAY``.
+        """
+        self.display = display or os.environ.get("DISPLAY", ":0")
+        self._proc: subprocess.Popen[bytes] | None = None
+
+    def start(self, output_file: str | Path, fps: int = 15) -> None:
+        """Start recording the desktop.
+
+        Args:
+            output_file: Video file output path.
+            fps: Capture frame rate.
+
+        Raises:
+            RecorderError: If ffmpeg is missing or recorder is already running.
+        """
+        if shutil.which("ffmpeg") is None:
+            raise RecorderError("ffmpeg is required for recording APIs")
+        if self._proc is not None and self._proc.poll() is None:
+            raise RecorderError("Recorder is already running")
+
+        out = str(output_file)
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-video_size",
+            "1920x1080",
+            "-framerate",
+            str(fps),
+            "-f",
+            "x11grab",
+            "-i",
+            self.display,
+            out,
+        ]
+        self._proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+    def stop(self) -> None:
+        """Stop recording if active. Safe to call repeatedly."""
+        if self._proc is None:
+            return
+        if self._proc.poll() is None:
+            self._proc.terminate()
+            self._proc.wait(timeout=3)
+        self._proc = None

pyvisionauto/screen.py

@@ -0,0 +1,457 @@
+from __future__ import annotations
+
+import importlib
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .config import HIGHLIGHT_ENABLED
+from .envcheck import check_env
+from .highlighter import Highlighter
+from .input import Input
+from .models import Match, Region
+
+if TYPE_CHECKING:
+    from .vision import Vision
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _get_pyautogui():
+    """Lazily import pyautogui to keep module import cross-platform friendly."""
+    return importlib.import_module("pyautogui")
+
+
+@dataclass
+class MatchHandle:
+    """Chainable handle around a resolved image match.
+
+    A handle stores the matched rectangle and allows fluent follow-up actions
+    such as highlight, click, hover, and waiting for disappearance.
+    """
+
+    screen: "Screen"
+    image: str
+    match: Match
+    region: Region | None = None
+
+    @property
+    def center(self) -> tuple[int, int]:
+        """Return the match center in absolute screen coordinates."""
+        return self.match.center
+
+    @property
+    def score(self) -> float:
+        """Return normalized match confidence in the range [0.0, 1.0]."""
+        return self.match.score
+
+    def highlight(
+        self,
+        duration_ms: int | None = None,
+        color: str | None = None,
+        thickness: int | None = None,
+    ) -> "MatchHandle":
+        """Render a temporary highlight overlay around the current match.
+
+        Args:
+            duration_ms: Overlay lifetime in milliseconds. ``None`` uses config default.
+            color: Border color string (for example ``"#ff0000"``). ``None`` uses default.
+            thickness: Border thickness in pixels. ``None`` uses default.
+
+        Returns:
+            The current handle for method chaining.
+        """
+        self.screen._highlight_match(self.match, duration_ms=duration_ms, color=color, thickness=thickness)
+        return self
+
+    def click(self, button: str = "left", highlight: bool = True) -> "MatchHandle":
+        """Click at the current match center.
+
+        Args:
+            button: Mouse button name accepted by pyautogui (``"left"``, ``"right"``, etc.).
+            highlight: Whether to show highlight overlay before clicking.
+
+        Returns:
+            The current handle for method chaining.
+        """
+        if highlight:
+            self.highlight()
+        x, y = self.match.center
+        pyautogui = _get_pyautogui()
+        pyautogui.click(x=x, y=y, button=button)
+        return self
+
+    def double_click(self, highlight: bool = True) -> "MatchHandle":
+        """Double-click at the current match center.
+
+        Args:
+            highlight: Whether to show highlight overlay before the action.
+
+        Returns:
+            The current handle for method chaining.
+        """
+        if highlight:
+            self.highlight()
+        x, y = self.match.center
+        pyautogui = _get_pyautogui()
+        pyautogui.doubleClick(x=x, y=y)
+        return self
+
+    def right_click(self, highlight: bool = True) -> "MatchHandle":
+        """Right-click at the current match center.
+
+        Args:
+            highlight: Whether to show highlight overlay before the action.
+
+        Returns:
+            The current handle for method chaining.
+        """
+        return self.click(button="right", highlight=highlight)
+
+    def hover(self, highlight: bool = True) -> "MatchHandle":
+        """Move the pointer to the current match center.
+
+        Args:
+            highlight: Whether to show highlight overlay before pointer move.
+
+        Returns:
+            The current handle for method chaining.
+        """
+        if highlight:
+            self.highlight()
+        x, y = self.match.center
+        pyautogui = _get_pyautogui()
+        pyautogui.moveTo(x, y)
+        return self
+
+    def wait_vanish(
+        self,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        strict: bool = True,
+    ) -> bool:
+        """Wait until this handle's image is no longer detected.
+
+        Args:
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            strict: If ``True``, raise on timeout. If ``False``, return ``False``.
+
+        Returns:
+            ``True`` if vanished before timeout; ``False`` only when ``strict=False``.
+        """
+        return self.screen.wait_vanish(
+            self.image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=self.region,
+            strict=strict,
+        )
+
+
+class RegionScreen:
+    """A Screen proxy that automatically scopes all operations to one region."""
+
+    def __init__(self, screen: "Screen", region: Region) -> None:
+        self._screen = screen
+        self._region = region
+
+    def find(self, image: str | Path, confidence: float | None = None) -> MatchHandle | None:
+        """Find one image inside this pre-scoped region."""
+        return self._screen.find(image=image, confidence=confidence, region=self._region)
+
+    def wait(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+    ) -> MatchHandle:
+        """Wait for an image to appear inside this pre-scoped region."""
+        return self._screen.wait(
+            image=image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=self._region,
+        )
+
+    def click(
+        self,
+        image: str | Path,
+        timeout: float = 10,
+        confidence: float | None = None,
+        poll: float | None = None,
+        highlight: bool = True,
+    ) -> MatchHandle:
+        """Wait for and click an image inside this pre-scoped region."""
+        return self._screen.click(
+            image=image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            highlight=highlight,
+            region=self._region,
+        )
+
+    def wait_vanish(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        strict: bool = True,
+    ) -> bool:
+        """Wait for an image to disappear inside this pre-scoped region."""
+        return self._screen.wait_vanish(
+            image=image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=self._region,
+            strict=strict,
+        )
+
+
+class Screen:
+    """High-level image-driven automation API for Linux X11 desktops."""
+
+    def __init__(self) -> None:
+        from .vision import Vision
+
+        self.vision = Vision()
+        self.highlighter = Highlighter()
+        self.input = Input()
+
+    def region(self, x: int, y: int, w: int, h: int) -> RegionScreen:
+        """Create a region-scoped helper.
+
+        Args:
+            x: Absolute screen X coordinate of the region's top-left corner.
+            y: Absolute screen Y coordinate of the region's top-left corner.
+            w: Region width in pixels.
+            h: Region height in pixels.
+
+        Returns:
+            A ``RegionScreen`` instance that limits find/wait/click operations
+            to ``Region(x, y, w, h)``.
+        """
+        return RegionScreen(self, Region(x, y, w, h))
+
+    def _highlight_match(
+        self,
+        match: Match,
+        duration_ms: int | None = None,
+        color: str | None = None,
+        thickness: int | None = None,
+    ) -> None:
+        """Display a temporary highlight for one match rectangle."""
+        self.highlighter.safe_show(match, duration_ms=duration_ms, color=color, thickness=thickness)
+
+    @staticmethod
+    def _normalize_region(region: Region | tuple[int, int, int, int] | None) -> Region | None:
+        """Convert tuple region values to ``Region`` while preserving ``None``."""
+        if region is None:
+            return None
+        if isinstance(region, Region):
+            return region
+        x, y, w, h = region
+        return Region(int(x), int(y), int(w), int(h))
+
+    def find(
+        self,
+        image: str | Path,
+        confidence: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+        highlight: bool = HIGHLIGHT_ENABLED,
+    ) -> MatchHandle | None:
+        """Find an image once and return a chainable handle when matched.
+
+        Args:
+            image: Template image path.
+            confidence: Match threshold. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+            highlight: Whether to show highlight overlay when matched.
+
+        Returns:
+            ``MatchHandle`` when found, otherwise ``None``.
+        """
+        normalized_region = self._normalize_region(region)
+        match = self.vision.find(image=image, confidence=confidence, region=region)
+        if match is None:
+            return None
+        if highlight:
+            self._highlight_match(match)
+        return MatchHandle(screen=self, image=str(image), match=match, region=normalized_region)
+
+    def wait(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+        highlight: bool = HIGHLIGHT_ENABLED,
+    ) -> MatchHandle:
+        """Wait until an image appears and return a chainable handle.
+
+        Args:
+            image: Template image path.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+            highlight: Whether to show highlight overlay on success.
+
+        Returns:
+            A ``MatchHandle`` for fluent actions.
+        """
+        normalized_region = self._normalize_region(region)
+        match = self.vision.wait(image=image, timeout=timeout, confidence=confidence, poll=poll, region=region)
+        if highlight:
+            self._highlight_match(match)
+        return MatchHandle(screen=self, image=str(image), match=match, region=normalized_region)
+
+    def wait_vanish(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+        strict: bool = True,
+    ) -> bool:
+        """Wait until an image disappears from the screen or region.
+
+        Args:
+            image: Template image path.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+            strict: If ``True``, raise on timeout. If ``False``, return ``False``.
+
+        Returns:
+            ``True`` if image vanished before timeout.
+        """
+        return self.vision.wait_vanish(
+            image=image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=region,
+            strict=strict,
+        )
+
+    def click(
+        self,
+        image: str | Path,
+        timeout: float = 10,
+        confidence: float | None = None,
+        poll: float | None = None,
+        highlight: bool = HIGHLIGHT_ENABLED,
+        region: Region | tuple[int, int, int, int] | None = None,
+    ) -> MatchHandle:
+        """Wait for an image and click its center.
+
+        Args:
+            image: Template image path.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            highlight: Whether to show highlight overlay before clicking.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+
+        Returns:
+            A ``MatchHandle`` representing the clicked match.
+        """
+        handle = self.wait(
+            image=image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=region,
+            highlight=False,
+        )
+        return handle.click(highlight=highlight)
+
+    def click_and_wait_vanish(
+        self,
+        click_image: str | Path,
+        vanish_image: str | Path | None = None,
+        timeout: float = 10,
+        confidence: float | None = None,
+        poll: float | None = None,
+        highlight: bool = HIGHLIGHT_ENABLED,
+        region: Region | tuple[int, int, int, int] | None = None,
+        strict: bool = True,
+    ) -> bool:
+        """Click one image and wait for an image to disappear.
+
+        Args:
+            click_image: Image used for click targeting.
+            vanish_image: Image to monitor for disappearance. ``None`` uses ``click_image``.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            highlight: Whether to highlight before click.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+            strict: If ``True``, raise on timeout. If ``False``, return ``False``.
+
+        Returns:
+            ``True`` if the vanish target disappears before timeout.
+        """
+        self.click(
+            image=click_image,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            highlight=highlight,
+            region=region,
+        )
+        target = vanish_image if vanish_image is not None else click_image
+        return self.wait_vanish(
+            image=target,
+            timeout=timeout,
+            confidence=confidence,
+            poll=poll,
+            region=region,
+            strict=strict,
+        )
+
+    def activate_window(self, title_substring: str) -> bool:
+        """Attempt to activate a window by title fragment.
+
+        Tries ``xdotool`` first and falls back to ``wmctrl``.
+
+        Args:
+            title_substring: Case-sensitive fragment used by window manager tools.
+
+        Returns:
+            ``True`` when activation command succeeds, otherwise ``False``.
+        """
+        xdotool_cmd = ["xdotool", "search", "--name", title_substring, "windowactivate"]
+        wmctrl_cmd = ["wmctrl", "-a", title_substring]
+
+        try:
+            proc = subprocess.run(xdotool_cmd, capture_output=True, check=False)
+            if proc.returncode == 0:
+                return True
+        except FileNotFoundError:
+            LOGGER.debug("xdotool not available")
+
+        try:
+            proc = subprocess.run(wmctrl_cmd, capture_output=True, check=False)
+            return proc.returncode == 0
+        except FileNotFoundError:
+            LOGGER.debug("wmctrl not available")
+            return False
+
+    def check_env(self, strict: bool = True):
+        """Run environment checks for platform, display, and required tools."""
+        return check_env(strict=strict)

pyvisionauto/vision.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import cv2
+import mss
+import numpy as np
+
+from .config import DEFAULT_CONFIDENCE, DEFAULT_POLL_INTERVAL
+from .errors import TemplateNotFoundError, VanishTimeoutError, WaitTimeoutError
+from .models import Match, Region
+
+
+def _as_region(region: Region | tuple[int, int, int, int] | None) -> Region | None:
+    """Normalize region input into a ``Region`` instance.
+
+    Accepts either an existing ``Region`` object or a tuple ``(x, y, w, h)``.
+    """
+    if region is None:
+        return None
+    if isinstance(region, Region):
+        return region
+    x, y, w, h = region
+    return Region(int(x), int(y), int(w), int(h))
+
+
+class Vision:
+    """Low-level OpenCV template matching and polling engine."""
+
+    def __init__(self) -> None:
+        """Initialize screen capture backend."""
+        self._mss = mss.mss()
+
+    def _load_template(self, image: str | Path) -> np.ndarray:
+        """Load a template image from disk.
+
+        Args:
+            image: Template image path.
+
+        Returns:
+            BGR image array.
+
+        Raises:
+            TemplateNotFoundError: If the file does not exist or cannot be decoded.
+        """
+        image_path = Path(image)
+        if not image_path.exists():
+            raise TemplateNotFoundError(f"Template not found: {image_path}")
+        template = cv2.imread(str(image_path), cv2.IMREAD_COLOR)
+        if template is None:
+            raise TemplateNotFoundError(f"Unable to load template: {image_path}")
+        return template
+
+    def _capture_screen(self, region: Region | None = None) -> np.ndarray:
+        """Capture the full screen or a specific region.
+
+        Args:
+            region: Optional capture region. ``None`` captures primary monitor.
+
+        Returns:
+            Captured BGR frame as a numpy array.
+        """
+        if region is None:
+            monitor = self._mss.monitors[1]
+            frame = self._mss.grab(monitor)
+            return np.array(frame)[:, :, :3]
+
+        monitor = {
+            "left": region.x,
+            "top": region.y,
+            "width": region.w,
+            "height": region.h,
+        }
+        frame = self._mss.grab(monitor)
+        return np.array(frame)[:, :, :3]
+
+    def find(
+        self,
+        image: str | Path,
+        confidence: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+    ) -> Match | None:
+        """Run one template match operation.
+
+        Args:
+            image: Template image path.
+            confidence: Match threshold in [0.0, 1.0]. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+
+        Returns:
+            ``Match`` on success, otherwise ``None``.
+        """
+        resolved_region = _as_region(region)
+        threshold = confidence if confidence is not None else DEFAULT_CONFIDENCE
+        template = self._load_template(image)
+        screen = self._capture_screen(resolved_region)
+
+        result = cv2.matchTemplate(screen, template, cv2.TM_CCOEFF_NORMED)
+        _, max_val, _, max_loc = cv2.minMaxLoc(result)
+
+        if max_val < threshold:
+            return None
+
+        h, w = template.shape[:2]
+        abs_x = max_loc[0] + (resolved_region.x if resolved_region else 0)
+        abs_y = max_loc[1] + (resolved_region.y if resolved_region else 0)
+        return Match(x=abs_x, y=abs_y, w=w, h=h, score=float(max_val))
+
+    def wait(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+    ) -> Match:
+        """Poll until an image appears or timeout occurs.
+
+        Args:
+            image: Template image path.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold in [0.0, 1.0]. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+
+        Returns:
+            The first successful ``Match``.
+
+        Raises:
+            WaitTimeoutError: If timeout elapses before any match reaches threshold.
+        """
+        interval = poll if poll is not None else DEFAULT_POLL_INTERVAL
+        deadline = time.time() + timeout
+        last_score = 0.0
+        resolved_region = _as_region(region)
+        threshold = confidence if confidence is not None else DEFAULT_CONFIDENCE
+        template = self._load_template(image)
+        h, w = template.shape[:2]
+
+        while time.time() < deadline:
+            screen = self._capture_screen(resolved_region)
+            result = cv2.matchTemplate(screen, template, cv2.TM_CCOEFF_NORMED)
+            _, max_val, _, max_loc = cv2.minMaxLoc(result)
+            score = float(max_val)
+            last_score = max(last_score, score)
+            if score >= threshold:
+                abs_x = max_loc[0] + (resolved_region.x if resolved_region else 0)
+                abs_y = max_loc[1] + (resolved_region.y if resolved_region else 0)
+                return Match(x=abs_x, y=abs_y, w=w, h=h, score=score)
+            time.sleep(interval)
+
+        raise WaitTimeoutError(
+            f"wait timeout image={image} timeout={timeout}s confidence={threshold} last_score={last_score:.4f}"
+        )
+
+    def wait_vanish(
+        self,
+        image: str | Path,
+        timeout: float,
+        confidence: float | None = None,
+        poll: float | None = None,
+        region: Region | tuple[int, int, int, int] | None = None,
+        strict: bool = True,
+    ) -> bool:
+        """Poll until an image can no longer be matched.
+
+        Args:
+            image: Template image path.
+            timeout: Max wait duration in seconds.
+            confidence: Match threshold in [0.0, 1.0]. ``None`` uses configured default.
+            poll: Poll interval in seconds. ``None`` uses configured default.
+            region: Search region as ``Region`` or ``(x, y, w, h)`` tuple.
+            strict: If ``True``, raise on timeout. If ``False``, return ``False``.
+
+        Returns:
+            ``True`` if image vanishes before timeout; otherwise ``False`` when ``strict=False``.
+
+        Raises:
+            VanishTimeoutError: If timeout occurs while ``strict=True``.
+        """
+        interval = poll if poll is not None else DEFAULT_POLL_INTERVAL
+        deadline = time.time() + timeout
+
+        while time.time() < deadline:
+            match = self.find(image=image, confidence=confidence, region=region)
+            if match is None:
+                return True
+            time.sleep(interval)
+
+        if strict:
+            threshold = confidence if confidence is not None else DEFAULT_CONFIDENCE
+            raise VanishTimeoutError(
+                f"wait_vanish timeout image={image} timeout={timeout}s confidence={threshold}"
+            )
+        return False

pyvisionauto-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: pyvisionauto
+Version: 0.1.0
+Summary: PyVisionAuto: Linux end-to-end automation toolkit with visual image matching, mouse/keyboard control, and screen recording
+Author: PyVisionAuto contributors
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://pypi.org/project/pyvisionauto/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: X11 Applications
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: mss>=9.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# PyVisionAuto
+
+PyVisionAuto (`pyvisionauto`) is a Linux end-to-end automation testing toolkit.
+It is centered on visual image matching and also includes screen recording, mouse automation, and keyboard automation capabilities.
+
+## Scope
+
+- Linux only
+- X11 session only
+- Real physical display required
+
+## Install
+
+```bash
+pip install pyvisionauto
+```
+
+## System dependencies
+
+- python3-tk (for border overlay highlight)
+- xdotool (preferred for window activation)
+- wmctrl (fallback for window activation)
+- ffmpeg (optional, only for recording APIs)
+
+## Quick start
+
+```python
+from pyvisionauto import Screen
+
+screen = Screen()
+screen.wait("login_button.png", timeout=10).highlight().click()
+```
+
+## Notes
+
+Wayland-first and headless-only environments are not supported in v0.1.

pyvisionauto-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pyvisionauto/__init__.py,sha256=n8d_57ZPt7_L7QvZY2MyOXu_K2wuY36ZyRP4a55NuBk,888
+pyvisionauto/config.py,sha256=0m8FW_LFz3Jm5iUn7qPbbAamPaW00KtSTMgyOdtXjBo,569
+pyvisionauto/envcheck.py,sha256=Ewa9ldTb1GSd5MyOdoay4SFe5f7IyY9qtgm8fL7ibIA,2907
+pyvisionauto/errors.py,sha256=yu1dE2CTNM3xi0Ss9BIIGSfLsQ0Tb1W2l4M1I_UtY_4,733
+pyvisionauto/highlighter.py,sha256=0DvB2_zJaArKeE3C1TcxxFC7PdEfkMUocX6Qv6I8kfc,2581
+pyvisionauto/input.py,sha256=J4sqtTfSBTZPQRanLKJsXvk1w8oDJaby6F4jjhBw2qc,3954
+pyvisionauto/models.py,sha256=482REXLPKHahnx37pq8L7JiqchXDWDjeDVno8JHhVOA,1938
+pyvisionauto/overlay.py,sha256=cHF8sQNH89B0FLh-kpvPJE5UJTRXpQlj4trxL45jVp0,1289
+pyvisionauto/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyvisionauto/recorder.py,sha256=AaP8Nc7dEm-WCpf0PtzpTYXe8g8HRkB-TqxTxxsNtOw,1856
+pyvisionauto/screen.py,sha256=qFzvjp0skwczU7pFjBiiOHFS9Ffc_-vFPaff4SVPJzU,15861
+pyvisionauto/vision.py,sha256=HjQ7tF5eFbWQcjxCqTvLWMcn2LDt2iWchyFzBSyZ_IY,7177
+pyvisionauto-0.1.0.dist-info/licenses/LICENSE,sha256=ipwM6eUlm4Jvp5a_ixwEJgkko112aJnPjd2rMLmxUsM,411
+pyvisionauto-0.1.0.dist-info/METADATA,sha256=wiz2VCVJgb2UZEW8ueYwFt8MOGSIijBQeidk8wlHobI,1935
+pyvisionauto-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyvisionauto-0.1.0.dist-info/top_level.txt,sha256=3obi1phVrm33prkM9B3t0STWnyvkPF0RcBoUvVJhOH8,13
+pyvisionauto-0.1.0.dist-info/RECORD,,

pyvisionauto-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
+

pyvisionauto-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 PyVisionAuto contributors. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+Redistribution, modification, or use of the source code in any form is
+prohibited without explicit written permission from the copyright holder.
+
+The compiled/distributed package may be used in accordance with the terms
+provided at: https://pypi.org/project/pyvisionauto/

pyvisionauto-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyvisionauto