dbxdebug 0.2.1__py3-none-any.whl

dbxdebug/keyboard.py

@@ -0,0 +1,205 @@
+"""
+Keyboard input helpers for QMP protocol.
+
+Provides convenient functions for building key sequences and common
+keyboard operations using the QMP protocol.
+"""
+
+from .dbx_kbd import DBX_KEY, DBX_KEY_TO_QCODE
+
+
+def get_qcode(key: DBX_KEY) -> str:
+    """
+    Get QMP qcode for a DBX_KEY.
+
+    Args:
+        key: DOSBox-X key code
+
+    Returns:
+        QMP qcode string
+
+    Raises:
+        ValueError: If key has no QMP mapping
+    """
+    qcode = DBX_KEY_TO_QCODE.get(key)
+    if qcode is None:
+        raise ValueError(f"No QMP mapping for key: {key.name}")
+    return qcode
+
+
+def key_list(*keys: DBX_KEY) -> list[str]:
+    """
+    Convert DBX_KEY values to QMP qcode list.
+
+    Args:
+        *keys: DBX_KEY values
+
+    Returns:
+        List of QMP qcode strings for use with QMPClient.send_key()
+
+    Example:
+        >>> key_list(DBX_KEY.KBD_leftctrl, DBX_KEY.KBD_c)
+        ['ctrl', 'c']
+    """
+    return [get_qcode(k) for k in keys]
+
+
+def ctrl_key(key: DBX_KEY) -> list[str]:
+    """
+    Build Ctrl+key combination.
+
+    Args:
+        key: The key to combine with Ctrl
+
+    Returns:
+        List of qcodes for QMPClient.send_key()
+
+    Example:
+        >>> ctrl_key(DBX_KEY.KBD_c)
+        ['ctrl', 'c']
+    """
+    return ["ctrl", get_qcode(key)]
+
+
+def alt_key(key: DBX_KEY) -> list[str]:
+    """
+    Build Alt+key combination.
+
+    Args:
+        key: The key to combine with Alt
+
+    Returns:
+        List of qcodes for QMPClient.send_key()
+
+    Example:
+        >>> alt_key(DBX_KEY.KBD_f4)
+        ['alt', 'f4']
+    """
+    return ["alt", get_qcode(key)]
+
+
+def shift_key(key: DBX_KEY) -> list[str]:
+    """
+    Build Shift+key combination.
+
+    Args:
+        key: The key to combine with Shift
+
+    Returns:
+        List of qcodes for QMPClient.send_key()
+    """
+    return ["shift", get_qcode(key)]
+
+
+def ctrl_alt_key(key: DBX_KEY) -> list[str]:
+    """
+    Build Ctrl+Alt+key combination.
+
+    Args:
+        key: The key to combine with Ctrl+Alt
+
+    Returns:
+        List of qcodes for QMPClient.send_key()
+
+    Example:
+        >>> ctrl_alt_key(DBX_KEY.KBD_delete)
+        ['ctrl', 'alt', 'delete']
+    """
+    return ["ctrl", "alt", get_qcode(key)]
+
+
+def ctrl_shift_key(key: DBX_KEY) -> list[str]:
+    """
+    Build Ctrl+Shift+key combination.
+
+    Args:
+        key: The key to combine with Ctrl+Shift
+
+    Returns:
+        List of qcodes for QMPClient.send_key()
+    """
+    return ["ctrl", "shift", get_qcode(key)]
+
+
+# Convenience constants for common keys
+ENTER = ["ret"]
+ESCAPE = ["esc"]
+TAB = ["tab"]
+BACKSPACE = ["backspace"]
+SPACE = ["spc"]
+DELETE = ["delete"]
+INSERT = ["insert"]
+HOME = ["home"]
+END = ["end"]
+PAGE_UP = ["pgup"]
+PAGE_DOWN = ["pgdn"]
+UP = ["up"]
+DOWN = ["down"]
+LEFT = ["left"]
+RIGHT = ["right"]
+
+# Common key combinations
+CTRL_C = ["ctrl", "c"]
+CTRL_V = ["ctrl", "v"]
+CTRL_X = ["ctrl", "x"]
+CTRL_Z = ["ctrl", "z"]
+CTRL_A = ["ctrl", "a"]
+CTRL_S = ["ctrl", "s"]
+CTRL_ALT_DEL = ["ctrl", "alt", "delete"]
+ALT_F4 = ["alt", "f4"]
+ALT_TAB = ["alt", "tab"]
+
+
+def function_key(n: int) -> list[str]:
+    """
+    Get function key qcode.
+
+    Args:
+        n: Function key number (1-24)
+
+    Returns:
+        List with single qcode for QMPClient.send_key()
+
+    Example:
+        >>> function_key(1)
+        ['f1']
+    """
+    if not 1 <= n <= 24:
+        raise ValueError(f"Function key must be 1-24, got {n}")
+    return [f"f{n}"]
+
+
+def digit_key(n: int) -> list[str]:
+    """
+    Get digit key qcode.
+
+    Args:
+        n: Digit (0-9)
+
+    Returns:
+        List with single qcode for QMPClient.send_key()
+
+    Example:
+        >>> digit_key(5)
+        ['5']
+    """
+    if not 0 <= n <= 9:
+        raise ValueError(f"Digit must be 0-9, got {n}")
+    return [str(n)]
+
+
+def number_keys(num: int) -> list[list[str]]:
+    """
+    Get key sequences to type a number.
+
+    Args:
+        num: Number to type
+
+    Returns:
+        List of key lists, each to be passed to QMPClient.send_key()
+
+    Example:
+        >>> number_keys(42)
+        [['4'], ['2']]
+    """
+    return [[d] for d in str(num)]

