apparser 1.0.0__py3-none-any.whl

apparser/__init__.py

@@ -0,0 +1 @@
+from apparser.core import *

apparser/core/__init__.py

@@ -0,0 +1,4 @@
+from apparser.core.app import App
+from apparser.core.ui import BaseUi, DesktopUi, CoordinatesUi, WindowUi, WindowByDisplayUi
+
+__all__ = ["App", "BaseUi", "DesktopUi", "CoordinatesUi", "WindowUi", "WindowByDisplayUi"]

apparser/core/app.py

@@ -0,0 +1,95 @@
+import os
+import subprocess
+import time
+
+from appwindows import get_finder
+from appwindows.exceptions import WindowDoesNotFoundException, WindowDoesNotValidException
+
+from apparser.core.ui import WindowUi, BaseUi
+
+
+class App:
+    """Manage an application process and its UI wrapper."""
+
+    def __init__(self, path_to_exe: str,
+                 window_title: str | None = None,
+                 timeout: float = 1):
+        """Initialize an application controller.
+
+        :param path_to_exe: Path to the executable file.
+        :type path_to_exe: str
+        :param window_title: Title of the window to attach to.
+        :type window_title: str
+        :param timeout: Delay before the window lookup starts.
+        :type timeout: float
+        :raises TypeError: If any argument has an invalid type.
+        """
+        if not isinstance(path_to_exe, str):
+            raise TypeError('path_to_exe must be a string')
+
+        if window_title is not None and not isinstance(window_title, str):
+            raise TypeError('window_title must be a string')
+
+        if not (isinstance(timeout, float) or isinstance(timeout, int)):
+            raise TypeError('timeout must be a number')
+
+        self.__window_finder = get_finder()
+        self.__process: subprocess.Popen | None = None
+        self.__path = path_to_exe
+        self.__timeout = timeout
+        self.__window_title_name: str = window_title
+        self.__ui: BaseUi | None = None
+        self.start_app()
+
+    def __find_window_by_title(self):
+        try:
+            window = self.__window_finder.get_window_by_title(self.__window_title_name)
+            self.__ui = WindowUi(window)
+        except WindowDoesNotFoundException:
+            pass
+
+    def __find_window_by_process_id(self, process_id: int):
+        try:
+            window = self.__window_finder.get_window_by_process_id(process_id)
+            self.__ui = WindowUi(window)
+        except WindowDoesNotFoundException:
+            pass
+
+    def start_app(self):
+        """Start the application process and bind its UI.
+
+        :raises WindowDoesNotValidException: If the window is not found or the application cannot be opened.
+        """
+        if self.__window_title_name is not None:
+            self.__find_window_by_title()
+        if self.__ui is not None:
+            return
+        window_processes = [i.get_process_id() for i in get_finder().get_all_windows()]
+        self.__process = subprocess.Popen([self.__path])
+        time.sleep(self.__timeout)
+        self.__find_window_by_process_id(os.getpid())
+        for i in get_finder().get_all_windows():
+            if self.__ui is not None:
+                return
+            if i.get_process_id() not in window_processes:
+                self.__find_window_by_process_id(i.get_process_id())
+        if self.__ui is not None:
+            return
+        self.__find_window_by_title()
+        if self.__ui is not None:
+            raise WindowDoesNotValidException()
+
+    def stop_app(self):
+        """Close the application window and stop the process."""
+        self.ui.window.close()
+        if self.__process is not None:
+            self.__process.kill()
+
+    @property
+    def ui(self) -> BaseUi:
+        """Return the UI wrapper for the running application.
+
+        :return: UI wrapper bound to the application window.
+        :rtype: BaseUi
+        """
+        return self.__ui

apparser/core/ui/__init__.py

@@ -0,0 +1,8 @@
+from apparser.core.ui.base import BaseUi
+from apparser.core.ui.desktop import DesktopUi
+from apparser.core.ui.coordinates import CoordinatesUi
+from apparser.core.ui.window import WindowUi
+from apparser.core.ui.window_by_display import WindowByDisplayUi
+
+
+__all__ = ["BaseUi", "DesktopUi", "CoordinatesUi", "WindowUi", "WindowByDisplayUi"]

apparser/core/ui/base.py

