AutoMonkey 0.2.1__tar.gz → 0.4.2__tar.gz

{AutoMonkey-0.2.1 → automonkey-0.4.2}/AutoMonkey.egg-info/PKG-INFO

@@ -1,27 +1,49 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: AutoMonkey
-Version: 0.2.1
+Version: 0.4.2
 Summary: Python Automation using Mouse and Keyboard, for the masses
-Home-page: https://github.com/MihailCosmin/automonkey
-Author: Mihail-Cosmin Munteanu
 Author-email: Mihail-Cosmin Munteanu <munteanumihailcosmin@gmail.com>
-License: GNU General Public License v3
+License: GNU General Public License v3 (GPLv3)
 Project-URL: Homepage, https://github.com/MihailCosmin/AutoMonkey
 Project-URL: Bug Tracker, https://github.com/MihailCosmin/AutoMonkey/issues
 Keywords: automonkey
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.rst
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pytesseract>=0.3.9
+Requires-Dist: numpy
+Requires-Dist: keyboard>=0.13.5
+Requires-Dist: clipboard>=0.0.4
+Requires-Dist: opencv-python
+Requires-Dist: pillow>=10.3.0
+Requires-Dist: screeninfo>=0.8
+Requires-Dist: pyperclip==1.8.2
+Requires-Dist: PyScreeze>=0.1.27
+Requires-Dist: pywin32>=303; sys_platform == "win32"
+Requires-Dist: pywin32-ctypes>=0.2.0; sys_platform == "win32"
+Requires-Dist: pywinauto>=0.6.8; sys_platform == "win32"
+Provides-Extra: ai
+Requires-Dist: mcp>=2.0; extra == "ai"
+Dynamic: license-file
 
 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/donate/?hosted_button_id=5Q6TUMXS2QJW4)
 [![](https://snyk.io/test/github/MihailCosmin/AutoMonkey/badge.svg)](https://snyk.io/test/github/MihailCosmin/AutoMonkey)
-[![HitCount](https://hits.dwyl.com/MihailCosmin/AutoMonkey.svg?style=flat-square&show=unique)](http://hits.dwyl.com/MihailCosmin/AutoMonkey)
+[![visitors](https://visitor-badge.laobi.icu/badge?page_id=MihailCosmin.AutoMonkey)](https://github.com/MihailCosmin/AutoMonkey)
 [![build](https://github.com/MihailCosmin/AutoMonkey/actions/workflows/python-package.yml/badge.svg)](https://github.com/MihailCosmin/AutoMonkey/actions/workflows/python-package.yml)
-[![Code Climate](https://codeclimate.com/github/MihailCosmin/AutoMonkey/badges/gpa.svg)](https://codeclimate.com/github/MihailCosmin/AutoMonkey)
 
 # AutoMonkey
 <img alt="AutoMonkey" src="https://github.com/MihailCosmin/AutoMonkey/raw/06181954fa23605583d61843226f5f3997157435/img/monkey.ico" width="100px" height="100px"/>
@@ -57,6 +79,7 @@ pip install git+https://github.com/MihailCosmin/AutoMonkey
 - opencv-python
 - numpy
 - pytesseract
+- <a href="https://github.com/pywinauto/pywinauto">pywinauto</a> (Windows only, for the control actions)
 
 # Usage
 Main function to be used is "chain"  
@@ -327,8 +350,159 @@ or
         )
     ```
 
-# Roadmap
-1. Check if possible to add <a href="https://github.com/pywinauto/pywinauto">pyautowin</a> functionality
+6. Control actions (Windows: <a href="https://github.com/pywinauto/pywinauto">pywinauto</a>; Linux: AT-SPI; macOS: not implemented yet)
+
+    These find buttons, text boxes and menus through the OS accessibility tree instead of
+    coordinates or images, so they keep working when the resolution, theme or window position changes.
+    Same function names and arguments on both OSes - a `chain` script using them needs no changes
+    to run on either one; only the `backend` argument's value differs (`"uia"`/`"win32"` on Windows,
+    `"atspi"` on Linux).
+
+    Every function takes the window title (regex, matched anywhere in the title, like focus/close)
+    and a control:
+    * a "best match" name: `"Save"`, `"SaveButton"`, `"Edit"`
+    * or a dict of search criteria: `{"title": "Save", "control_type": "Button"}`, `{"auto_id": "num7Button"}`
+
+    6.1 Windows (pywinauto)
+
+    Optional for all: `backend="uia"` (default, modern apps) or `"win32"` (older apps), `timeout=10` seconds.
+
+    In chain the target is a tuple of arguments or a dict of keyword arguments:
+
+    ```python
+        from automonkey import chain, list_controls
+
+        list_controls("Calculator")  # prints the controls and the names you can use
+
+        chain(
+            dict(open_app="calc", wait=1),
+            dict(wait_control="Calculator"),
+            dict(click_control=("Calculator", {"auto_id": "num7Button"})),
+            dict(click_control=("Calculator", {"auto_id": "plusButton"})),
+            dict(click_control=("Calculator", {"auto_id": "num5Button"})),
+            dict(click_control=dict(window="Calculator", control={"auto_id": "equalButton"}, invoke=True)),
+            dict(get_control_text=("Calculator", {"auto_id": "CalculatorResults"})),  # copied to the clipboard
+        )
+
+        chain(
+            dict(open_app="notepad", wait=1),
+            dict(type_in_control=dict(window=" - Notepad$", control={"control_type": "Document"}, text="Hello (world)!")),
+            dict(select_menu=(" - Notepad$", "Edit->Select all")),
+        )
+    ```
+
+    Available functions:
+    * start_app - start an application with pywinauto
+    * click_control, double_click_control, right_click_control - `invoke=True` presses it without moving the mouse
+    * type_in_control - types the text as it is; `literal=False` for pywinauto key syntax (`{ENTER}`, `^a`);
+      `pause=0.05` if a slow app loses characters
+    * set_control_text, get_control_text
+    * select_menu - path separated by `->`, e.g. `"File->Save As..."`
+    * select_item - item of a combo box / list
+    * check_control, uncheck_control
+    * wait_control, control_exists
+    * list_controls
+    * get_window, get_control - return the pywinauto objects for anything else
+
+    6.2 Linux (AT-SPI)
+
+    Setup (distro packages, not pip - PyGObject needs system build dependencies pip can't
+    guarantee): on Debian/Ubuntu/Raspberry Pi OS,
+
+    ```bash
+        sudo apt-get install python3-gi gir1.2-atspi-2.0 at-spi2-core
+        gsettings set org.gnome.desktop.interface toolkit-accessibility true
+    ```
+
+    The `toolkit-accessibility` key only affects apps started *after* it's enabled -
+    restart anything already running. Apps must also not have `NO_AT_BRIDGE=1` set in
+    their environment, which silently disables AT-SPI registration.
+
+    Not every app exposes an accessibility tree: GTK, GNOME and LibreOffice apps and
+    Firefox work out of the box; Qt apps need `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1` in
+    their environment before they start; Chrome/Electron apps need the
+    `--force-renderer-accessibility` flag; self-drawn/custom-rendered UIs (games,
+    canvas-based apps) can't expose one at all.
+
+    `control_type` maps to an AT-SPI role, not quite the same names pywinauto uses on
+    Windows - confirmed against real GTK widgets, not just the spec (a push button's role
+    is `BUTTON`, not `PUSH_BUTTON`, for instance):
+
+    | control_type | AT-SPI role(s) |
+    | --- | --- |
+    | `Button` | `BUTTON`, `PUSH_BUTTON`, `TOGGLE_BUTTON` |
+    | `CheckBox` | `CHECK_BOX` |
+    | `RadioButton` | `RADIO_BUTTON` |
+    | `ComboBox` | `COMBO_BOX` |
+    | `Edit` | `TEXT`, `ENTRY`, `PASSWORD_TEXT` (also a plain GTK text editor's main area - see note below) |
+    | `Document` | `DOCUMENT_TEXT`, `DOCUMENT_FRAME`, `DOCUMENT_WEB`, ... (LibreOffice/WebKit-style content) |
+    | `Static` | `LABEL` |
+    | `MenuItem` | `MENU_ITEM`, `CHECK_MENU_ITEM`, `RADIO_MENU_ITEM`, `TEAROFF_MENU_ITEM` |
+    | `Menu` | `MENU`, `POPUP_MENU` |
+    | `MenuBar` | `MENU_BAR` |
+    | `List` | `LIST`, `LIST_BOX` |
+    | `ListItem` | `LIST_ITEM` |
+    | `Tab` / `TabControl` | `PAGE_TAB` / `PAGE_TAB_LIST` |
+    | `Window` / `Dialog` | `FRAME` / `DIALOG` |
+
+    `auto_id` matches the AT-SPI accessible-id or an `"id"` attribute if the app sets one
+    (most GTK apps don't), falling back to the accessible name otherwise.
+
+    Known Wayland limits: AT-SPI tree reading and actions (`invoke=True`, `check_control`,
+    `select_menu`, ...) work the same as on X11/Xwayland. What doesn't: mouse clicks
+    (`click_control(invoke=False)`) and keyboard injection (`type_in_control`) only reach
+    apps running under Xwayland - a native-Wayland client never receives them at all, no
+    matter what has focus (confirmed directly: the identical app forced through Xwayland
+    via `GDK_BACKEND=x11` works, the native-Wayland instance silently doesn't). Raising/
+    activating a window doesn't work either. `click_control(invoke=False)` detects a
+    Wayland session and falls back to `invoke=True` with a warning; `type_in_control` has
+    no such fallback - use `invoke=True`-based actions where possible, or run the target
+    app under Xwayland (`GDK_BACKEND=x11` for GTK apps) if it must be driven by mouse/
+    keyboard injection on Wayland.
+
+    ```python
+        from automonkey import chain, list_controls
+
+        list_controls("Calculator")  # prints the controls and the names you can use
+
+        chain(
+            # a short wait after each click matters here: Atspi.Action.do_action() returns
+            # once the D-Bus call completes, not once the app has processed the resulting
+            # GTK signal - clicking straight through with no pause silently drops presses
+            # (confirmed directly while building this).
+            dict(start_app="gnome-calculator", wait=1),
+            dict(wait_control="Calculator"),
+            dict(click_control=dict(window="Calculator", control={"title": "7", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "+", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "5", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "=", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(get_control_text=("Calculator", {"control_type": "Edit"})),  # copied to the clipboard
+        )
+
+        chain(
+            # control_type "Edit" (AT-SPI role "text"), not "Document": gnome-text-editor's
+            # main area is a plain GtkSourceView widget, same as most GTK text editors -
+            # "Document*" roles are for LibreOffice/WebKit-style content, confirmed against
+            # a GtkSourceView-based app while building this.
+            dict(start_app="gnome-text-editor", wait=1),
+            dict(type_in_control=dict(window="Text Editor", control={"control_type": "Edit"}, text="Hello (world)!")),
+            dict(get_control_text=("Text Editor", {"control_type": "Edit"})),  # copied to the clipboard
+        )
+    ```
+
+    `select_menu` isn't shown against gnome-text-editor above: it's a modern GNOME app
+    with no traditional File/Edit menu bar at all (confirmed - zero AT-SPI menu-role nodes
+    anywhere in its tree), not an AT-SPI limitation. It works the same way as on Windows
+    against any app that does have one, e.g. `select_menu("Mousepad", "File->Save As...")`.
+
+    Same available functions as the Windows list above (`backend="atspi"`, the default on
+    Linux, instead of `"uia"`/`"win32"`); `get_window`/`get_control` return `Atspi.Accessible`
+    objects instead of pywinauto wrappers for anything not covered here.
+
+    See `pywinauto_for_linux.md` in the repo for the full implementation notes (role
+    mapping, best-match lookup, the AT-SPI-bus-down detection, known gotchas found while
+    building this) if you need to go beyond what's documented above.
+
 
 # Frequently Asked Questions:
 

{AutoMonkey-0.2.1 → automonkey-0.4.2}/AutoMonkey.egg-info/SOURCES.txt

@@ -18,13 +18,24 @@ AutoMonkey.egg-info/requires.txt
 AutoMonkey.egg-info/top_level.txt
 automonkey/__init__.py
 automonkey/app_funcs.py
+automonkey/atspi_funcs.py
 automonkey/automonkey.py
 automonkey/constants.py
 automonkey/exceptions.py
 automonkey/img_funcs.py
+automonkey/key_funcs.py
 automonkey/mouse_funcs.py
 automonkey/mouse_tracker.py
+automonkey/pywinauto_funcs.py
 automonkey/utils.py
+automonkey/ai/__init__.py
+automonkey/ai/__main__.py
+automonkey/ai/mcp_launch.py
+automonkey/ai/mcp_server.py
+automonkey/ai/ocr.py
+automonkey/ai/screen.py
+automonkey/ai/script.py
+automonkey/ai/windows.py
 docs/Makefile
 docs/authors.rst
 docs/conf.py
@@ -34,4 +45,10 @@ docs/index.rst
 docs/installation.rst
 docs/make.bat
 docs/readme.rst
-docs/usage.rst
+docs/usage.rst
+tests/test_ai.py
+tests/test_atspi_funcs.py
+tests/test_atspi_integration.py
+tests/test_key_funcs.py
+tests/test_mcp_launch.py
+tests/test_pywinauto_funcs.py

automonkey-0.4.2/AutoMonkey.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+automonkey-ai = automonkey.ai.__main__:main
+automonkey-mcp = automonkey.ai.mcp_server:main

{AutoMonkey-0.2.1 → automonkey-0.4.2}/AutoMonkey.egg-info/requires.txt

@@ -1,10 +1,10 @@
-pyautogui>=0.9.53
+pyautogui>=0.9.54
 pytesseract>=0.3.9
-numpy>=1.21.5
+numpy
 keyboard>=0.13.5
 clipboard>=0.0.4
-opencv-python==4.5.5.62
-pillow>=9.0.1
+opencv-python
+pillow>=10.3.0
 screeninfo>=0.8
 pyperclip==1.8.2
 PyScreeze>=0.1.27
@@ -12,3 +12,7 @@ PyScreeze>=0.1.27
 [:sys_platform == "win32"]
 pywin32>=303
 pywin32-ctypes>=0.2.0
+pywinauto>=0.6.8
+
+[ai]
+mcp>=2.0

automonkey-0.4.2/HISTORY.rst

@@ -0,0 +1,25 @@
+=======
+History
+=======
+
+0.4.0 (2026-10-13)
+------------------
+
+* Add a Linux backend (``automonkey/atspi_funcs.py``) for the control actions
+  (``click_control``, ``type_in_control``, ``get_control_text``, ``select_menu``, ...),
+  using AT-SPI via ``gi.repository.Atspi`` (``python3-gi``, ``gir1.2-atspi-2.0``,
+  ``at-spi2-core`` - distro packages, not pip). Same function names and signatures as
+  the Windows ``pywinauto_funcs.py`` backend, selected automatically by platform, so a
+  ``chain`` script using the control actions needs no changes to run on either OS.
+* Known limits on Wayland: mouse clicks and keyboard injection into a control only
+  reach apps running under Xwayland, not native Wayland clients; raising/activating a
+  window doesn't work either. ``click_control(invoke=False)`` falls back to the AT-SPI
+  action and warns when this is detected. See the README's Control actions section.
+* Fix: ``copy()`` (used by ``get_control_text``/clipboard helpers) no longer crashes the
+  whole call when one of its two clipboard backends raises - pyperclip's auto-detected
+  "gtk" backend does, once ``gi.repository`` has been imported in-process.
+
+0.0.2 (2022-11-06)
+------------------
+
+* First release on PyPI.

AutoMonkey-0.2.1/README.md → automonkey-0.4.2/PKG-INFO

@@ -1,8 +1,49 @@
+Metadata-Version: 2.4
+Name: AutoMonkey
+Version: 0.4.2
+Summary: Python Automation using Mouse and Keyboard, for the masses
+Author-email: Mihail-Cosmin Munteanu <munteanumihailcosmin@gmail.com>
+License: GNU General Public License v3 (GPLv3)
+Project-URL: Homepage, https://github.com/MihailCosmin/AutoMonkey
+Project-URL: Bug Tracker, https://github.com/MihailCosmin/AutoMonkey/issues
+Keywords: automonkey
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pytesseract>=0.3.9
+Requires-Dist: numpy
+Requires-Dist: keyboard>=0.13.5
+Requires-Dist: clipboard>=0.0.4
+Requires-Dist: opencv-python
+Requires-Dist: pillow>=10.3.0
+Requires-Dist: screeninfo>=0.8
+Requires-Dist: pyperclip==1.8.2
+Requires-Dist: PyScreeze>=0.1.27
+Requires-Dist: pywin32>=303; sys_platform == "win32"
+Requires-Dist: pywin32-ctypes>=0.2.0; sys_platform == "win32"
+Requires-Dist: pywinauto>=0.6.8; sys_platform == "win32"
+Provides-Extra: ai
+Requires-Dist: mcp>=2.0; extra == "ai"
+Dynamic: license-file
+
 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/donate/?hosted_button_id=5Q6TUMXS2QJW4)
 [![](https://snyk.io/test/github/MihailCosmin/AutoMonkey/badge.svg)](https://snyk.io/test/github/MihailCosmin/AutoMonkey)
-[![HitCount](https://hits.dwyl.com/MihailCosmin/AutoMonkey.svg?style=flat-square&show=unique)](http://hits.dwyl.com/MihailCosmin/AutoMonkey)
+[![visitors](https://visitor-badge.laobi.icu/badge?page_id=MihailCosmin.AutoMonkey)](https://github.com/MihailCosmin/AutoMonkey)
 [![build](https://github.com/MihailCosmin/AutoMonkey/actions/workflows/python-package.yml/badge.svg)](https://github.com/MihailCosmin/AutoMonkey/actions/workflows/python-package.yml)
-[![Code Climate](https://codeclimate.com/github/MihailCosmin/AutoMonkey/badges/gpa.svg)](https://codeclimate.com/github/MihailCosmin/AutoMonkey)
 
 # AutoMonkey
 <img alt="AutoMonkey" src="https://github.com/MihailCosmin/AutoMonkey/raw/06181954fa23605583d61843226f5f3997157435/img/monkey.ico" width="100px" height="100px"/>
@@ -38,6 +79,7 @@ pip install git+https://github.com/MihailCosmin/AutoMonkey
 - opencv-python
 - numpy
 - pytesseract
+- <a href="https://github.com/pywinauto/pywinauto">pywinauto</a> (Windows only, for the control actions)
 
 # Usage
 Main function to be used is "chain"  
@@ -308,8 +350,159 @@ or
         )
     ```
 
-# Roadmap
-1. Check if possible to add <a href="https://github.com/pywinauto/pywinauto">pyautowin</a> functionality
+6. Control actions (Windows: <a href="https://github.com/pywinauto/pywinauto">pywinauto</a>; Linux: AT-SPI; macOS: not implemented yet)
+
+    These find buttons, text boxes and menus through the OS accessibility tree instead of
+    coordinates or images, so they keep working when the resolution, theme or window position changes.
+    Same function names and arguments on both OSes - a `chain` script using them needs no changes
+    to run on either one; only the `backend` argument's value differs (`"uia"`/`"win32"` on Windows,
+    `"atspi"` on Linux).
+
+    Every function takes the window title (regex, matched anywhere in the title, like focus/close)
+    and a control:
+    * a "best match" name: `"Save"`, `"SaveButton"`, `"Edit"`
+    * or a dict of search criteria: `{"title": "Save", "control_type": "Button"}`, `{"auto_id": "num7Button"}`
+
+    6.1 Windows (pywinauto)
+
+    Optional for all: `backend="uia"` (default, modern apps) or `"win32"` (older apps), `timeout=10` seconds.
+
+    In chain the target is a tuple of arguments or a dict of keyword arguments:
+
+    ```python
+        from automonkey import chain, list_controls
+
+        list_controls("Calculator")  # prints the controls and the names you can use
+
+        chain(
+            dict(open_app="calc", wait=1),
+            dict(wait_control="Calculator"),
+            dict(click_control=("Calculator", {"auto_id": "num7Button"})),
+            dict(click_control=("Calculator", {"auto_id": "plusButton"})),
+            dict(click_control=("Calculator", {"auto_id": "num5Button"})),
+            dict(click_control=dict(window="Calculator", control={"auto_id": "equalButton"}, invoke=True)),
+            dict(get_control_text=("Calculator", {"auto_id": "CalculatorResults"})),  # copied to the clipboard
+        )
+
+        chain(
+            dict(open_app="notepad", wait=1),
+            dict(type_in_control=dict(window=" - Notepad$", control={"control_type": "Document"}, text="Hello (world)!")),
+            dict(select_menu=(" - Notepad$", "Edit->Select all")),
+        )
+    ```
+
+    Available functions:
+    * start_app - start an application with pywinauto
+    * click_control, double_click_control, right_click_control - `invoke=True` presses it without moving the mouse
+    * type_in_control - types the text as it is; `literal=False` for pywinauto key syntax (`{ENTER}`, `^a`);
+      `pause=0.05` if a slow app loses characters
+    * set_control_text, get_control_text
+    * select_menu - path separated by `->`, e.g. `"File->Save As..."`
+    * select_item - item of a combo box / list
+    * check_control, uncheck_control
+    * wait_control, control_exists
+    * list_controls
+    * get_window, get_control - return the pywinauto objects for anything else
+
+    6.2 Linux (AT-SPI)
+
+    Setup (distro packages, not pip - PyGObject needs system build dependencies pip can't
+    guarantee): on Debian/Ubuntu/Raspberry Pi OS,
+
+    ```bash
+        sudo apt-get install python3-gi gir1.2-atspi-2.0 at-spi2-core
+        gsettings set org.gnome.desktop.interface toolkit-accessibility true
+    ```
+
+    The `toolkit-accessibility` key only affects apps started *after* it's enabled -
+    restart anything already running. Apps must also not have `NO_AT_BRIDGE=1` set in
+    their environment, which silently disables AT-SPI registration.
+
+    Not every app exposes an accessibility tree: GTK, GNOME and LibreOffice apps and
+    Firefox work out of the box; Qt apps need `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1` in
+    their environment before they start; Chrome/Electron apps need the
+    `--force-renderer-accessibility` flag; self-drawn/custom-rendered UIs (games,
+    canvas-based apps) can't expose one at all.
+
+    `control_type` maps to an AT-SPI role, not quite the same names pywinauto uses on
+    Windows - confirmed against real GTK widgets, not just the spec (a push button's role
+    is `BUTTON`, not `PUSH_BUTTON`, for instance):
+
+    | control_type | AT-SPI role(s) |
+    | --- | --- |
+    | `Button` | `BUTTON`, `PUSH_BUTTON`, `TOGGLE_BUTTON` |
+    | `CheckBox` | `CHECK_BOX` |
+    | `RadioButton` | `RADIO_BUTTON` |
+    | `ComboBox` | `COMBO_BOX` |
+    | `Edit` | `TEXT`, `ENTRY`, `PASSWORD_TEXT` (also a plain GTK text editor's main area - see note below) |
+    | `Document` | `DOCUMENT_TEXT`, `DOCUMENT_FRAME`, `DOCUMENT_WEB`, ... (LibreOffice/WebKit-style content) |
+    | `Static` | `LABEL` |
+    | `MenuItem` | `MENU_ITEM`, `CHECK_MENU_ITEM`, `RADIO_MENU_ITEM`, `TEAROFF_MENU_ITEM` |
+    | `Menu` | `MENU`, `POPUP_MENU` |
+    | `MenuBar` | `MENU_BAR` |
+    | `List` | `LIST`, `LIST_BOX` |
+    | `ListItem` | `LIST_ITEM` |
+    | `Tab` / `TabControl` | `PAGE_TAB` / `PAGE_TAB_LIST` |
+    | `Window` / `Dialog` | `FRAME` / `DIALOG` |
+
+    `auto_id` matches the AT-SPI accessible-id or an `"id"` attribute if the app sets one
+    (most GTK apps don't), falling back to the accessible name otherwise.
+
+    Known Wayland limits: AT-SPI tree reading and actions (`invoke=True`, `check_control`,
+    `select_menu`, ...) work the same as on X11/Xwayland. What doesn't: mouse clicks
+    (`click_control(invoke=False)`) and keyboard injection (`type_in_control`) only reach
+    apps running under Xwayland - a native-Wayland client never receives them at all, no
+    matter what has focus (confirmed directly: the identical app forced through Xwayland
+    via `GDK_BACKEND=x11` works, the native-Wayland instance silently doesn't). Raising/
+    activating a window doesn't work either. `click_control(invoke=False)` detects a
+    Wayland session and falls back to `invoke=True` with a warning; `type_in_control` has
+    no such fallback - use `invoke=True`-based actions where possible, or run the target
+    app under Xwayland (`GDK_BACKEND=x11` for GTK apps) if it must be driven by mouse/
+    keyboard injection on Wayland.
+
+    ```python
+        from automonkey import chain, list_controls
+
+        list_controls("Calculator")  # prints the controls and the names you can use
+
+        chain(
+            # a short wait after each click matters here: Atspi.Action.do_action() returns
+            # once the D-Bus call completes, not once the app has processed the resulting
+            # GTK signal - clicking straight through with no pause silently drops presses
+            # (confirmed directly while building this).
+            dict(start_app="gnome-calculator", wait=1),
+            dict(wait_control="Calculator"),
+            dict(click_control=dict(window="Calculator", control={"title": "7", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "+", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "5", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(click_control=dict(window="Calculator", control={"title": "=", "control_type": "Button"}, invoke=True), wait=0.3),
+            dict(get_control_text=("Calculator", {"control_type": "Edit"})),  # copied to the clipboard
+        )
+
+        chain(
+            # control_type "Edit" (AT-SPI role "text"), not "Document": gnome-text-editor's
+            # main area is a plain GtkSourceView widget, same as most GTK text editors -
+            # "Document*" roles are for LibreOffice/WebKit-style content, confirmed against
+            # a GtkSourceView-based app while building this.
+            dict(start_app="gnome-text-editor", wait=1),
+            dict(type_in_control=dict(window="Text Editor", control={"control_type": "Edit"}, text="Hello (world)!")),
+            dict(get_control_text=("Text Editor", {"control_type": "Edit"})),  # copied to the clipboard
+        )
+    ```
+
+    `select_menu` isn't shown against gnome-text-editor above: it's a modern GNOME app
+    with no traditional File/Edit menu bar at all (confirmed - zero AT-SPI menu-role nodes
+    anywhere in its tree), not an AT-SPI limitation. It works the same way as on Windows
+    against any app that does have one, e.g. `select_menu("Mousepad", "File->Save As...")`.
+
+    Same available functions as the Windows list above (`backend="atspi"`, the default on
+    Linux, instead of `"uia"`/`"win32"`); `get_window`/`get_control` return `Atspi.Accessible`
+    objects instead of pywinauto wrappers for anything not covered here.
+
+    See `pywinauto_for_linux.md` in the repo for the full implementation notes (role
+    mapping, best-match lookup, the AT-SPI-bus-down detection, known gotchas found while
+    building this) if you need to go beyond what's documented above.
+
 
 # Frequently Asked Questions: