pyjab 1.2.0__py3-none-any.whl

pyjab/__init__.py

@@ -0,0 +1,14 @@
+"""
+Python implementation for Java application UI automation with Java Access Bridge.
+"""
+__author__ = "Gary Gao"
+__email__ = "gaozhao89@qq.com"
+__license__ = "GPLv2"
+__url__ = "https://github.com/gaozhao1989/pyjab"
+__version__ = "1.2.0"
+
+# NOTE: no platform guard here on purpose.  pyjab.config and pyjab.common.service
+# are platform independent and are unit tested on every OS, so `import pyjab`
+# must stay harmless.  The Windows-only entry points (pyjab.jabdriver,
+# pyjab.jabelement) raise a descriptive ImportError instead of letting a bare
+# "No module named 'win32process'" escape.

pyjab/accessibleinfo.py

@@ -0,0 +1,183 @@
+from ctypes import c_float
+from ctypes import c_int
+from ctypes import c_wchar
+from ctypes import c_bool
+from ctypes import Structure
+from ctypes.wintypes import BOOL
+from ctypes.wintypes import WCHAR
+from pyjab.common.types import JOBJECT64
+from pyjab.config import (
+    MAX_STRING_SIZE,
+    MAX_VISIBLE_CHILDREN,
+    SHORT_STRING_SIZE,
+    MAX_KEY_BINDINGS,
+    MAX_RELATION_TARGETS,
+    MAX_RELATIONS,
+    MAX_ACTION_INFO,
+    MAX_ACTIONS_TO_DO,
+)
+
+
+class AccessBridgeVersionInfo(Structure):
+    _fields_ = [
+        ("VMVersion", WCHAR * SHORT_STRING_SIZE),
+        ("bridgeJavaClassVersion", WCHAR * SHORT_STRING_SIZE),
+        ("bridgeJavaDLLVersion", WCHAR * SHORT_STRING_SIZE),
+        ("bridgeWinDLLVersion", WCHAR * SHORT_STRING_SIZE),
+    ]
+
+
+class AccessibleContextInfo(Structure):
+    _fields_ = [
+        ("name", WCHAR * MAX_STRING_SIZE),
+        ("description", WCHAR * MAX_STRING_SIZE),
+        ("role", WCHAR * SHORT_STRING_SIZE),
+        ("role_en_US", WCHAR * SHORT_STRING_SIZE),
+        ("states", WCHAR * SHORT_STRING_SIZE),
+        ("states_en_US", WCHAR * SHORT_STRING_SIZE),
+        ("indexInParent", c_int),
+        ("childrenCount", c_int),
+        ("x", c_int),
+        ("y", c_int),
+        ("width", c_int),
+        ("height", c_int),
+        ("accessibleComponent", BOOL),
+        ("accessibleAction", BOOL),
+        ("accessibleSelection", BOOL),
+        ("accessibleText", BOOL),
+        ("accessibleValue", BOOL),
+    ]
+
+
+class AccessibleTextInfo(Structure):
+    _fields_ = [
+        ("charCount", c_int),
+        ("caretIndex", c_int),
+        ("indexAtPoint", c_int),
+    ]
+
+
+class AccessibleTextItemsInfo(Structure):
+    _fields_ = [
+        ("letter", WCHAR),
+        ("word", WCHAR * SHORT_STRING_SIZE),
+        ("sentence", WCHAR * MAX_STRING_SIZE),
+    ]
+
+
+class AccessibleTextSelectionInfo(Structure):
+    _fields_ = [
+        ("selectionStartIndex", c_int),
+        ("selectionEndIndex", c_int),
+        ("selectedText", WCHAR * MAX_STRING_SIZE),
+    ]
+
+
+class AccessibleTextRectInfo(Structure):
+    _fields_ = [
+        ("x", c_int),
+        ("y", c_int),
+        ("width", c_int),
+        ("height", c_int),
+    ]
+
+
+class AccessibleTextAttributesInfo(Structure):
+    _fields_ = [
+        ("bold", BOOL),
+        ("italic", BOOL),
+        ("underline", BOOL),
+        ("strikethrough", BOOL),
+        ("superscript", BOOL),
+        ("subscript", BOOL),
+        ("backgroundColor", WCHAR * SHORT_STRING_SIZE),
+        ("foregroundColor", WCHAR * SHORT_STRING_SIZE),
+        ("fontFamily", WCHAR * SHORT_STRING_SIZE),
+        ("fontSize", c_int),
+        ("alignment", c_int),
+        ("bidiLevel", c_int),
+        ("firstLineIndent", c_float),
+        ("LeftIndent", c_float),
+        ("rightIndent", c_float),
+        ("lineSpacing", c_float),
+        ("spaceAbove", c_float),
+        ("spaceBelow", c_float),
+        ("fullAttributesString", WCHAR * MAX_STRING_SIZE),
+    ]
+
+
+class AccessibleRelationInfo(Structure):
+    _fields_ = [
+        ("key", WCHAR * SHORT_STRING_SIZE),
+        ("targetCount", c_int),
+        ("targets", JOBJECT64 * MAX_RELATION_TARGETS),
+    ]
+
+
+class AccessibleRelationSetInfo(Structure):
+    _fields_ = [
+        ("relationCount", c_int),
+        ("relations", AccessibleRelationInfo * MAX_RELATIONS),
+    ]
+
+
+class AccessibleActionInfo(Structure):
+    _fields_ = (("name", c_wchar * SHORT_STRING_SIZE),)
+
+
+class AccessibleActions(Structure):
+    _fields_ = (
+        ("actionsCount", c_int),
+        ("actionInfo", AccessibleActionInfo * MAX_ACTION_INFO),
+    )
+
+
+class AccessibleActionsToDo(Structure):
+    _fields_ = (
+        ("actionsCount", c_int),
+        ("actions", AccessibleActionInfo * MAX_ACTIONS_TO_DO),
+    )
+
+
+class AccessibleTableInfo(Structure):
+    _fields_ = [
+        ("caption", JOBJECT64),
+        ("summary", JOBJECT64),
+        ("rowCount", c_int),
+        ("columnCount", c_int),
+        ("accessibleContext", JOBJECT64),
+        ("accessibleTable", JOBJECT64),
+    ]
+
+
+class AccessibleTableCellInfo(Structure):
+    _fields_ = [
+        ("accessibleContext", JOBJECT64),
+        ("index", c_int),
+        ("row", c_int),
+        ("column", c_int),
+        ("rowExtent", c_int),
+        ("columnExtent", c_int),
+        ("isSelected", c_bool),
+    ]
+
+
+class AccessibleKeyBindingInfo(Structure):
+    _fields_ = [
+        ("character", c_wchar),
+        ("modifiers", c_int),
+    ]
+
+
+class AccessibleKeyBindings(Structure):
+    _fields_ = [
+        ("keyBindingsCount", c_int),
+        ("keyBindingInfo", AccessibleKeyBindingInfo * MAX_KEY_BINDINGS),
+    ]
+
+
+class VisibleChildrenInfo(Structure):
+    _fields_ = [
+        ("returnedChildrenCount", c_int),
+        ("children", JOBJECT64 * MAX_VISIBLE_CHILDREN),
+    ]

