winauto-cli 0.1.0__py3-none-any.whl

winauto_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

winauto_cli/__main__.py

@@ -0,0 +1,5 @@
+from winauto_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

winauto_cli/automation.py

@@ -0,0 +1,635 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from winauto_cli.errors import ActionExecutionError, AssertionExecutionError, ElementResolutionError
+from winauto_cli.models import RuntimeOptions, Selector
+
+try:
+    from pywinauto import Desktop
+except ImportError:  # pragma: no cover - handled at runtime
+    Desktop = None
+
+
+COMMON_PATTERNS = {
+    "invoke": "iface_invoke",
+    "value": "iface_value",
+    "selection": "iface_selection",
+    "selection_item": "iface_selection_item",
+    "toggle": "iface_toggle",
+    "expand_collapse": "iface_expand_collapse",
+    "text": "iface_text",
+    "grid": "iface_grid",
+    "table": "iface_table",
+    "legacy": "iface_legacy_iaccessible",
+}
+
+ALLOWED_PATH_ATTRS = {"name", "auto_id", "class_name", "control_type", "window_text"}
+PATH_ATTR_PATTERN = re.compile(r"\[@(?P<key>[a-zA-Z_]+)=(?P<quote>['\"])(?P<value>.*?)(?P=quote)\]")
+PATH_INDEX_PATTERN = re.compile(r"\[(?P<index>\d+)\]")
+
+
+@dataclass(slots=True)
+class PathStep:
+    axis: str
+    control_type: str | None = None
+    filters: dict[str, str] = field(default_factory=dict)
+    index: int | None = None
+    raw: str = ""
+
+
+
+def _require_pywinauto() -> None:
+    if Desktop is None:
+        raise ActionExecutionError(
+            "pywinauto is not installed. Install dependencies first with: python -m pip install -e ."
+        )
+
+
+
+def _log(enabled: bool, message: str) -> None:
+    if enabled:
+        print(f"[debug] {message}")
+
+
+
+def _desktop(backend: str):
+    _require_pywinauto()
+    return Desktop(backend=backend)
+
+
+
+def _wait_until(timeout: float):
+    deadline = time.monotonic() + max(timeout, 0)
+    while True:
+        yield
+        if time.monotonic() >= deadline:
+            break
+        time.sleep(0.2)
+
+
+
+def resolve_scope(window_selector: Selector, options: RuntimeOptions):
+    if window_selector.is_empty():
+        return None
+    desktop = _desktop(options.backend)
+    return desktop.window(**window_selector.to_kwargs()).wrapper_object()
+
+
+
+def resolve_element(window_selector: Selector, target_selector: Selector, options: RuntimeOptions, path_query: str | None = None):
+    matches = find_elements(window_selector, target_selector, options, max_results=1, require_match=True, path_query=path_query)
+    return matches[0]
+
+
+
+def find_elements(
+    window_selector: Selector,
+    target_selector: Selector,
+    options: RuntimeOptions,
+    max_results: int = 20,
+    require_match: bool = False,
+    path_query: str | None = None,
+):
+    last_error: Exception | None = None
+
+    for _ in _wait_until(options.timeout):
+        try:
+            scope = resolve_scope(window_selector, options)
+            if scope is not None:
+                _log(options.verbose, f"resolved parent window: {safe_summary(scope)}")
+            matches = _collect_matches(scope, target_selector, options, max_results=max_results, path_query=path_query)
+            if matches:
+                _log(options.verbose, f"resolved {len(matches)} candidate(s)")
+                return matches
+            last_error = None
+        except Exception as exc:  # pragma: no cover - depends on UI state
+            last_error = exc
+
+    if require_match:
+        selector_blob = {
+            "window": window_selector.to_kwargs(),
+            "target": target_selector.to_kwargs(),
+            "path": path_query,
+            "backend": options.backend,
+            "top_level_only": options.top_level_only,
+        }
+        raise ElementResolutionError(
+            f"Unable to resolve element within {options.timeout:.1f}s: {json.dumps(selector_blob, ensure_ascii=True)}"
+        ) from last_error
+
+    return []
+
+
+
+def _collect_matches(scope, target_selector: Selector, options: RuntimeOptions, max_results: int, path_query: str | None = None):
+    if path_query:
+        return _collect_path_matches(scope, path_query, options, max_results=max_results)
+
+    target_kwargs = target_selector.to_kwargs()
+    desktop = _desktop(options.backend)
+
+    if scope is None:
+        if target_selector.is_empty():
+            windows = desktop.windows()
+        else:
+            windows = desktop.windows(**target_kwargs)
+        return list(windows)[:max_results]
+
+    if target_selector.is_empty():
+        candidates = scope.children() if options.top_level_only else scope.descendants()
+    else:
+        candidates = scope.children(**target_kwargs) if options.top_level_only else scope.descendants(**target_kwargs)
+    return list(candidates)[:max_results]
+
+
+
+def _collect_path_matches(scope, path_query: str, options: RuntimeOptions, max_results: int):
+    steps = parse_path_query(path_query)
+    desktop = _desktop(options.backend)
+    if scope is None:
+        current_nodes = list(desktop.windows())
+    else:
+        current_nodes = [scope]
+
+    for position, step in enumerate(steps):
+        next_nodes = []
+        for node in current_nodes:
+            next_nodes.extend(_step_candidates(node, step, root_scope=(position == 0 and scope is None)))
+        if step.index is not None:
+            next_nodes = next_nodes[step.index:step.index + 1]
+        current_nodes = next_nodes
+        if not current_nodes:
+            break
+
+    return current_nodes[:max_results]
+
+
+
+def _step_candidates(node, step: PathStep, root_scope: bool = False):
+    if root_scope:
+        if step.axis == "direct":
+            pool = [node]
+        else:
+            pool = [node]
+            try:
+                pool.extend(node.descendants())
+            except Exception:
+                pass
+    else:
+        try:
+            pool = node.children() if step.axis == "direct" else node.descendants()
+        except Exception:
+            return []
+    return [candidate for candidate in pool if _matches_path_step(candidate, step)]
+
+
+
+def _matches_path_step(element, step: PathStep) -> bool:
+    summary = safe_summary(element)
+    if step.control_type and str(summary.get("control_type") or "") != step.control_type:
+        return False
+    for key, expected in step.filters.items():
+        actual = summary.get(key)
+        if actual is None:
+            return False
+        if str(actual) != expected:
+            return False
+    return True
+
+
+
+def parse_path_query(path_query: str) -> list[PathStep]:
+    query = (path_query or "").strip()
+    if not query:
+        raise ElementResolutionError("Path query cannot be empty.")
+
+    steps: list[PathStep] = []
+    position = 0
+    while position < len(query):
+        axis = "descendant"
+        if query.startswith("//", position):
+            axis = "descendant"
+            position += 2
+        elif query.startswith("/", position):
+            axis = "direct"
+            position += 1
+        elif steps:
+            axis = "direct"
+
+        start = position
+        bracket_depth = 0
+        while position < len(query):
+            char = query[position]
+            if char == '[':
+                bracket_depth += 1
+            elif char == ']':
+                bracket_depth -= 1
+            elif char == '/' and bracket_depth == 0:
+                break
+            position += 1
+
+        segment = query[start:position].strip()
+        if not segment:
+            continue
+        steps.append(_parse_path_segment(segment, axis))
+
+    if not steps:
+        raise ElementResolutionError(f"Invalid path query: {path_query}")
+    return steps
+
+
+
+def _parse_path_segment(segment: str, axis: str) -> PathStep:
+    bracket_start = segment.find('[')
+    head = segment if bracket_start == -1 else segment[:bracket_start]
+    head = head.strip()
+    control_type = None if head in ("", "*") else head
+
+    filters: dict[str, str] = {}
+    for match in PATH_ATTR_PATTERN.finditer(segment):
+        key = match.group("key")
+        if key not in ALLOWED_PATH_ATTRS:
+            raise ElementResolutionError(f"Unsupported path attribute: {key}")
+        filters[key] = match.group("value")
+
+    index = None
+    for match in PATH_INDEX_PATTERN.finditer(segment):
+        if match.group(0).startswith("[@"):
+            continue
+        index = int(match.group("index"))
+
+    return PathStep(axis=axis, control_type=control_type, filters=filters, index=index, raw=segment)
+
+
+
+def list_windows(options: RuntimeOptions, max_results: int = 50):
+    desktop = _desktop(options.backend)
+    windows = desktop.windows()
+    return [safe_summary(window) for window in windows[:max_results]]
+
+
+
+def safe_summary(element) -> dict[str, Any]:
+    info: dict[str, Any] = {"friendly_class_name": None, "window_text": None}
+
+    try:
+        info["friendly_class_name"] = element.friendly_class_name()
+    except Exception:
+        pass
+
+    try:
+        info["window_text"] = element.window_text()
+    except Exception:
+        pass
+
+    try:
+        rect = element.rectangle()
+        info["rectangle"] = {
+            "left": rect.left,
+            "top": rect.top,
+            "right": rect.right,
+            "bottom": rect.bottom,
+        }
+    except Exception:
+        pass
+
+    element_info = getattr(element, "element_info", None)
+    if element_info is not None:
+        for source_name, target_name in [
+            ("name", "name"),
+            ("automation_id", "automation_id"),
+            ("class_name", "class_name"),
+            ("control_type", "control_type"),
+            ("handle", "handle"),
+            ("rich_text", "rich_text"),
+        ]:
+            try:
+                info[target_name] = getattr(element_info, source_name)
+            except Exception:
+                continue
+
+    return info
+
+
+
+def inspect_element(element, child_limit: int = 20, parent_limit: int = 8) -> dict[str, Any]:
+    summary = safe_summary(element)
+    children = []
+    parents = []
+
+    try:
+        for child in element.children()[:child_limit]:
+            children.append(safe_summary(child))
+    except Exception:
+        pass
+
+    current = element
+    for _ in range(parent_limit):
+        try:
+            current = current.parent()
+        except Exception:
+            break
+        if current is None:
+            break
+        parents.append(safe_summary(current))
+
+    return {
+        "element": summary,
+        "children": children,
+        "parents": parents,
+        "supported_patterns": _supported_patterns(element),
+        "recommended_selectors": recommended_selectors(summary),
+        "recommended_paths": recommended_paths(summary, parents),
+        "relative_path": build_relative_path(summary),
+    }
+
+
+
+def recommended_selectors(summary: dict[str, Any]) -> list[dict[str, str]]:
+    selectors: list[dict[str, str]] = []
+    automation_id = summary.get("automation_id")
+    name = summary.get("name") or summary.get("window_text")
+    control_type = summary.get("control_type")
+    class_name = summary.get("class_name")
+
+    if automation_id:
+        selectors.append({"auto_id": str(automation_id)})
+    if name and control_type:
+        selectors.append({"name": str(name), "control_type": str(control_type)})
+    if name:
+        selectors.append({"name": str(name)})
+    if class_name and control_type:
+        selectors.append({"class_name": str(class_name), "control_type": str(control_type)})
+    return selectors
+
+
+
+def recommended_paths(summary: dict[str, Any], parents: list[dict[str, Any]]) -> list[str]:
+    leaf = _path_segment_for_summary(summary)
+    parent_segments = [_path_segment_for_summary(parent) for parent in reversed(parents[:2])]
+
+    candidates: list[str] = []
+    if leaf:
+        candidates.append(f"//{leaf}")
+    if parent_segments and leaf:
+        candidates.append("//" + "/".join(parent_segments + [leaf]))
+    if summary.get("control_type"):
+        candidates.append(f"//{summary['control_type']}")
+
+    seen = set()
+    deduped = []
+    for candidate in candidates:
+        if candidate not in seen:
+            seen.add(candidate)
+            deduped.append(candidate)
+    return deduped
+
+
+
+def build_relative_path(summary: dict[str, Any]) -> str | None:
+    segment = _path_segment_for_summary(summary)
+    if not segment:
+        return None
+    return segment
+
+
+
+def _path_segment_for_summary(summary: dict[str, Any]) -> str | None:
+    control_type = summary.get("control_type")
+    if not control_type:
+        return None
+
+    auto_id = summary.get("automation_id")
+    if auto_id:
+        return f"{control_type}[@auto_id={json.dumps(str(auto_id), ensure_ascii=True)}]"
+
+    name = summary.get("name") or summary.get("window_text")
+    if name:
+        return f"{control_type}[@name={json.dumps(str(name), ensure_ascii=True)}]"
+
+    class_name = summary.get("class_name")
+    if class_name:
+        return f"{control_type}[@class_name={json.dumps(str(class_name), ensure_ascii=True)}]"
+
+    return str(control_type)
+
+
+
+def _supported_patterns(element) -> list[str]:
+    supported = []
+    for pattern_name, attr_name in COMMON_PATTERNS.items():
+        try:
+            value = getattr(element, attr_name, None)
+            if value is not None:
+                supported.append(pattern_name)
+        except Exception:
+            continue
+    return supported
+
+
+
+def dump_identifiers(element) -> str:
+    lines: list[str] = []
+    _append_tree(lines, element, depth=0, max_depth=8)
+    return "\n".join(lines).rstrip()
+
+
+
+def highlight_element(element, duration_ms: int = 800, colour: str = "red", thickness: int = 3) -> dict[str, Any]:
+    try:
+        element.draw_outline(colour=colour, thickness=thickness)
+        time.sleep(max(duration_ms, 0) / 1000.0)
+    except Exception as exc:  # pragma: no cover - depends on UI state
+        raise ActionExecutionError(f"Failed to highlight element: {safe_summary(element)}") from exc
+
+    return {
+        "status": "ok",
+        "duration_ms": duration_ms,
+        "colour": colour,
+        "thickness": thickness,
+        "element": safe_summary(element),
+    }
+
+
+
+def capture_image(
+    element,
+    out_path: str,
+    highlight: bool = False,
+    highlight_duration_ms: int = 800,
+    highlight_colour: str = "red",
+    highlight_thickness: int = 3,
+) -> dict[str, Any]:
+    if highlight:
+        highlight_element(
+            element,
+            duration_ms=highlight_duration_ms,
+            colour=highlight_colour,
+            thickness=highlight_thickness,
+        )
+
+    try:
+        image = element.capture_as_image()
+        image.save(out_path)
+    except Exception as exc:  # pragma: no cover - depends on UI state
+        raise ActionExecutionError(f"Failed to capture screenshot for element: {safe_summary(element)}") from exc
+
+    return {
+        "status": "ok",
+        "out": out_path,
+        "highlight": highlight,
+        "highlight_duration_ms": highlight_duration_ms if highlight else 0,
+        "highlight_colour": highlight_colour if highlight else None,
+        "highlight_thickness": highlight_thickness if highlight else None,
+        "element": safe_summary(element),
+    }
+
+
+
+def _append_tree(lines: list[str], element, depth: int, max_depth: int) -> None:
+    indent = "  " * depth
+    summary = safe_summary(element)
+    label_parts: list[str] = []
+
+    control_type = summary.get("control_type")
+    friendly_class_name = summary.get("friendly_class_name")
+    name = summary.get("name") or summary.get("window_text")
+    auto_id = summary.get("automation_id")
+    class_name = summary.get("class_name")
+
+    if control_type:
+        label_parts.append(f"control_type={control_type}")
+    if friendly_class_name:
+        label_parts.append(f"friendly_class={friendly_class_name}")
+    if name:
+        label_parts.append(f"name={name!r}")
+    if auto_id:
+        label_parts.append(f"auto_id={auto_id!r}")
+    if class_name:
+        label_parts.append(f"class_name={class_name!r}")
+
+    if not label_parts:
+        label_parts.append(repr(summary))
+
+    lines.append(f"{indent}- " + ", ".join(label_parts))
+
+    if depth >= max_depth:
+        return
+
+    try:
+        children = element.children()
+    except Exception:
+        return
+
+    for child in children:
+        _append_tree(lines, child, depth + 1, max_depth)
+
+
+
+def click_element(element) -> None:
+    try:
+        element.click_input()
+    except Exception as exc:  # pragma: no cover - depends on UI state
+        raise ActionExecutionError(f"Failed to click element: {safe_summary(element)}") from exc
+
+
+
+def type_into_element(element, text: str) -> None:
+    try:
+        element.set_focus()
+    except Exception:
+        pass
+
+    try:
+        element.type_keys(text, with_spaces=True, set_foreground=True)
+    except Exception:
+        try:
+            element.set_edit_text(text)
+        except Exception as exc:  # pragma: no cover - depends on UI state
+            raise ActionExecutionError(f"Failed to type into element: {safe_summary(element)}") from exc
+
+
+
+def invoke_element(element) -> None:
+    try:
+        element.invoke()
+    except Exception as exc:  # pragma: no cover - depends on UI state
+        raise ActionExecutionError(f"Failed to invoke element: {safe_summary(element)}") from exc
+
+
+
+def perform_action(element, action: str, text: str | None = None) -> dict[str, Any]:
+    if action == "click":
+        click_element(element)
+    elif action == "type":
+        if text is None:
+            raise ActionExecutionError("The 'type' action requires --text.")
+        type_into_element(element, text)
+    elif action == "invoke":
+        invoke_element(element)
+    elif action == "set_text":
+        if text is None:
+            raise ActionExecutionError("The 'set_text' action requires --text.")
+        try:
+            element.set_edit_text(text)
+        except Exception as exc:  # pragma: no cover - depends on UI state
+            raise ActionExecutionError(f"Failed to set text on element: {safe_summary(element)}") from exc
+    else:
+        raise ActionExecutionError(f"Unsupported action: {action}")
+
+    payload = {"status": "ok", "action": action, "element": safe_summary(element)}
+    if text is not None:
+        payload["text"] = text
+    return payload
+
+
+
+def run_assertion(elements: list, assertion: str, expected: str | None = None, expected_bool: bool | None = None) -> dict[str, Any]:
+    if assertion == "exists":
+        passed = len(elements) > 0
+        actual = len(elements)
+    elif assertion == "count":
+        if expected is None:
+            raise AssertionExecutionError("The 'count' assertion requires --expected.")
+        actual = len(elements)
+        passed = actual == int(expected)
+    else:
+        if not elements:
+            raise AssertionExecutionError("Target element was not found for assertion.")
+        element = elements[0]
+        summary = safe_summary(element)
+        if assertion == "text_equals":
+            if expected is None:
+                raise AssertionExecutionError("The 'text_equals' assertion requires --expected.")
+            actual = str(summary.get("name") or summary.get("window_text") or "")
+            passed = actual == expected
+        elif assertion == "enabled":
+            actual = bool(element.is_enabled())
+            passed = actual is expected_bool
+        elif assertion == "visible":
+            actual = bool(element.is_visible())
+            passed = actual is expected_bool
+        else:
+            raise AssertionExecutionError(f"Unsupported assertion: {assertion}")
+
+    result = {
+        "status": "passed" if passed else "failed",
+        "assertion": assertion,
+        "actual": actual,
+    }
+    if expected is not None:
+        result["expected"] = expected
+    if expected_bool is not None:
+        result["expected"] = expected_bool
+    if elements:
+        result["element"] = safe_summary(elements[0])
+        result["count"] = len(elements)
+
+    if not passed:
+        raise AssertionExecutionError(json.dumps(result, ensure_ascii=True))
+    return result