dbxdebug/qmp.py

@@ -0,0 +1,239 @@
+"""
+QEMU Monitor Protocol (QMP) client for DOSBox-X keyboard input.
+
+Provides keyboard input injection via the QMP protocol:
+- send_key(): Press and release keys with timing control
+- key_down()/key_up(): Explicit press/release control
+- type_text(): Type a string of characters
+"""
+
+import json
+import socket
+import time
+
+from loguru import logger
+
+from .dbx_kbd import DBX_KEY, DBX_KEY_TO_QCODE, char_needs_shift, char_to_qcode
+
+
+class QMPError(Exception):
+    """QMP protocol error."""
+
+    pass
+
+
+class QMPClient:
+    """QEMU Monitor Protocol client for DOSBox-X keyboard input."""
+
+    DEFAULT_PORT = 4444
+
+    def __init__(self, host: str = "localhost", port: int = DEFAULT_PORT):
+        """
+        Connect to DOSBox-X QMP server.
+
+        Args:
+            host: Server hostname
+            port: Server port (default 4444)
+        """
+        logger.debug(f"Connecting to QMP server at {host}:{port}")
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.sock.connect((host, port))
+        self.buffer = ""
+
+        # Read greeting
+        greeting = self._read_message()
+        logger.debug(f"QMP greeting: {greeting}")
+
+        if "QMP" not in greeting:
+            raise QMPError(f"Unexpected QMP greeting: {greeting}")
+
+        # Send capabilities negotiation
+        self._send_command("qmp_capabilities")
+        logger.debug("QMP capabilities negotiated")
+
+    def _send_raw(self, data: str) -> None:
+        """Send raw string to server."""
+        if self.sock is None:
+            raise ConnectionError("Socket not initialized")
+        self.sock.sendall((data + "\r\n").encode())
+
+    def _read_message(self) -> dict:
+        """Read a JSON message from the server."""
+        if self.sock is None:
+            raise ConnectionError("Socket not initialized")
+
+        while True:
+            # Look for complete JSON object in buffer
+            if self.buffer:
+                try:
+                    # Try to parse what we have
+                    msg = json.loads(self.buffer.strip())
+                    self.buffer = ""
+                    return msg
+                except json.JSONDecodeError:
+                    pass
+
+            # Need more data
+            data = self.sock.recv(4096).decode()
+            if not data:
+                raise ConnectionError("Connection closed")
+            self.buffer += data
+
+            # Try to find complete message (newline-delimited)
+            if "\n" in self.buffer:
+                line, self.buffer = self.buffer.split("\n", 1)
+                if line.strip():
+                    return json.loads(line.strip())
+
+    def _send_command(self, execute: str, arguments: dict | None = None) -> dict:
+        """
+        Send a QMP command and return the response.
+
+        Args:
+            execute: Command name
+            arguments: Optional command arguments
+
+        Returns:
+            Response dict
+
+        Raises:
+            QMPError: If command returns an error
+        """
+        cmd: dict = {"execute": execute}
+        if arguments:
+            cmd["arguments"] = arguments
+
+        self._send_raw(json.dumps(cmd))
+        response = self._read_message()
+
+        if "error" in response:
+            error = response["error"]
+            raise QMPError(f"{error.get('class', 'Error')}: {error.get('desc', 'Unknown error')}")
+
+        return response
+
+    def send_key(self, keys: list[str], hold_time: int = 100) -> None:
+        """
+        Send simultaneous key presses with auto-release.
+
+        All keys are pressed, held for hold_time ms, then released in reverse order.
+
+        Args:
+            keys: List of QMP qcode strings (e.g., ["ctrl", "alt", "delete"])
+            hold_time: Milliseconds to hold before releasing (default 100)
+
+        Example:
+            >>> qmp.send_key(["ctrl", "c"])  # Ctrl+C
+            >>> qmp.send_key(["a"])  # Press 'a'
+        """
+        key_objects = [{"type": "qcode", "data": k} for k in keys]
+        self._send_command("send-key", {"keys": key_objects, "hold-time": hold_time})
+
+    def send_key_dbx(self, keys: list[DBX_KEY], hold_time: int = 100) -> None:
+        """
+        Send keys using DBX_KEY enum values.
+
+        Args:
+            keys: List of DBX_KEY values
+            hold_time: Milliseconds to hold before releasing
+
+        Example:
+            >>> qmp.send_key_dbx([DBX_KEY.KBD_leftctrl, DBX_KEY.KBD_c])
+        """
+        qcodes = []
+        for key in keys:
+            qcode = DBX_KEY_TO_QCODE.get(key)
+            if qcode is None:
+                raise ValueError(f"No QMP mapping for key: {key.name}")
+            qcodes.append(qcode)
+        self.send_key(qcodes, hold_time)
+
+    def key_down(self, key: str) -> None:
+        """
+        Send a key press (down) event.
+
+        Args:
+            key: QMP qcode string
+        """
+        event = {
+            "type": "key",
+            "data": {"down": True, "key": {"type": "qcode", "data": key}},
+        }
+        self._send_command("input-send-event", {"events": [event]})
+
+    def key_up(self, key: str) -> None:
+        """
+        Send a key release (up) event.
+
+        Args:
+            key: QMP qcode string
+        """
+        event = {
+            "type": "key",
+            "data": {"down": False, "key": {"type": "qcode", "data": key}},
+        }
+        self._send_command("input-send-event", {"events": [event]})
+
+    def key_press(self, key: str, hold_time: float = 0.05) -> None:
+        """
+        Press and release a single key with timing control.
+
+        Args:
+            key: QMP qcode string
+            hold_time: Seconds to hold (default 0.05)
+        """
+        self.key_down(key)
+        time.sleep(hold_time)
+        self.key_up(key)
+
+    def type_text(self, text: str, delay: float = 0.05) -> None:
+        """
+        Type a string of text.
+
+        Handles shift for uppercase and special characters.
+
+        Args:
+            text: Text to type
+            delay: Delay between characters in seconds (default 0.05)
+
+        Example:
+            >>> qmp.type_text("Hello World!")
+        """
+        for char in text:
+            qcode = char_to_qcode(char)
+            if qcode is None:
+                logger.warning(f"Cannot type character: {repr(char)}")
+                continue
+
+            if char_needs_shift(char):
+                # Hold shift, press key, release key, release shift
+                self.key_down("shift")
+                time.sleep(0.01)
+                self.key_press(qcode, 0.03)
+                self.key_up("shift")
+            else:
+                self.key_press(qcode, 0.03)
+
+            time.sleep(delay)
+
+    def query_commands(self) -> list[str]:
+        """
+        Query available QMP commands.
+
+        Returns:
+            List of command names
+        """
+        response = self._send_command("query-commands")
+        return [cmd["name"] for cmd in response.get("return", [])]
+
+    def close(self) -> None:
+        """Close the connection."""
+        if self.sock:
+            self.sock.close()
+            self.sock = None  # type: ignore
+
+    def __enter__(self) -> "QMPClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