pyjab/common/actorscheduler.py

@@ -0,0 +1,48 @@
+from collections import deque
+from pyjab.common.logger import Logger
+from pyjab.common.singleton import singleton
+
+
+@singleton
+class ActorScheduler:
+    """Message queue for run generator func as thread.
+
+    Sample:
+
+        sched = ActorScheduler()
+        sched.new_actor("jab", win32utils.setup_msg_pump())
+        sched.run()
+    """
+
+    def __init__(self):
+        self.actors = {}  # Mapping of names to actors
+        self.msg_queue = deque()  # Message queue
+        self.logger = Logger("pyjab")
+
+    def new_actor(self, name, actor):
+        """
+        Admit a newly started actor to the scheduler and give it a name
+        """
+        self.logger.debug(f"msg queue append new actor '{name}'")
+        self.msg_queue.append((actor, None))
+        self.actors[name] = actor
+
+    def send(self, name, msg):
+        """
+        Send a message to a named actor
+        """
+        if actor := self.actors.get(name):
+            self.logger.debug(f"send msg '{msg}' to actor '{actor}'")
+            self.msg_queue.append((actor, msg))
+
+    def run(self):
+        """
+        Run as long as there are pending messages.
+        """
+        while self.msg_queue:
+            actor, msg = self.msg_queue.popleft()
+            try:
+                self.logger.debug(f"run actor '{actor}' with msg '{msg}'")
+                actor.send(msg)
+            except StopIteration:
+                self.logger.debug("stop run action in scheduler")