@@ -0,0 +1,51 @@
+import abc
+
+import numpy
+from appwindows import Window
+
+from apparser.geometry import Point, RelativelyPoint
+
+
+class BaseUi(abc.ABC):
+    """Define the common interface for UI coordinate systems."""
+
+    @abc.abstractmethod
+    def point_to_global(self, coordinates: Point | RelativelyPoint) -> Point:
+        """Convert coordinates to the global screen space.
+
+        :param coordinates: Local or relative coordinates to convert.
+        :type coordinates: Point | RelativelyPoint
+        :return: Converted global point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def point_to_local(self, coordinates: Point) -> Point:
+        """Convert coordinates to the local UI space.
+
+        :param coordinates: Global point to convert.
+        :type coordinates: Point
+        :return: Converted local point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def get_screenshot(self) -> numpy.ndarray:
+        """Capture the current UI screenshot.
+
+        :return: Screenshot data.
+        :rtype: numpy.ndarray
+        """
+        raise NotImplementedError()
+
+    @property
+    @abc.abstractmethod
+    def window(self) -> Window:
+        """Return the window associated with the UI context.
+
+        :return: Underlying application window.
+        :rtype: Window
+        """
+        raise NotImplementedError()

apparser/core/ui/coordinates.py

@@ -0,0 +1,118 @@
+from functools import singledispatchmethod
+
+import numpy
+from appwindows import Window
+from appwindows.geometry import Size
+
+from apparser.core.ui.base import BaseUi
+from apparser.geometry import Point, RelativelyPoint
+
+
+class CoordinatesUi(BaseUi):
+    """Represent a UI region defined by two points inside another UI context."""
+
+    def __init__(
+        self,
+        from_ui: BaseUi,
+        point_one: Point | RelativelyPoint,
+        point_two: Point | RelativelyPoint
+    ):
+        """Initialize a nested coordinate-based UI context.
+
+        :param from_ui: Source UI used as a parent context.
+        :type from_ui: BaseUi
+        :param point_one: First point of the nested region.
+        :type point_one: Point | RelativelyPoint
+        :param point_two: Second point of the nested region or region size.
+        :type point_two: Point | RelativelyPoint | Size
+        :raises TypeError: If any argument has an invalid type.
+        """
+        if not isinstance(from_ui, BaseUi):
+            raise TypeError('from_ui must be BaseUi')
+
+        if not isinstance(point_one, (Point, RelativelyPoint)):
+            raise TypeError('point1 must be Point or RelativelyPoint')
+
+        elif not isinstance(point_two, (Point, RelativelyPoint)):
+            raise TypeError('point2 must be Point, RelativelyPoint')
+
+        self.__from_ui = from_ui
+        self.__point_one = point_one
+        self.__point_two = point_two
+
+    def __point_to_main_ui_local(self, point: Point | RelativelyPoint) -> Point:
+        if isinstance(point, RelativelyPoint):
+            return self.__from_ui.point_to_local(self.__from_ui.point_to_global(point))
+        return point
+
+    def __get_local_bounds(self) -> tuple[Point, Point]:
+        point1 = self.__point_to_main_ui_local(self.__point_one)
+        point2 = self.__point_to_main_ui_local(self.__point_two)
+        left_top_point = Point(
+            min(point1.x, point2.x),
+            min(point1.y, point2.y),
+        )
+        right_bottom_point = Point(
+            max(point1.x, point2.x),
+            max(point1.y, point2.y),
+        )
+        return left_top_point, right_bottom_point
+
+    @singledispatchmethod
+    def point_to_global(self, coordinates: Point | RelativelyPoint) -> Point:
+        """Convert region coordinates to the global screen space.
+
+        :param coordinates: Local or relative coordinates to convert.
+        :type coordinates: Point | RelativelyPoint
+        :return: Converted global point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @point_to_global.register(Point)
+    def _(self, coordinates: Point) -> Point:
+        left_top_point, _ = self.__get_local_bounds()
+        return self.__from_ui.point_to_global(coordinates + left_top_point)
+
+    @point_to_global.register(RelativelyPoint)
+    def _(self, coordinates: RelativelyPoint) -> Point:
+        left_top_point, right_bottom_point = self.__get_local_bounds()
+        width = abs(round(right_bottom_point.x - left_top_point.x))
+        height = abs(round(right_bottom_point.y - left_top_point.y))
+        x = round(coordinates.x * width)
+        y = round(coordinates.y * height)
+        local_point = Point(x, y)
+        return self.point_to_global(local_point)
+
+    def point_to_local(self, coordinates: Point) -> Point:
+        """Convert global coordinates to the local region space.
+
+        :param coordinates: Global point to convert.
+        :type coordinates: Point
+        :return: Converted local point.
+        :rtype: Point
+        """
+        left_top_point, _ = self.__get_local_bounds()
+        return self.__from_ui.point_to_local(coordinates) - left_top_point
+
+    def get_screenshot(self) -> numpy.ndarray:
+        """Capture a screenshot cropped to the nested region.
+
+        :return: Screenshot data for the nested region.
+        :rtype: numpy.ndarray
+        """
+        screenshot = self.__from_ui.get_screenshot()
+        left_top_point, right_bottom_point = self.__get_local_bounds()
+        return screenshot[
+            left_top_point.y:right_bottom_point.y,
+            left_top_point.x:right_bottom_point.x,
+        ]
+
+    @property
+    def window(self) -> Window:
+        """Return the parent window for the nested region.
+
+        :return: Underlying parent window.
+        :rtype: Window
+        """
+        return self.__from_ui.window

apparser/core/ui/desktop.py

@@ -0,0 +1,72 @@
+from functools import singledispatchmethod
+
+import numpy
+from appwindows import Window
+from PIL import ImageGrab
+from screeninfo import get_monitors
+
+from apparser.core.ui.base import BaseUi
+from apparser.geometry import Point, RelativelyPoint
+from apparser.exceptions import WindowActionWithDesktopException
+
+
+class DesktopUi(BaseUi):
+    """Represent the full desktop as a UI context."""
+
+    def __init__(self, display_id: int = 0):
+        """Initialize a desktop UI context.
+
+        :param display_id: Monitor index used for relative coordinates.
+        :type display_id: int
+        """
+        self.__display_id = display_id
+
+    @singledispatchmethod
+    def point_to_global(self, coordinates: Point | RelativelyPoint) -> Point:
+        """Convert desktop coordinates to the global screen space.
+
+        :param coordinates: Local or relative coordinates to convert.
+        :type coordinates: Point | RelativelyPoint
+        :return: Converted global point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @point_to_global.register(Point)
+    def _(self, coordinates: Point):
+        return coordinates
+
+    @point_to_global.register(RelativelyPoint)
+    def _(self, coordinates: RelativelyPoint):
+        monitor = get_monitors()[self.__display_id]
+        x = round(coordinates.x * monitor.width)
+        y = round(coordinates.y * monitor.height)
+        local_point = Point(x, y)
+        return self.point_to_global(local_point)
+
+    def point_to_local(self, coordinates: Point) -> Point:
+        """Convert global coordinates to the desktop local space.
+
+        :param coordinates: Global point to convert.
+        :type coordinates: Point
+        :return: Converted local point.
+        :rtype: Point
+        """
+        return Point(coordinates.x, coordinates.y)
+
+    def get_screenshot(self) -> numpy.ndarray:
+        """Capture a screenshot of the desktop.
+
+        :return: Desktop screenshot data.
+        :rtype: numpy.ndarray
+        """
+        screenshot = ImageGrab.grab()
+        return numpy.asarray(screenshot)
+
+    @property
+    def window(self) -> Window:
+        """Raise an exception because the desktop has no window.
+
+        :raises WindowActionWithDesktopException: Always raised for desktop UI contexts.
+        """
+        raise WindowActionWithDesktopException()

