robotframework-desktop 0.1.0__py3-none-any.whl

DesktopLibrary/overlay.py

@@ -0,0 +1,180 @@
+"""Screen overlays (highlight and interactive region selection) using Tkinter.
+
+All Tk objects live in a dedicated daemon thread; other threads talk to it
+through a queue.
+"""
+
+import queue
+import threading
+import uuid
+
+from .geometry import Region
+
+_TRANSPARENT = '#ff00fe'
+
+
+class Overlay:
+    def __init__(self):
+        self._queue: queue.Queue = queue.Queue()
+        self._thread: threading.Thread | None = None
+        self._ready = threading.Event()
+        self._windows: dict[str, object] = {}
+        self._keys: dict[str, list[str]] = {}
+        self._root = None
+
+    # ---- thread ---------------------------------------------------------
+    def _ensure(self):
+        if self._thread and self._thread.is_alive():
+            return
+        self._ready.clear()
+        self._thread = threading.Thread(
+            target=self._run, name='DesktopLibraryOverlay', daemon=True
+        )
+        self._thread.start()
+        self._ready.wait(5)
+
+    def _run(self):
+        import tkinter as tk
+
+        self._root = tk.Tk()
+        self._root.withdraw()
+        self._ready.set()
+        self._root.after(30, self._poll)
+        self._root.mainloop()
+
+    def _poll(self):
+        try:
+            while True:
+                func, args = self._queue.get_nowait()
+                try:
+                    func(*args)
+                except Exception:
+                    pass
+        except queue.Empty:
+            pass
+        self._root.after(30, self._poll)
+
+    def _call(self, func, *args):
+        self._ensure()
+        self._queue.put((func, args))
+
+    # ---- highlight --------------------------------------------------------
+    def highlight(
+        self,
+        region: Region,
+        seconds: float = 0,
+        key: str = '',
+        color: str = 'red',
+        width: int = 3,
+    ) -> str:
+        hid = uuid.uuid4().hex
+        self._keys.setdefault(key or hid, []).append(hid)
+        self._call(
+            self._create, hid, region, float(seconds or 0), color, int(width)
+        )
+        return hid
+
+    def _create(self, hid, region: Region, seconds, color, width):
+        import tkinter as tk
+
+        win = tk.Toplevel(self._root)
+        win.overrideredirect(True)
+        win.attributes('-topmost', True)
+        try:
+            win.attributes('-transparentcolor', _TRANSPARENT)
+        except tk.TclError:
+            win.attributes('-alpha', 0.4)
+        pad = width
+        win.geometry(
+            f'{region.width + 2 * pad}x{region.height + 2 * pad}+{region.x - pad}+{region.y - pad}'
+        )
+        canvas = tk.Canvas(win, bg=_TRANSPARENT, highlightthickness=0)
+        canvas.pack(fill='both', expand=True)
+        canvas.create_rectangle(
+            pad // 2,
+            pad // 2,
+            region.width + pad * 1.5,
+            region.height + pad * 1.5,
+            outline=color,
+            width=width,
+        )
+        self._windows[hid] = win
+        if seconds > 0:
+            self._root.after(int(seconds * 1000), lambda: self._destroy(hid))
+
+    def _destroy(self, hid):
+        win = self._windows.pop(hid, None)
+        if win is not None:
+            win.destroy()
+
+    def clear(self, key: str):
+        for hid in self._keys.pop(key, []):
+            self._call(self._destroy, hid)
+
+    def clear_all(self):
+        self._keys.clear()
+        for hid in list(self._windows):
+            self._call(self._destroy, hid)
+
+    # ---- region selection ---------------------------------------------------
+    def select_region(
+        self, message: str, bounds: Region, timeout: float = 300
+    ) -> Region | None:
+        done = threading.Event()
+        result: dict = {}
+        self._call(self._select, message, bounds, result, done)
+        done.wait(timeout)
+        return result.get('region')
+
+    def _select(self, message, bounds: Region, result, done):
+        import tkinter as tk
+
+        win = tk.Toplevel(self._root)
+        win.overrideredirect(True)
+        win.attributes('-topmost', True)
+        win.attributes('-alpha', 0.3)
+        win.geometry(f'{bounds.width}x{bounds.height}+{bounds.x}+{bounds.y}')
+        canvas = tk.Canvas(
+            win, bg='black', cursor='cross', highlightthickness=0
+        )
+        canvas.pack(fill='both', expand=True)
+        canvas.create_text(
+            bounds.width // 2,
+            40,
+            text=message or 'Select a region (ESC to cancel)',
+            fill='white',
+            font=('Segoe UI', 18, 'bold'),
+        )
+        state = {'start': None, 'rect': None}
+
+        def press(e):
+            state['start'] = (e.x, e.y)
+            state['rect'] = canvas.create_rectangle(
+                e.x, e.y, e.x, e.y, outline='red', width=3
+            )
+
+        def drag(e):
+            if state['rect']:
+                sx, sy = state['start']
+                canvas.coords(state['rect'], sx, sy, e.x, e.y)
+
+        def release(e):
+            if state['start']:
+                sx, sy = state['start']
+                x1, x2 = sorted((sx, e.x))
+                y1, y2 = sorted((sy, e.y))
+                if x2 - x1 > 0 and y2 - y1 > 0:
+                    result['region'] = Region(
+                        bounds.x + x1, bounds.y + y1, x2 - x1, y2 - y1
+                    )
+            finish()
+
+        def finish(_=None):
+            win.destroy()
+            done.set()
+
+        canvas.bind('<ButtonPress-1>', press)
+        canvas.bind('<B1-Motion>', drag)
+        canvas.bind('<ButtonRelease-1>', release)
+        win.bind('<Escape>', finish)
+        win.focus_force()