pyjab/common/by.py

@@ -0,0 +1,18 @@
+"""
+The By implementation.
+"""
+
+
+class By(object):
+    """
+    Set of supported locator strategies.
+    """
+
+    XPATH = "xpath"
+    NAME = "name"
+    DESCRIPTION = "description"
+    ROLE = "role"
+    STATES = "states"
+    OBJECT_DEPTH = "objectdepth"
+    CHILDREN_COUNT = "childrencount"
+    INDEX_IN_PARENT = "indexinparent"

pyjab/common/exceptions.py

@@ -0,0 +1,21 @@
+class CommonException(Exception):
+    def __init__(self, message: str = None, status: str = None) -> None:
+        super().__init__(message, status)
+        self.message = message
+        self.status = status
+
+
+class JABException(CommonException):
+    """
+    Raised by Java Access Bridge if func internal error
+    """
+
+    pass
+
+
+class XpathParserException(CommonException):
+    """
+    Raised by Xpath Parser if error
+    """
+
+    pass

pyjab/common/logger.py

@@ -0,0 +1,31 @@
+import logging
+from pyjab.common.singleton import singleton
+
+
+@singleton
+class Logger(object):
+    LOGGER_INFO = logging.INFO
+    LOGGER_DEBUG = logging.DEBUG
+    LOGGER_WARN = logging.WARN
+    LOGGER_ERROR = logging.ERROR
+    LOGGER_CRITICAL = logging.CRITICAL
+
+    def __init__(self, name=None, level=logging.INFO):
+        self.FORMAT = "%(asctime)-15s %(levelname)s %(name)s %(message)s"
+        self.log = logging.getLogger(name)
+        logging.basicConfig(format=self.FORMAT, level=level)
+
+    def info(self, msg, *args, **kwargs):
+        self.log.info(msg, *args, **kwargs)
+
+    def debug(self, msg, *args, **kwargs):
+        self.log.debug(msg, *args, **kwargs)
+
+    def warning(self, msg, *args, **kwargs):
+        self.log.warning(msg, *args, **kwargs)
+
+    def error(self, msg, *args, **kwargs):
+        self.log.error(msg, *args, **kwargs)
+
+    def critical(self, msg, *args, **kwargs):
+        self.log.critical(msg, *args, **kwargs)

pyjab/common/role.py

