pywingui 2.2.3

PyWinGUI GUI Automation Library for Windows Forms (Binary Distribution)

pywinGUI – Intelligent Windows GUI Automation Framework

pywinGUI is an enterprise-grade Windows GUI automation framework designed to automate complex desktop applications without relying on automation IDs.
It interacts with UI elements using label recognition, visual ordering, proximity matching, and intelligent fallbacks.

This framework powers automated form filling, radio/checkbox selection, dropdown interactions, button clicks, and active window keystrokes — using a simple dictionary payload.

---

🚀 Features

✅ Label-Based Text Input

• Fill fields using visible labels ("Surname:" : "Niranjan")
• Supports repeated labels (Label:01, Label:02)
• Matches nearest control by visual proximity

✅ Radio Button Automation

Supports:

• radioBtn:toggle:<name> – attribute-based match
• radioBtn:<name> – direct name match
• radioBtn:All_01 – global index based on visual order
• Group selection via "Label": "Option"

✅ Checkbox Handling

Three enterprise-level patterns:

• checkboxBtn:toggle:<name>
• checkboxBtn:left:<Label> – checkbox on the left
• checkboxBtn:right:<Label> – checkbox on the right

✅ Dropdown Selections

• dropdown:<Label> → selects matching option text

✅ Button Actions

• btn:OK
• btn:Save_01
• Any button name with optional suffixes

✅ Active Window Keystrokes

Send keystrokes directly to focused window:

"activeWindow:SendKeys_01": "{ENTER}"
"activeWindow:SendKeys_02": "[e-mail]"

Executed in numeric order.

✅ No Automation ID Required

Intelligent strategies:

• Label text matching
• Visual position sorting
• Nearest control search
• Repeated label disambiguation

---

📦 Installation

Requirements

• Python 3.9+
• Windows OS

---

📁 Project Structure

pywinGUI/
│
├── controller.py        # Main orchestrator for automation
├── actions.py           # Typing, clicking, selecting
├── selectors.py         # Label parsing and detection logic
├── readers.py           # (Optional) read/extract mode
├── utils.py             # Helpers, logging, fallback logic
├── README.md

---

🔧 Usage Example

1. Import the controller

from pywinGUI import controller1

2. Prepare your payload

payload = {

    # ---------------- TEXT FIELDS ----------------
    "Street:": "ValueStreet",
    "Date Of Birth:": "11/11/2025",
    "Title:": "Mr",
    "Forenames:": "ValueStreet",
    "Initials:": "GS",
    "Surname:": "ValueBuilding",

    # ---------------- RADIO BUTTONS ----------------
    "radioBtn:toggle:Female": True,
    "radioBtn:toggle:Male": True,
    "radioBtn:All_01": True,
    "radioBtn:All_02": True,
    "radioBtn:Report": True,
    "radioBtn:Admin Area": True,

    # ---------------- CHECKBOXES ----------------
    "checkboxBtn:toggle:Format": True,
    "checkboxBtn:toggle:Use Today's Date": True,
    "checkboxBtn:right:Inactive": True,
    "checkboxBtn:left:Services": True,
    "checkboxBtn:left:Work Type": True,

    # ---------------- DROPDOWNS ----------------
    "dropdown:Nationality": "India (IN)",
    "dropdown:Work Type": "ZNDRST2C",

    # ---------------- BUTTONS ----------------
    "btn:OK": True,
    "btn:OK_01": True,
    "btn:OK_02": True,

    # ---------------- BUTTONS ----------------
    "sleep": "5|5ms|millis|milliseconds|s|sec|secs|seconds",

    # ---------------- ACTIVE WINDOW SEND KEYS ----------------
    "activeWindow:SendKeys_01": "{ENTER}",
    "activeWindow:SendKeys_02": "[e-mail]",

    # ---------------- REPEATED LABELS ----------------
    "Start:01": "5",
    "End:01": "5",
    "Start:02": "1",
    "End:02": "1",
}

3. Execute

controller.fill_form_with_agent("Master Form [Org 01]", payload)

---

📘 Payload Reference Guide

📝 Text Fields

"Label:": "TextValue"

🔘 Radio Buttons

1. Toggle match

   "radioBtn:toggle:Male": True
   

2. Direct name

   "radioBtn:Council": True
   

3. Index-based

   "radioBtn:All_01": True
   

☑️ Checkboxes

Left of label:

"checkboxBtn:left:Services": True

Right of label:

"checkboxBtn:right:Inactive": True

Toggle attribute:

"checkboxBtn:toggle:Format": True

🔽 Dropdowns

"dropdown:Nationality": "India (IN)"

🟦 Buttons

"btn:OK": True
"btn:Save_01": True

⌨️ Active Window Keys

"activeWindow:SendKeys_01": "{TAB}"
"activeWindow:SendKeys_02": "[e-mail]"

---

Error handler

ERROR_HANDLERS = [
    {
        "code": 1405,
        "document": (
            "National Insurance number MUST be  unique.\r\n\r\nAnother core person has this NI number."
        ),
        "condition": "and",  # any | and
        "action": {
            "btn:OK": True,
            "NI Number:": "2345678",
            "btn:Create": True,
        },
    },
    {
        "code": 1404,
        "document": "National Insurance number is in an incorrect format.",
        "condition": "and",
        # "retry": 10,
        "action": {
            "btn:OK": True,
            "NI Number:": "WL187680C",
            "btn:Create": True,
        },
    },
]


def error_rules():
    return ERROR_HANDLERS


----------------------------------------------

confest.py

from error_engine import ErrorEngine
from error_rules import error_rules
from error_reader import get_error_document_text



# conftest.py
import pytest

@pytest.fixture(scope="session", autouse=True)
def register_error_engine():
    engine = ErrorEngine(
        rule_provider=error_rules,
        error_reader=lambda win: get_error_document_text(win, timeout=2.0),
    )

    controller.set_error_engine(engine)

standalone testing

from pywinGUI.controller import orchestrate, set_error_engine

from ..error_engine import ErrorEngine
from error_rules import error_rules
from ..error_reader import get_error_document_text

engine = ErrorEngine(
    rule_provider=error_rules,
    error_reader=lambda win: get_error_document_text(win, timeout=2.0),
)

set_error_engine(engine)


orchestrate("Create Person Details [Org 01]", {
    "btn:OK": True,
    "btn:Create": True,
    "errorHandler": True,
})

wait_for_window(window_name) -> wait_for_window("Create Person Details [Org 01]")
wait_for_window_to_disappear(window_name) -> wait_for_window_to_disappear("Create Person Details [Org 01]")

🔄 Execution Flow

1. Connect to target window
2. Bring to focus
3. Parse payload
4. Fill text inputs
5. Process radio buttons
6. Process checkboxes
7. Select dropdowns
8. Click buttons
9. Send active window keys
10. Return completion status

---

🧠 Intelligence Behind the Framework

• Top-left ordering for repeated controls
• Visual proximity for matching labels to inputs
• Automatic retry mechanisms
• Graceful fallback if element not found
• Unified naming grammar for all UI control types

---

📈 Roadmap

• OCR-based label detection
• Read/extract mode
• Payload auto-generator
• Screenshot capturing on failure
• Plugin system for custom strategies

---

🐛 Support

For issues, feature requests, or enhancements, contact the maintainer or open a support ticket.