apparser/core/ui/window.py

@@ -0,0 +1,75 @@
+from functools import singledispatchmethod
+
+import numpy
+
+from appwindows import Window
+from appwindows.geometry import Point, Size
+
+from apparser.core.ui.base import BaseUi
+from apparser.geometry.relatively_point import RelativelyPoint
+
+
+class WindowUi(BaseUi):
+    """Represent a window as a UI context."""
+
+    def __init__(self, window: Window):
+        """Initialize a window UI context.
+
+        :param window: Window instance to wrap.
+        :type window: Window
+        :raises TypeError: If ``window`` has an invalid type.
+        """
+        if not isinstance(window, Window):
+            raise TypeError('window must be Window')
+
+        self.__window = window
+
+    @singledispatchmethod
+    def point_to_global(self, coordinates: Point | RelativelyPoint) -> Point:
+        """Convert window coordinates to the global screen space.
+
+        :param coordinates: Local or relative coordinates to convert.
+        :type coordinates: Point | RelativelyPoint
+        :return: Converted global point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @point_to_global.register(Point)
+    def _(self, coordinates: Point):
+        return coordinates + self.__window.get_points().left_top
+
+    @point_to_global.register(RelativelyPoint)
+    def _(self, coordinates: RelativelyPoint):
+        size: Size = self.__window.get_size()
+        x = round(coordinates.x * size.width)
+        y = round(coordinates.y * size.height)
+        local_point = Point(x, y)
+        return self.point_to_global(local_point)
+
+    def point_to_local(self, coordinates: Point) -> Point:
+        """Convert global coordinates to the window local space.
+
+        :param coordinates: Global point to convert.
+        :type coordinates: Point
+        :return: Converted local point.
+        :rtype: Point
+        """
+        return coordinates - self.__window.get_points().left_top
+
+    def get_screenshot(self) -> numpy.ndarray:
+        """Capture a screenshot of the window.
+
+        :return: Window screenshot data.
+        :rtype: numpy.ndarray
+        """
+        return self.__window.get_screenshot()
+
+    @property
+    def window(self):
+        """Return the wrapped window instance.
+
+        :return: Wrapped window.
+        :rtype: Window
+        """
+        return self.__window

apparser/core/ui/window_by_display.py

@@ -0,0 +1,90 @@
+from functools import singledispatchmethod
+
+import numpy
+from PIL import ImageGrab
+
+from appwindows import Window
+from appwindows.geometry import Point, Size
+
+from apparser.core.ui.base import BaseUi
+from apparser.geometry.relatively_point import RelativelyPoint
+
+
+class WindowByDisplayUi(BaseUi):
+    """
+    Represent a window as a display-captured UI context.
+    Unlike the WindowUi class, it retrieves the application's image based on its borders rather than from the graphical shell.
+    """
+
+    def __init__(self, window: Window) -> None:
+        """Initialize a display-captured window UI context.
+
+        :param window: Window instance to wrap.
+        :type window: Window
+        :raises TypeError: If ``window`` has an invalid type.
+        """
+        if not isinstance(window, Window):
+            raise TypeError('window must be Window')
+
+        self.__window = window
+
+    @singledispatchmethod
+    def point_to_global(self, coordinates: Point | RelativelyPoint) -> Point:
+        """Convert window coordinates to the global screen space.
+
+        :param coordinates: Local or relative coordinates to convert.
+        :type coordinates: Point | RelativelyPoint
+        :return: Converted global point.
+        :rtype: Point
+        """
+        raise NotImplementedError()
+
+    @point_to_global.register(Point)
+    def _(self, coordinates: Point) -> Point:
+        return coordinates + self.__window.get_points().left_top
+
+    @point_to_global.register(RelativelyPoint)
+    def _(self, coordinates: RelativelyPoint) -> Point:
+        size: Size = self.__window.get_size()
+        x = round(coordinates.x * size.width)
+        y = round(coordinates.y * size.height)
+        local_point = Point(x, y)
+        return self.point_to_global(local_point)
+
+    def point_to_local(self, coordinates: Point) -> Point:
+        """Convert global coordinates to the window local space.
+
+        :param coordinates: Global point to convert.
+        :type coordinates: Point
+        :return: Converted local point.
+        :rtype: Point
+        """
+        return coordinates - self.__window.get_points().left_top
+
+    def get_screenshot(self) -> numpy.ndarray:
+        """Capture a screenshot of the window from the display.
+
+        :return: Window screenshot data captured by window bounds.
+        :rtype: numpy.ndarray
+        """
+        left_top = self.__window.get_points().left_top
+        size: Size = self.__window.get_size()
+        screenshot = ImageGrab.grab(
+            bbox=(
+                left_top.x,
+                left_top.y,
+                left_top.x + size.width,
+                left_top.y + size.height,
+            ),
+            all_screens=True,
+        )
+        return numpy.asarray(screenshot)
+
+    @property
+    def window(self) -> Window:
+        """Return the wrapped window instance.
+
+        :return: Wrapped window.
+        :rtype: Window
+        """
+        return self.__window

apparser/cv/__init__.py

@@ -0,0 +1,6 @@
+"""Public computer vision interfaces and default implementations."""
+
+from apparser.cv.handlers.default import DefaultHandlers
+from apparser.cv.processes.default import DefaultCvProcess
+from apparser.cv.readers.yolo import YoloReader
+from apparser.cv.models import *

apparser/cv/events/__init__.py

@@ -0,0 +1,8 @@
+from apparser.cv.events.base import CvEvent
+from apparser.cv.events.moved import Moved
+from apparser.cv.events.detected import Detected
+from apparser.cv.events.resized import Resized
+from apparser.cv.events.undetected import UnDetected
+
+__all__ = ["CvEvent", "Moved",
+           "Detected", "Resized", "UnDetected"]

apparser/cv/events/base.py

@@ -0,0 +1,14 @@
+import abc
+
+
+class CvEvent(abc.ABC):
+    """Define the interface for computer vision change events."""
+
+    @abc.abstractmethod
+    def __str__(self) -> str:
+        """Return the human-readable event name.
+
+        :return: Event name.
+        :rtype: str
+        """
+        raise NotImplementedError()

apparser/cv/events/detected.py

@@ -0,0 +1,13 @@
+from apparser.cv.events.base import CvEvent
+
+
+class Detected(CvEvent):
+    """Represent a newly detected object."""
+
+    def __str__(self) -> str:
+        """Return the event name.
+
+        :return: Detected event name.
+        :rtype: str
+        """
+        return "Detected"

apparser/cv/events/moved.py

@@ -0,0 +1,13 @@
+from apparser.cv.events.base import CvEvent
+
+
+class Moved(CvEvent):
+    """Represent a detected object whose position changed."""
+
+    def __str__(self) -> str:
+        """Return the event name.
+
+        :return: Moved event name.
+        :rtype: str
+        """
+        return "Moved"

apparser/cv/events/resized.py

@@ -0,0 +1,13 @@
+from apparser.cv.events.base import CvEvent
+
+
+class Resized(CvEvent):
+    """Represent a detected object whose size changed."""
+
+    def __str__(self) -> str:
+        """Return the event name.
+
+        :return: Resized event name.
+        :rtype: str
+        """
+        return "Resized"

apparser/cv/events/undetected.py

@@ -0,0 +1,13 @@
+from apparser.cv.events.base import CvEvent
+
+
+class UnDetected(CvEvent):
+    """Represent a previously tracked object that disappeared."""
+
+    def __str__(self) -> str:
+        """Return the event name.
+
+        :return: Undetected event name.
+        :rtype: str
+        """
+        return "UnDetected"

apparser/cv/handlers/__init__.py

@@ -0,0 +1,5 @@
+from apparser.cv.handlers.base import CvHandlers
+from apparser.cv.handlers.default import DefaultHandlers
+
+
+__all__ = ["CvHandlers", "DefaultHandlers"]

apparser/cv/handlers/base.py

@@ -0,0 +1,30 @@
+import abc
+from typing import Type
+
+from apparser.cv.events import CvEvent
+from apparser.cv.models import CvChangeData
+
+
+class CvHandlers(abc.ABC):
+    """Define the interface for computer vision event handler registries."""
+
+    @abc.abstractmethod
+    def register_handler(self, event: Type[CvEvent]):
+        """Return a decorator that registers a handler for an event.
+
+        :param event: Event type to subscribe to.
+        :type event: Type[CvEvent]
+        """
+        pass
+
+    @abc.abstractmethod
+    def call(self, event: Type[CvEvent], changed_data: CvChangeData, *args):
+        """Call handlers registered for the provided event.
+
+        :param event: Event type to dispatch.
+        :type event: Type[CvEvent]
+        :param changed_data: Event payload with current and previous box data.
+        :type changed_data: CvChangeData
+        :param args: Additional context passed to handler functions.
+        """
+        pass