@@ -0,0 +1,71 @@
+from enum import Enum
+
+"""
+The Role implementation.
+"""
+
+
+class Role(str, Enum):
+    """
+    Set of supported role strategies.
+    """
+
+    ALERT = "alert"
+    CANVAS = "canvas"
+    CHECK_BOX = "check box"
+    COLOR_CHOOSER = "color chooser"
+    COLUMN_HEADER = "column header"
+    COMBO_BOX = "combo box"
+    DATE_EDITOR = "date editor"
+    DESKTOP_ICON = "desktop icon"
+    DESKTOP_PANE = "desktop pane"
+    DIALOG = "dialog"
+    DIRECTORY_PANE = "directory pane"
+    EDIT_BAR = "edit bar"
+    FILE_CHOOSER = "file chooser"
+    FILLER = "filler"
+    FONT_CHOOSER = "font chooser"
+    FOOTER = "footer"
+    FRAME = "frame"
+    GLASS_PANE = "glass pane"
+    GROUP_BOX = "group box"
+    HEADER = "header"
+    HYPERLINK = "hyperlink"
+    ICON = "icon"
+    INTERNAL_FRAME = "internal frame"
+    LABEL = "label"
+    LAYERED_PANE = "layered pane"
+    LIST = "list"
+    LIST_ITEM = "list item"
+    MENU = "menu"
+    MENU_BAR = "menu bar"
+    MENU_ITEM = "menu item"
+    OPTION_PANE = "option pane"
+    PAGE_TAB = "page tab"
+    PAGE_TAB_LIST = "page tab list"
+    PANEL = "panel"
+    PARAGRAPH = "paragraph"
+    PASSWORD_TEXT = "password text"
+    POPUP_MENU = "popup menu"
+    PROGRESS_BAR = "progress bar"
+    PUSH_BUTTON = "push button"
+    RADIO_BUTTON = "radio button"
+    ROOT_PANE = "root pane"
+    ROW_HEADER = "row header"
+    RULER = "ruler"
+    SCROLL_BAR = "scroll bar"
+    SCROLL_PANE = "scroll pane"
+    SEPARATOR = "separator"
+    SLIDER = "slider"
+    SPIN_BOX = "spinbox"
+    SPLIT_PANE = "split pane"
+    STATUS_BAR = "status bar"
+    TABLE = "table"
+    TEXT = "text"
+    TOGGLE_BUTTON = "toggle button"
+    TOOL_BAR = "tool bar"
+    TOOL_TIP = "tool tip"
+    TREE = "tree"
+    UNKNOWN = "unknown"
+    VIEW_PORT = "viewport"
+    WINDOW = "window"

pyjab/common/service.py

@@ -0,0 +1,95 @@
+from ctypes import cdll
+from ctypes import CDLL
+from pathlib import Path
+from typing import Optional
+
+from pyjab.common.logger import Logger
+from pyjab.common.singleton import singleton
+from pyjab.config import A11Y_PROPS_CONTENT
+from pyjab.config import A11Y_PROPS_PATH
+from pyjab.config import describe_bridge_dll_search
+from pyjab.config import find_bridge_dll
+
+
+@singleton
+class Service(object):
+    def __init__(self) -> None:
+        self.logger = Logger("pyjab")
+        self.init_bridge()
+
+    def enable_bridge(self) -> None:
+        with open(A11Y_PROPS_PATH, "wt") as fp:
+            try:
+                self.logger.debug("enable bridge")
+                fp.write(A11Y_PROPS_CONTENT)
+            except (OSError, IOError):
+                self.logger.error("enable bridge failed")
+
+    def is_bridge_enabled(self) -> bool:
+        if not Path(A11Y_PROPS_PATH).is_file():
+            return False
+        with open(A11Y_PROPS_PATH, "rt") as fp:
+            try:
+                data = fp.read()
+            except (OSError, IOError):
+                self.logger.error("bridge is not enabled")
+                return False
+        is_enabled = data == A11Y_PROPS_CONTENT
+        self.logger.debug("is bridge enabled => '{}'".format(is_enabled))
+        return is_enabled
+
+    def init_bridge(self) -> None:
+        self.logger.debug("init bridge")
+        if not self.is_bridge_enabled():
+            self.enable_bridge()
+
+    def find_bridge_dll(self, bridge_dll: Optional[str] = None) -> Optional[Path]:
+        """Locate the Java Access Bridge DLL without loading it.
+
+        Useful for diagnostics: it reports *where* the DLL would be loaded from
+        without actually loading it into the process.
+
+        Args:
+            bridge_dll: An explicit DLL path supplied by the caller.  When given
+                and valid it takes precedence over all automatic discovery.
+
+        Returns:
+            The path to the DLL, or ``None`` when it could not be located.
+        """
+        if bridge_dll:
+            explicit = Path(str(bridge_dll))
+            if explicit.is_file():
+                return explicit
+            self.logger.warning(
+                "The explicit bridge_dll path does not exist: '{}'. "
+                "Falling back to automatic discovery.".format(bridge_dll)
+            )
+        return find_bridge_dll()
+
+    def load_library(self, bridge_dll: str = "") -> CDLL:
+        """Load the Java Access Bridge DLL.
+
+        Resolution order:
+
+        1. The ``bridge_dll`` argument, when it points at an existing file.
+        2. :func:`pyjab.config.find_bridge_dll`, which probes
+           ``%JAVA_HOME%\\bin`` (JDK 11+), ``%JAVA_HOME%\\jre\\bin`` (JDK 8-10),
+           ``%JRE_HOME%``, ``%JAB_HOME%``, common vendor install locations and
+           finally performs a bounded recursive search.
+
+        Args:
+            bridge_dll: Explicit path to ``WindowsAccessBridge-XX.dll``.
+                Defaults to "" (automatic discovery).
+
+        Raises:
+            FileNotFoundError: When no DLL could be located.  The message lists
+                every location that was probed and how to fix the situation.
+        """
+        self.logger.debug("load library of bridge")
+
+        resolved = self.find_bridge_dll(bridge_dll)
+        if resolved is None:
+            raise FileNotFoundError(describe_bridge_dll_search())
+
+        self.logger.debug("Loading Java Access Bridge DLL from '{}'".format(resolved))
+        return cdll.LoadLibrary(str(resolved))