dbxdebug/utils.py

@@ -0,0 +1,92 @@
+"""
+Utility functions for address parsing and hex dumps.
+"""
+
+import re
+
+
+def parse_x86_address(address_str: str | int) -> int:
+    """
+    Parse an x86 address and convert to linear address.
+
+    Supports:
+    - Segmented addresses: "XXXX:YYYY" or "0xXXXX:YYYY"
+    - Linear hex: "0x12345" or "12345"
+    - Integer passthrough
+
+    Args:
+        address_str: Address as string or int
+
+    Returns:
+        Linear address as integer
+
+    Raises:
+        ValueError: If address format is invalid
+    """
+    if isinstance(address_str, int):
+        return address_str
+
+    # Check if it's a segmented address
+    segment_match = re.match(r"(?:0x)?([0-9a-fA-F]+):([0-9a-fA-F]+)", address_str)
+    if segment_match:
+        segment = int(segment_match.group(1), 16)
+        offset = int(segment_match.group(2), 16)
+        # Linear address: segment * 16 + offset
+        return (segment << 4) + offset
+
+    # Try to interpret as a normal hex or decimal number
+    try:
+        return int(address_str, 0)
+    except ValueError as e:
+        raise ValueError(
+            f"Invalid address format: {address_str}. "
+            "Use segment:offset (e.g., b800:0000) or linear address."
+        ) from e
+
+
+def hexdump(
+    src: bytes,
+    bytes_per_line: int = 32,
+    bytes_per_group: int = 4,
+    sep: str = ".",
+    start_addr: int = 0,
+) -> list[str]:
+    """
+    Generate a hex dump of binary data.
+
+    Args:
+        src: Binary data to dump
+        bytes_per_line: Number of bytes per line
+        bytes_per_group: Group bytes with spaces
+        sep: Character for non-printable bytes
+        start_addr: Starting address for display
+
+    Returns:
+        List of formatted hex dump lines
+    """
+    FILTER = "".join([(len(repr(chr(x))) == 3) and chr(x) or sep for x in range(256)])
+    lines = []
+    max_addr_len = max(8, len(hex(start_addr + len(src))))
+
+    for offset in range(0, len(src), bytes_per_line):
+        addr = start_addr + offset
+        chars = src[offset : offset + bytes_per_line]
+
+        # Create hex string
+        hex_parts = []
+        for i in range(0, len(chars), bytes_per_group):
+            group = chars[i : i + bytes_per_group]
+            hex_parts.append("".join(f"{b:02X}" for b in group))
+        hex_string = " ".join(hex_parts)
+
+        # Pad to align with full lines
+        full_groups = bytes_per_line // bytes_per_group
+        expected_len = full_groups * (bytes_per_group * 2) + (full_groups - 1)
+        hex_string = hex_string.ljust(expected_len)
+
+        # Create printable string
+        printable = "".join((x <= 127 and FILTER[x]) or sep for x in chars)
+
+        lines.append(f"{addr:0{max_addr_len}X}  {hex_string}  |{printable}|")
+
+    return lines