robotframework-desktop 0.1.0__py3-none-any.whl

DesktopLibrary/geometry.py

@@ -0,0 +1,187 @@
+import ast
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Region:
+    """Rectangular area of the screen in virtual-screen coordinates."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    def __post_init__(self):
+        self.x, self.y = int(self.x), int(self.y)
+        self.width, self.height = int(self.width), int(self.height)
+
+    @property
+    def w(self) -> int:
+        return self.width
+
+    @property
+    def h(self) -> int:
+        return self.height
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return self.x + self.width // 2, self.y + self.height // 2
+
+    @property
+    def right(self) -> int:
+        return self.x + self.width
+
+    @property
+    def bottom(self) -> int:
+        return self.y + self.height
+
+    def to_list(self) -> list[int]:
+        return [self.x, self.y, self.width, self.height]
+
+    def to_tuple(self) -> tuple[int, int, int, int]:
+        return self.x, self.y, self.width, self.height
+
+    def contains_point(self, px: int, py: int) -> bool:
+        return self.x <= px < self.right and self.y <= py < self.bottom
+
+    def intersection(self, other: 'Region') -> 'Region | None':
+        x1, y1 = max(self.x, other.x), max(self.y, other.y)
+        x2, y2 = min(self.right, other.right), min(self.bottom, other.bottom)
+        if x2 <= x1 or y2 <= y1:
+            return None
+        return Region(x1, y1, x2 - x1, y2 - y1)
+
+    def overlap_ratio(self, other: 'Region') -> float:
+        inter = self.intersection(other)
+        if inter is None:
+            return 0.0
+        smaller = (
+            min(self.width * self.height, other.width * other.height) or 1
+        )
+        return inter.width * inter.height / smaller
+
+    def extended(self, direction: str, times: float = 1) -> 'Region':
+        """Region adjacent to this one in ``direction`` (``above``, ``below``,
+        ``left``, ``right`` or ``original``) scaled by ``times``."""
+        direction = str(direction).strip().lower()
+        times = float(times)
+        if direction == 'original':
+            return Region(*self.to_tuple())
+        if direction == 'below':
+            return Region(self.x, self.bottom, self.width, self.height * times)
+        if direction == 'above':
+            h = int(self.height * times)
+            return Region(self.x, self.y - h, self.width, h)
+        if direction == 'right':
+            return Region(self.right, self.y, self.width * times, self.height)
+        if direction == 'left':
+            w = int(self.width * times)
+            return Region(self.x - w, self.y, w, self.height)
+        raise ValueError(
+            f"Invalid direction '{direction}'. Use above, below, left, right or original."
+        )
+
+    def jump(self, direction: str, jumps: int, margin: int = 1) -> 'Region':
+        """Translate the region ``jumps`` times its own size plus ``margin``."""
+        direction = str(direction).strip().lower()
+        jumps, margin = int(jumps), int(margin)
+        if margin < 1:
+            raise ValueError('Margin must be >= 1.')
+        dx = (self.width + margin) * jumps
+        dy = (self.height + margin) * jumps
+        moves = {
+            'below': (0, dy),
+            'above': (0, -dy),
+            'right': (dx, 0),
+            'left': (-dx, 0),
+        }
+        if direction not in moves:
+            raise ValueError(
+                f"Invalid direction '{direction}'. Use above, below, left or right."
+            )
+        mx, my = moves[direction]
+        return Region(self.x + mx, self.y + my, self.width, self.height)
+
+    def __str__(self) -> str:
+        return f'Region(x={self.x}, y={self.y}, width={self.width}, height={self.height})'
+
+
+@dataclass
+class Match(Region):
+    """Element found on screen. ``target`` is the action point
+    (center plus the locator offset)."""
+
+    score: float = 1.0
+    source: str = ''
+    offset: tuple[int, int] = (0, 0)
+    element: Any = field(default=None, repr=False, compare=False)
+
+    @property
+    def target(self) -> tuple[int, int]:
+        cx, cy = self.center
+        return cx + int(self.offset[0]), cy + int(self.offset[1])
+
+    def __str__(self) -> str:
+        return (
+            f'Match(x={self.x}, y={self.y}, width={self.width}, height={self.height}, '
+            f'score={self.score:.3f}, source={self.source})'
+        )
+
+
+def sort_matches(matches: list, sort_by: str = 'row') -> list:
+    """Sorts matches by ``row`` (top-bottom, left-right), ``column``
+    (left-right, top-bottom), ``score`` (best first) or ``none``."""
+    key = str(sort_by or 'none').strip().lower()
+    if key == 'row':
+        return sorted(matches, key=lambda m: (m.y, m.x))
+    if key == 'column':
+        return sorted(matches, key=lambda m: (m.x, m.y))
+    if key == 'score':
+        return sorted(matches, key=lambda m: -getattr(m, 'score', 1.0))
+    if key == 'none':
+        return list(matches)
+    raise ValueError(
+        f"Invalid sort_by '{sort_by}'. Use row, column, score or none."
+    )
+
+
+def to_region(value: Any) -> Region:
+    """Convert a Region, list/tuple ``[x, y, w, h]``, dict or string into a Region."""
+    if isinstance(value, Region):
+        return Region(value.x, value.y, value.width, value.height)
+    if isinstance(value, dict):
+        lower = {str(k).lower(): v for k, v in value.items()}
+        return Region(
+            lower.get('x', 0),
+            lower.get('y', 0),
+            lower.get('width', lower.get('w')),
+            lower.get('height', lower.get('h')),
+        )
+    if isinstance(value, str):
+        text = value.strip()
+        if not text.startswith(('[', '(')):
+            text = f'[{text}]'
+        value = ast.literal_eval(text)
+    if isinstance(value, (list, tuple)) and len(value) == 4:
+        return Region(*[int(float(v)) for v in value])
+    raise ValueError(
+        f"Cannot convert '{value}' to a region. Expected [x, y, width, height]."
+    )
+
+
+def to_offset(value: Any) -> tuple[int, int]:
+    if value is None or value == '':
+        return 0, 0
+    if isinstance(value, dict):
+        lower = {str(k).lower(): v for k, v in value.items()}
+        return int(lower.get('x', 0)), int(lower.get('y', 0))
+    if isinstance(value, str):
+        value = ast.literal_eval(
+            value if value.strip().startswith(('[', '(')) else f'[{value}]'
+        )
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        return int(value[0]), int(value[1])
+    raise ValueError(
+        f"Cannot convert '{value}' to an offset. Expected {{'x': int, 'y': int}}."
+    )

DesktopLibrary/keywords/__init__.py

@@ -0,0 +1,23 @@
+from .application import ApplicationKeywords
+from .config import ConfigKeywords
+from .cursor import CursorKeywords
+from .element import ElementKeywords
+from .find import FindKeywords
+from .keyboard import KeyboardKeywords
+from .mouse import MouseKeywords
+from .ocr import OcrKeywords
+from .region import RegionKeywords
+from .wait import WaitKeywords
+
+__all__ = [
+    'ApplicationKeywords',
+    'ConfigKeywords',
+    'CursorKeywords',
+    'ElementKeywords',
+    'FindKeywords',
+    'KeyboardKeywords',
+    'MouseKeywords',
+    'OcrKeywords',
+    'RegionKeywords',
+    'WaitKeywords',
+]

DesktopLibrary/keywords/application.py

@@ -0,0 +1,149 @@
+import shlex
+import subprocess
+
+from robot.api import logger
+from robot.api.deco import keyword
+
+from ..locator import parse_locator
+from .base import KeywordGroup
+
+
+class ApplicationKeywords(KeywordGroup):
+    @keyword
+    def open_application(
+        self,
+        path: str,
+        *args,
+        alias: str = '',
+        backend: str = '',
+        timeout='10s',
+    ):
+        """Starts an application and returns its alias.
+
+        The application is started with pywinauto, so it can later be used
+        with UI Automation keywords. ``alias`` defaults to the executable name.
+
+        Examples:
+        | Open Application | notepad.exe |
+        | Open Application | C:/apps/MyApp.exe | --config | test.ini | alias=myapp |
+        | Open Application | calc.exe | backend=uia |
+        """
+        command = subprocess.list2cmdline([path, *args]) if args else path
+        name = alias or _exe_name(path)
+        self.ctx.ui.start(
+            name, command, backend or None, self.ctx.to_seconds(timeout)
+        )
+        logger.info(f"Started '{command}' as '{name}'.")
+        return name
+
+    @keyword
+    def connect_to_application(
+        self, alias: str = '', backend: str = '', timeout='10s', **criteria
+    ):
+        """Connects to a running application. Criteria are passed to
+        pywinauto ``Application.connect``: ``process``, ``path``, ``title``,
+        ``title_re``, ``handle``.
+
+        Examples:
+        | Connect To Application | process=1234 |
+        | Connect To Application | alias=calc | path=calc.exe |
+        | Connect To Application | title_re=.*Notepad |
+        """
+        for key in ('process', 'handle'):
+            if key in criteria:
+                criteria[key] = int(criteria[key])
+        name = alias or str(
+            criteria.get('path') or criteria.get('title') or 'app'
+        )
+        self.ctx.ui.connect(
+            name, backend or None, self.ctx.to_seconds(timeout), **criteria
+        )
+        return name
+
+    @keyword
+    def close_application(self, name: str):
+        """Closes an application by alias (from `Open Application` /
+        `Connect To Application`) or by process name.
+
+        Examples:
+        | Close Application | myapp |
+        | Close Application | notepad.exe |
+        """
+        app = self.ctx.ui.apps.pop(name, None)
+        if app is not None:
+            try:
+                app.kill(soft=True)
+            except Exception:
+                app.kill()
+            return
+        exe = name if name.lower().endswith('.exe') else name + '.exe'
+        result = subprocess.run(
+            ['taskkill', '/IM', exe, '/F'], capture_output=True, text=True
+        )
+        if result.returncode != 0:
+            raise AssertionError(
+                f"Could not close '{name}': {result.stderr.strip()}"
+            )
+
+    # ---- windows -------------------------------------------------------------
+    @keyword
+    def attach_to_window(self, window, timeout=''):
+        """Sets the top level window used as root for UI Automation searches
+        and brings it to the foreground.
+
+        ``window`` uses the UI locator syntax (see `Element locators`).
+
+        Examples:
+        | Attach To Window | name:Untitled - Notepad |
+        | Attach To Window | name_re:.*Notepad |
+        | Attach To Window | win32:class:Notepad |
+        | Attach To Window | ${{ {"name": "Sample App", "backend": "uia"} }} |
+        """
+        locator = parse_locator(window)
+        if locator.kind != 'ui':
+            raise ValueError(
+                "Attach To Window requires a UI locator such as 'name:My App'."
+            )
+        secs = self.ctx.to_seconds(timeout, self.ctx.timeout)
+        self.ctx.ui.attach_window(locator.criteria, locator.backend, secs)
+
+    @keyword
+    def switch_window(self, window, timeout=''):
+        """Alias for `Attach To Window`.
+
+        Example:
+        | Switch Window | name:Settings |
+        """
+        self.attach_to_window(window, timeout)
+
+    @keyword
+    def detach_window(self):
+        """Removes the window set by `Attach To Window`; UI searches start
+        from the desktop again.
+
+        Example:
+        | Detach Window |
+        """
+        self.ctx.ui.detach()
+
+    @keyword
+    def set_backend(self, backend: str):
+        """Sets the default UI backend: ``uia`` (WPF, WinForms, UWP, Win32)
+        or ``win32`` (legacy Win32/WinForms). Returns the previous one.
+
+        Example:
+        | ${old}= | Set Backend | win32 |
+        """
+        backend = str(backend).lower()
+        if backend not in ('uia', 'win32'):
+            raise ValueError("Backend must be 'uia' or 'win32'.")
+        old, self.ctx.ui.backend = self.ctx.ui.backend, backend
+        return old
+
+
+def _exe_name(path: str) -> str:
+    try:
+        first = shlex.split(path, posix=False)[0]
+    except ValueError:
+        first = path
+    return first.strip('"').replace('\\', '/').rsplit('/', 1)[-1]

DesktopLibrary/keywords/base.py

@@ -0,0 +1,90 @@
+import functools
+import inspect
+import time
+
+import pyautogui
+
+from ..context import LibraryContext
+from ..geometry import Match
+
+_BUSY_DOC = """
+
+        After the action, waits while the cursor is busy (see `Busy cursor
+        handling`). With ``ignore_busy_error=True`` a busy cursor timeout only
+        logs a warning instead of failing.
+"""
+
+
+def busy_action(func):
+    """Adds the named-only ``ignore_busy_error`` argument and waits for a
+    busy cursor caused by the action after the keyword body runs."""
+
+    @functools.wraps(func)
+    def wrapper(self, *args, ignore_busy_error: bool = False, **kwargs):
+        with self._action(ignore_busy_error):
+            return func(self, *args, **kwargs)
+
+    sig = inspect.signature(func)
+    params = list(sig.parameters.values())
+    extra = inspect.Parameter(
+        'ignore_busy_error',
+        inspect.Parameter.KEYWORD_ONLY,
+        default=False,
+        annotation=bool,
+    )
+    insert_at = len(params)
+    if params and params[-1].kind is inspect.Parameter.VAR_KEYWORD:
+        insert_at -= 1
+    params.insert(insert_at, extra)
+    wrapper.__signature__ = sig.replace(parameters=params)
+    wrapper.__annotations__ = {
+        **getattr(func, '__annotations__', {}),
+        'ignore_busy_error': bool,
+    }
+    del wrapper.__wrapped__
+    wrapper.__doc__ = (func.__doc__ or '').rstrip() + _BUSY_DOC
+    return wrapper
+
+
+class KeywordGroup:
+    def __init__(self, ctx: LibraryContext):
+        self.ctx = ctx
+
+    def _locate(self, element, x_offset=0, y_offset=0, timeout=None) -> Match:
+        match = self.ctx.find(
+            element, timeout, x_offset=int(x_offset), y_offset=int(y_offset)
+        )
+        self.ctx.show_action(match)
+        return match
+
+    def _move(self, x: int, y: int):
+        self.ctx.cursor.auto_wait()
+        pyautogui.moveTo(x, y, duration=self.ctx.move_mouse_delay)
+
+    def _click_at(self, match: Match, clicks: int = 1, button: str = 'left'):
+        x, y = match.target
+        self._move(x, y)
+        self.ctx.cursor.auto_wait()
+        pyautogui.click(x, y, clicks=clicks, interval=0.05, button=button)
+        self.ctx.last_match = match
+
+    def _ready(self):
+        """Waits for a busy cursor before keyboard/mouse actions without element."""
+        self.ctx.cursor.auto_wait()
+
+    def _action(self, ignore_busy_error=False):
+        """Context manager for action keywords: waits for a busy cursor caused
+        by the action and optionally turns busy timeouts into warnings."""
+        if not isinstance(ignore_busy_error, bool):
+            ignore_busy_error = str(ignore_busy_error).strip().lower() in (
+                'true',
+                '1',
+                'yes',
+                'on',
+            )
+        return self.ctx.cursor.action(ignore_busy_error)
+
+    @staticmethod
+    def _sleep(seconds: float):
+        if seconds > 0:
+            time.sleep(seconds)

DesktopLibrary/keywords/config.py

@@ -0,0 +1,159 @@
+import pyautogui
+from robot.api.deco import keyword
+
+from .base import KeywordGroup
+
+
+class ConfigKeywords(KeywordGroup):
+    @keyword
+    def add_image_path(self, path: str):
+        """Adds a folder where relative image paths are searched.
+
+        Folders are searched in the order they were added, then the current
+        working directory. Folders can also be given on import with ``image_paths``.
+
+        Example:
+        | Add Image Path | ${CURDIR}/images |
+        | Click | buttons/ok.png | | # resolved as ${CURDIR}/images/buttons/ok.png |
+        """
+        self.ctx.resolver.add(path)
+
+    @keyword
+    def remove_image_path(self, path: str):
+        """Removes a folder added with `Add Image Path`.
+
+        Example:
+        | Remove Image Path | ${CURDIR}/images |
+        """
+        self.ctx.resolver.remove(path)
+
+    @keyword
+    def get_image_paths(self) -> list:
+        """Returns the registered image folders.
+
+        Example:
+        | @{paths}= | Get Image Paths |
+        """
+        return [str(p) for p in self.ctx.resolver.paths]
+
+    @keyword
+    def set_min_similarity(self, min_similarity: float) -> float:
+        """Sets the default image similarity (0-1, default ``0.6``) and returns
+        the previous value. Locator level ``similarity`` overrides it.
+
+        Example:
+        | Set Min Similarity | 0.85 |
+        """
+        value = float(min_similarity)
+        if value > 1:
+            value /= 100
+        if not 0 < value <= 1:
+            raise ValueError('Similarity must be between 0 and 1.')
+        old, self.ctx.similarity = self.ctx.similarity, value
+        return old
+
+    @keyword
+    def set_timeout(self, timeout) -> float:
+        """Sets the default wait timeout and returns the previous value.
+        Accepts Robot Framework time format.
+
+        Examples:
+        | Set Timeout | 10 |
+        | ${old}= | Set Timeout | 2 min |
+        """
+        old, self.ctx.timeout = self.ctx.timeout, self.ctx.to_seconds(timeout)
+        return old
+
+    @keyword
+    def set_capture_folder(self, path: str):
+        """Sets the folder where captures are saved (default ``${OUTPUT DIR}``).
+
+        Example:
+        | Set Capture Folder | ${OUTPUT DIR}/captures |
+        """
+        self.ctx.capture_folder = path
+
+    @keyword
+    def set_capture_matched_image(self, value: bool):
+        """When enabled, every match is captured and embedded in the log.
+        Disabled by default.
+
+        Example:
+        | Set Capture Matched Image | true |
+        """
+        self.ctx.capture_matched_image = _bool(value)
+
+    @keyword
+    def set_move_mouse_delay(self, delay: float):
+        """Sets the duration (seconds) of mouse movements.
+
+        Example:
+        | Set Move Mouse Delay | 0.3 |
+        """
+        self.ctx.move_mouse_delay = float(delay)
+
+    @keyword
+    def set_slow_motion_delay(self, delay: float):
+        """Sets the duration (seconds) of the visual effect shown when
+        `Set Show Actions` is enabled.
+
+        Example:
+        | Set Slow Motion Delay | 1 |
+        """
+        self.ctx.slow_motion_delay = float(delay)
+
+    @keyword
+    def set_show_actions(self, show_actions: bool):
+        """Highlights each target before acting on it (useful for debugging).
+
+        Example:
+        | Set Show Actions | true |
+        """
+        self.ctx.show_actions = _bool(show_actions)
+
+    @keyword
+    def set_wait_scan_rate(self, rate: float):
+        """Sets how many searches per second are made while waiting (default 10).
+
+        Example:
+        | Set Wait Scan Rate | 5 |
+        """
+        rate = float(rate)
+        if rate <= 0:
+            raise ValueError('Scan rate must be greater than 0.')
+        self.ctx.scan_rate = rate
+
+    @keyword
+    def set_always_resize(self, resize: float):
+        """Resizes all reference images by ``resize`` before searching
+        (e.g. ``1.25`` for 125% DPI scaling). ``0`` or ``1`` disables it.
+
+        Example:
+        | Set Always Resize | 1.25 |
+        """
+        self.ctx.image.resize_factor = float(resize)
+
+    @keyword
+    def set_grayscale(self, grayscale: bool):
+        """Enables grayscale image matching (faster, ignores colors).
+
+        Example:
+        | Set Grayscale | true |
+        """
+        self.ctx.image.grayscale = _bool(grayscale)
+
+    @keyword
+    def set_fail_safe(self, enabled: bool):
+        """Enables/disables pyautogui fail-safe (moving the mouse to a screen
+        corner aborts the action). Enabled by default.
+
+        Example:
+        | Set Fail Safe | false |
+        """
+        pyautogui.FAILSAFE = _bool(enabled)
+
+
+def _bool(value) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in ('true', '1', 'yes', 'on')