pyjab/common/shortcutkeys.py

@@ -0,0 +1,164 @@
+from pyjab.common.logger import Logger
+from pyjab.common.win32utils import Win32Utils
+
+
+class ShortcutKeys(object):
+    def __init__(self) -> None:
+        self.logger = Logger("pyjab")
+        self.win32_utils = Win32Utils()
+        self.press_hold_release_key = self.win32_utils._press_hold_release_key
+        self.press_key = self.win32_utils._press_key
+
+    # Common shortcut keys
+    def clear_text(self) -> None:
+        self.logger.debug("send shortcut command clear text")
+        self.press_key("home")
+        self.press_hold_release_key("ctrl", "shift", "end")
+        # TODO: need find out method to clear text for JABElement
+        for _ in range(100):
+            self.press_key("backspace")
+
+    def paste(self) -> None:
+        self.logger.debug("paste text from clipboard")
+        self.press_hold_release_key("ctrl", "v")
+
+    # Oracle Form shortcut keys
+    def block_menu(self) -> None:
+        self.logger.debug("send shortcut command block menu")
+        self.press_hold_release_key("ctrl", "b")
+
+    def clear_block(self) -> None:
+        self.logger.debug("send shortcut command clear block")
+        self.press_key("F7")
+
+    def clear_field(self) -> None:
+        self.logger.debug("send shortcut command clear field")
+        self.press_key("F5")
+
+    def clear_form(self) -> None:
+        self.logger.debug("send shortcut command clear form")
+        self.press_key("F8")
+
+    def clear_record(self) -> None:
+        self.logger.debug("send shortcut command clear record")
+        self.press_key("F6")
+
+    def commit(self) -> None:
+        self.logger.debug("send shortcut command commit")
+        self.press_hold_release_key("ctrl", "s")
+
+    def count_query(self) -> None:
+        self.logger.debug("send shortcut command count query")
+        self.press_key("F12")
+
+    def delete_record(self) -> None:
+        self.logger.debug("send shortcut command delete record")
+        self.press_hold_release_key("ctrl", "up_arrow")
+
+    def display_error(self) -> None:
+        self.logger.debug("send shortcut command display error")
+        self.press_hold_release_key("shift", "ctrl", "e")
+
+    def down(self) -> None:
+        self.logger.debug("send shortcut command down")
+        self.press_key("down_arrow")
+
+    def duplicate_field(self) -> None:
+        self.logger.debug("send shortcut command duplicate field")
+        self.press_hold_release_key("shift", "F5")
+
+    def duplicate_record(self) -> None:
+        self.logger.debug("send shortcut command duplicate record")
+        self.press_hold_release_key("shift", "F6")
+
+    def edit(self) -> None:
+        self.logger.debug("send shortcut command edit")
+        self.press_hold_release_key("ctrl", "e")
+
+    def enter_query(self) -> None:
+        self.logger.debug("send shortcut command enter query")
+        self.press_key("F11")
+
+    def execute_query(self) -> None:
+        self.logger.debug("send shortcut command execute query")
+        self.press_hold_release_key("ctrl", "F11")
+
+    def _exit(self) -> None:
+        self.logger.debug("send shortcut command exit")
+        self.press_key("F4")
+
+    def _help(self) -> None:
+        self.logger.debug("send shortcut command help")
+        self.press_hold_release_key("ctrl", "h")
+
+    def insert_record(self) -> None:
+        self.logger.debug("send shortcut command insert record")
+        self.press_hold_release_key("ctrl", "down_arrow")
+
+    def list_of_values(self) -> None:
+        self.logger.debug("send shortcut command list of values")
+        self.press_hold_release_key("ctrl", "l")
+
+    def list_tab_pages(self) -> None:
+        self.logger.debug("send shortcut command list tab pages")
+        self.press_key("F2")
+
+    def next_block(self) -> None:
+        self.logger.debug("send shortcut command next block")
+        self.press_hold_release_key("shift", "page_down")
+
+    def next_field(self) -> None:
+        self.logger.debug("send shortcut command next field")
+        self.press_key("tab")
+
+    def next_primary_key(self) -> None:
+        self.logger.debug("send shortcut command next primary key")
+        self.press_hold_release_key("shift", "F7")
+
+    def next_record(self) -> None:
+        self.logger.debug("send shortcut command next record")
+        self.press_key("down_arrow")
+
+    def next_set_of_records(self) -> None:
+        self.logger.debug("send shortcut command next set of records")
+        self.press_key("shift", "F8")
+
+    def previous_block(self) -> None:
+        self.logger.debug("send shortcut command previous block")
+        self.press_key("shift", "page_up")
+
+    def previous_field(self) -> None:
+        self.logger.debug("send shortcut command previous field")
+        self.press_key("shift", "tab")
+
+    def previous_record(self) -> None:
+        self.logger.debug("send shortcut command previous record")
+        self.press_key("shift", "up_arrow")
+
+    def _print(self) -> None:
+        self.logger.debug("send shortcut command print")
+        self.press_key("ctrl", "p")
+
+    def _return(self) -> None:
+        self.logger.debug("send shortcut command return")
+        self.press_key("clear")
+
+    def scroll_down(self) -> None:
+        self.logger.debug("send shortcut command scroll down")
+        self.press_key("page_down")
+
+    def scroll_up(self) -> None:
+        self.logger.debug("send shortcut command scroll up")
+        self.press_key("page_up")
+
+    def show_keys(self) -> None:
+        self.logger.debug("send shortcut command show keys")
+        self.press_key("ctrl", "k")
+
+    def up(self) -> None:
+        self.logger.debug("send shortcut command up")
+        self.press_key("up_arrow")
+
+    def update_record(self) -> None:
+        self.logger.debug("send shortcut command update record")
+        self.press_key("ctrl", "u")

pyjab/common/singleton.py

@@ -0,0 +1,13 @@
+from functools import wraps
+
+
+def singleton(cls):
+    instances = {}
+
+    @wraps(cls)
+    def wrapper(*args, **kwargs):
+        if cls not in instances:
+            instances[cls] = cls(*args, **kwargs)
+        return instances[cls]
+
+    return wrapper

pyjab/common/states.py

@@ -0,0 +1,28 @@
+from enum import Enum
+
+"""
+The States implementation.
+"""
+
+
+class States(str, Enum):
+    """
+    Set of supported states strategies.
+    """
+
+    BUSY = "busy"
+    CHECKED = "checked"
+    ENABLED = "enabled"
+    FOCUSED = "focused"
+    SELECTED = "selected"
+    PRESSED = "pressed"
+    EXPANDED = "expanded"
+    COLLAPSED = "collapsed"
+    ICONIFIED = "iconified"
+    MODAL = "modal"
+    MULTI_LINE = "multi_line"
+    FOCUSABLE = "focusable"
+    EDITABLE = "editable"
+    VISIBLE = "visible"
+    SHOWING = "showing"
+    UNKNOWN = "unknown"