pyvisionauto 0.1.0__tar.gz

pyvisionauto-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,36 @@
+# 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/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyvisionauto"
+version = "0.1.0"
+description = "PyVisionAuto: Linux end-to-end automation toolkit with visual image matching, mouse/keyboard control, and screen recording"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+requires-python = ">=3.10"
+authors = [
+  { name = "PyVisionAuto contributors" }
+]
+dependencies = [
+  "opencv-python>=4.8.0",
+  "mss>=9.0.0",
+  "numpy>=1.24.0",
+  "pyautogui>=0.9.54",
+  "pillow>=10.0.0"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: POSIX :: Linux",
+  "Environment :: X11 Applications",
+  "Topic :: Software Development :: Testing"
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/pyvisionauto/"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.package-data]
+pyvisionauto = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyvisionauto-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyvisionauto-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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())