robotframework_desktop-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: robotframework-desktop
+Version: 0.1.0
+Summary: Robot Framework library for Windows desktop automation with hybrid image (pyautogui) and UI Automation (pywinauto) engines.
+License: Apache-2.0
+Keywords: robotframework,desktop,automation,pyautogui,pywinauto,uia,wpf,winforms
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: robotframework>=6.1
+Requires-Dist: robotframework-pythonlibcore>=4.2
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: pillow>=10.0
+Requires-Dist: mss>=9.0
+Requires-Dist: pywinauto>=0.6.8
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: rapidocr>=3.0
+Requires-Dist: onnxruntime>=1.17
+Provides-Extra: ocr
+Requires-Dist: rapidocr>=3.0; extra == "ocr"
+Requires-Dist: onnxruntime>=1.17; extra == "ocr"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: rapidocr>=3.0; extra == "dev"
+Requires-Dist: onnxruntime>=1.17; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Requires-Dist: blue>=0.9; extra == "dev"
+
+<div align="center">
+
+# 🖥️ robotframework-desktop
+
+**Hybrid Windows desktop automation for [Robot Framework](https://robotframework.org)**
+Image recognition · UI Automation · OCR — one keyword set, chosen by the locator.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
+![Robot Framework](https://img.shields.io/badge/Robot%20Framework-6.1%2B-000000?logo=robotframework&logoColor=white)
+![Platform](https://img.shields.io/badge/platform-Windows-0078D6?logo=windows&logoColor=white)
+![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![Code style: blue](https://img.shields.io/badge/code%20style-blue-1f6feb)
+
+[Install](#-install) · [Quick start](#-quick-start) · [Locators](#-locators) · [YAML locators](#-locators-in-a-yaml-file) · [OCR](#-ocr) · [Keywords](docs/DesktopLibrary.html)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🔀 **Hybrid keywords** – `Click`, `Input Text`, `Drag And Drop`, ... work with images, UI elements or regions; the engine is picked from the `element` argument.
+- 🖼️ **Image recognition** – pyautogui + OpenCV, per-call similarity, multiple candidate images, offsets and search regions.
+- 🌳 **UI Automation** – pywinauto (`uia` and `win32` backends) for WPF, WinForms, UWP and Win32 apps.
+- 🔤 **OCR** – [RapidOCR](https://github.com/RapidAI/RapidOCR) on onnxruntime, models bundled, **no external binary**; accent and case insensitive text search.
+- ⏳ **Busy cursor aware** – actions wait automatically while the app shows the busy cursor.
+- 🧩 **SikuliLibrary compatible** – implements all its actions, plus UIA keywords (`Attach To Window`, `Get Element Text`, `Set Element Value`, `Select Combobox Item`, ...).
+
+## 📦 Install
+
+```bash
+pip install robotframework-desktop          # core
+pip install robotframework-desktop[ocr]     # + OCR (rapidocr + onnxruntime)
+```
+
+## 🚀 Quick start
+
+```robot
+*** Settings ***
+Library    DesktopLibrary    image_paths=${CURDIR}/images;${CURDIR}/shared    similarity=0.6
+
+*** Test Cases ***
+Write In Notepad
+    Open Application     notepad.exe
+    Attach To Window     name_re:.*Notepad
+    Input Text           class:Edit    Hello
+    Click                ${{ {"path": ["save.png", "save_dark.png"], "similarity": 0.85} }}
+    Wait Until Screen Contain    done.png    10s
+    [Teardown]    Close Application    notepad.exe
+```
+
+> [!TIP]
+> Relative image paths are searched in the `image_paths` folders (in order, extendable with `Add Image Path`) and then in the current working directory. The extension can be omitted.
+
+## 🎯 Locators
+
+| Locator | Engine |
+|---|---|
+| `save.png` · `save.png=0.85` · `image:C:/refs/save.png` | 🖼️ Image |
+| `{"path": [...], "similarity": 0.8, "offset": {x, y}, "region": {x, y, width, height}}` | 🖼️ Image |
+| `automation_id:btnSave` · `name:OK AND control_type:Button` | 🌳 UIA |
+| `win32:class:Button` · `{"name": "Save", "backend": "win32"}` | 🌳 Win32 |
+| `{"automation_id": "btnSave", "offset": {"x": 5, "y": 0}}` | 🌳 UIA |
+| `[x, y, w, h]` · `{"region": {...}}` · region/match returned by keywords | 📐 Coordinates |
+
+## 🗂️ Locators in a YAML file
+
+Keep all element locators in one variable file ([full example](tests/atest/elements.yml)):
+
+```yaml
+APP:
+  BTN_SAVE: "automation_id:btnSave"
+  TXT_NAME:
+    automation_id: txtName
+    control_type: Edit
+  BTN_SAVE_WIN32:
+    name: Save
+    class_name_re: ".*BUTTON.*"
+    backend: win32
+  IMG_TARGET_OFFSET:
+    path: target.png
+    offset:
+      x: 30
+      y: 20
+  IMG_IN_REGION:
+    path: save.png
+    region:
+      x: 0
+      y: 0
+      width: 800
+      height: 600
+```
+
+```robot
+*** Settings ***
+Library      DesktopLibrary
+Variables    elements.yml          # requires PyYAML
+
+*** Test Cases ***
+Save
+    Input Text    ${APP.TXT_NAME}    Robot
+    Click         ${APP.BTN_SAVE}
+    Click         ${APP.IMG_TARGET_OFFSET}
+```
+
+## 🔤 OCR
+
+No language setup needed — the default RapidOCR models read Latin text (accented letters may come out unaccented, so matching ignores accents and case).
+
+```robot
+${text}=    Get Text    automation_id:lblStatus
+${text}=    Read Text From Region    [10, 400, 300, 30]
+Click Text    Clear
+Set ROI    [0, 0, 600, 400]
+Region Click Text    Clear
+```
+
+## 🔁 Looping over elements
+
+```robot
+@{items}=    Find Elements    control_type:ListItem          # [] when nothing is found
+FOR    ${item}    IN    @{items}
+    ${text}=    Get Element Text    ${item}
+    IF    $text == "Item 3"    Click    ${item}
+END
+@{icons}=    Find Elements    icon.png    sort_by=column    min_count=3
+@{rows}=     Find Child Elements    automation_id:grid    control_type:DataItem    depth=1
+```
+
+## ⏳ Busy cursor handling
+
+Action keywords wait while the cursor is busy (`wait` / `appstarting`) until it stays normal for 0.5 s — **before** searching, before acting and **after** the action (watched for 0.2 s). On timeout (default 30 s) the keyword fails, or only warns with `busy_cursor_fail=False` / `ignore_busy_error=True`. Use `show_warnings=False` to log warnings as INFO.
+
+```robot
+Library    DesktopLibrary    busy_cursor_timeout=1 min    busy_cursor_after_delay=0.3s
+
+Click    automation_id:btnLoad    ignore_busy_error=True
+Set Busy Cursor Wait     False
+Set Busy Cursor Types    wait,appstarting,custom
+Wait Until Cursor Is Not Busy    2 min
+${cursor}=    Get Current Cursor Type
+```
+
+## 📚 Documentation
+
+Full keyword reference: **[docs/DesktopLibrary.html](docs/DesktopLibrary.html)** (`just docs` to regenerate).
+
+## 🛠️ Development
+
+Requires [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just) (PowerShell recipes).
+
+| Command | Description |
+|---|---|
+| `just setup` | Create `.venv` and install the library (editable + dev deps) |
+| `just fmt` | Format code with [blue](https://github.com/grantjenks/blue) |
+| `just test` | Unit tests (pytest) |
+| `just atest` | Acceptance tests (Robot Framework) |
+| `just docs` | Regenerate libdoc |
+| `just build` | Build both wheels |
+| `just build-full` | `dist/full` – OCR deps required |
+| `just build-no-ocr` | `dist/no-ocr` – OCR optional (`[ocr]` extra) |
+| `just check` | Show dependencies of the built wheels |
+
+### Release
+
+CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) runs lint, unit and acceptance tests on every push and pull request.
+To publish a release, bump `version` in `pyproject.toml`, then:
+
+```powershell
+git tag v0.2.0
+git push --tags
+```
+
+[.github/workflows/release.yml](.github/workflows/release.yml) runs the tests, builds both wheels and creates a GitHub Release with them attached:
+
+- `robotframework-desktop` - OCR optional (`[ocr]` extra)
+- `robotframework-desktop-full` - OCR deps required
+
+> [!WARNING]
+> The acceptance suite launches a small WinForms app ([tests/app/SampleApp.ps1](tests/app/SampleApp.ps1)) and generates its reference images at runtime. **Don't use the mouse or keyboard while it runs.**
+
+## 📄 License
+
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)

robotframework_desktop-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+DesktopLibrary/__init__.py,sha256=v6_IvClm3ij_ve6ffFA4TfP2Em3nOnQkH_Rl-BcRa2U,11729
+DesktopLibrary/context.py,sha256=Myqoe-ACr91XP3g41YxmUjfT951JI6P5gebiSZz_QzA,10125
+DesktopLibrary/cursor.py,sha256=ACpv5kZgEZVsqL88LehMEB2iZhF3QT-eGrMgmfJKRGk,8573
+DesktopLibrary/geometry.py,sha256=C4M6tLB16iQ-Vy9VU3m63SnVNWdRCA6f6xxxw6O3UcE,6722
+DesktopLibrary/locator.py,sha256=ZjeT7MBbCbkgKToNzhF3h0V176PeUvI_ib_WlgZ_8PA,7383
+DesktopLibrary/overlay.py,sha256=FFTmMPOJcXqv3EK_Pp7DKZuYJczjPYJGqrqydIrpjxM,5707
+DesktopLibrary/engines/__init__.py,sha256=H2e7e6Q0aAqOcKVTnjnv_AucouoZuQHD_oVJvMpUpTk,139
+DesktopLibrary/engines/image.py,sha256=oEj0vSe0recQX4cFSlzJ5ec__9yR8vAPUFQwa1ZJJp4,6152
+DesktopLibrary/engines/ui.py,sha256=u9S--vIiE-JDfl6YGrw1Uvu4mRJHzRtHn2b6nn-L69o,6210
+DesktopLibrary/keywords/__init__.py,sha256=DvYDv9uKyoa6LzTF9QGCidALVEGteTqTxnXtK_YMbEo,608
+DesktopLibrary/keywords/application.py,sha256=4em6Bjyy802bBSe56TbBzg73Wr5iNMW5T4lpw49ZGB8,5073
+DesktopLibrary/keywords/base.py,sha256=nOzEGtOpGgzSVIjzCqKBALOJLtJG0lRFFEN9fNYaMEE,2986
+DesktopLibrary/keywords/config.py,sha256=DPaLerkHU0Q8QPmgmxqvz9cvbLfH2b3WP12iEoGv9OU,4901
+DesktopLibrary/keywords/cursor.py,sha256=svRADiYSFX2N4woxK1KtxgMtQDhx6N1yTMEGp6wy6HA,7689
+DesktopLibrary/keywords/element.py,sha256=ieAIUh2wcHdfr5oCn61nGqEzQZSjeh8SH47NaRgz4Wc,8991
+DesktopLibrary/keywords/find.py,sha256=SxK25gFYCbuSPSRfVggZfkZlcIyV8NjqHlISt7Sl010,5446
+DesktopLibrary/keywords/keyboard.py,sha256=11lPEFTLxeNSZGRD7YBli2wplYzSYfbRfxZDVjKWTPk,4756
+DesktopLibrary/keywords/mouse.py,sha256=zZDX2mrHCQfDX_B4GOwKkwiRMecSevX-YC_fdJXnAI0,12314
+DesktopLibrary/keywords/ocr.py,sha256=zXy9HbetD5vNB6zd95hrqpFlSLdMQHmaK51rm50u8vA,5442
+DesktopLibrary/keywords/region.py,sha256=CTwysDYAx7d2WYKJuML20r5WtnqkqM3anEZSkavUYHQ,10308
+DesktopLibrary/keywords/wait.py,sha256=DIfbUrgxicOTFmvf7DOuAYBne2BkFbw58pdMaV7YEgM,6523
+robotframework_desktop-0.1.0.dist-info/METADATA,sha256=SvMaaX--oZT6jFLHh_HvKyy4kSGBQjDLPUqFyQitg5s,8437
+robotframework_desktop-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+robotframework_desktop-0.1.0.dist-info/top_level.txt,sha256=5eYvVeCi3VKx9Lg4zk4yqN9m5A60Nxlima2FQIDCLKo,15
+robotframework_desktop-0.1.0.dist-info/RECORD,,

robotframework_desktop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

robotframework_desktop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+DesktopLibrary