window-snap 0.1.2__tar.gz

window_snap-0.1.2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: window-snap
+Version: 0.1.2
+Summary: Snap windows to their configured positions
+License: MIT
+Author: Maker By Night
+Author-email: 2565361+mshafer1@users.noreply.github.com
+Requires-Python: >=3.11,<4
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Dist: click (>=8.4.1,<9.0.0)
+Requires-Dist: python-decouple (>=3.8,<4.0)
+Requires-Dist: pywin32 (>=312,<313)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: screeninfo (>=0.8.1,<0.9.0)

window_snap-0.1.2/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "window-snap"
+version = "0.1.2"
+description = "Snap windows to their configured positions"
+authors = [
+    {name = "Maker By Night",email = "2565361+mshafer1@users.noreply.github.com"}
+]
+license = "MIT"
+requires-python = ">=3.11,<4"
+dynamic = ["dependencies"]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+]
+
+[tool.poetry.dependencies]
+pyyaml = "^6.0.3"
+click = "^8.4.1"
+python-decouple = "^3.8"
+screeninfo = "^0.8.1"
+pywin32 = "^312"
+
+[tool.poetry.scripts]
+window-snap = "window_snap.__main__:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "ni-python-styleguide (>=0.5.0,<0.6.0)",
+    "flake8-logging (>=1.8.0,<2.0.0)"
+]

window_snap-0.1.2/window_snap/__init__.py

@@ -0,0 +1,383 @@
+"""Module to snap windows to specified positions/sizes based on a YAML configuration."""
+
+import functools
+import logging
+import pathlib
+import typing
+
+import screeninfo
+import win32con
+import win32gui
+import yaml
+
+import window_snap
+import window_snap._win32_helpers
+
+_logger = logging.getLogger(__name__)
+_logger.addHandler(logging.NullHandler())  # make sure there is a default handler available
+
+
+def load_config(config_path: str | pathlib.Path) -> dict:
+    """Load YAML configuration from a file.
+
+    Args:
+        config_path: Path to the YAML config file.
+
+    Returns:
+        Parsed configuration as a dict. Returns an empty dict if the file
+        does not exist.
+
+    Raises:
+        yaml.YAMLError: If the YAML cannot be parsed.
+    """
+    try:
+        with open(config_path, "r") as f:
+            config = yaml.load(f, Loader=yaml.CSafeLoader)
+        return config
+    except FileNotFoundError:
+        _logger.warning("Config file not found: %s", config_path)
+        return {}
+    except yaml.YAMLError as e:
+        _logger.exception("Error parsing config file %s: %s", config_path, e)
+        raise
+
+
+@functools.lru_cache(maxsize=1)
+def _get_screen_info() -> typing.List[screeninfo.screeninfo.Monitor]:
+    return list(sorted(screeninfo.screeninfo.get_monitors(), key=lambda m: (m.x, m.y)))
+
+
+def _dataclass_representer(dumper, data):
+    # This automatically converts the NamedTuple to a plain dict behind the scenes
+    return dumper.represent_dict({k: v for k, v in data._asdict().items() if v is not None})
+
+
+class WindowSnapDestination(typing.NamedTuple):
+    """Destination specification for snapping a window.
+
+    Attributes:
+        monitor: Optional index of the monitor to move the window to.
+        left: Left position or fraction of the work area width.
+        top: Top position or fraction of the work area height.
+        width: Width in pixels or fraction of the work area width.
+        height: Height in pixels or fraction of the work area height.
+        maximized: If True, maximize the window on the target monitor/work area.
+        find_by_exe: If True, treat the name as an executable and find windows by exe.
+    """
+
+    monitor: typing.Optional[int] = None
+    left: typing.Optional[float] = None
+    top: typing.Optional[float] = None
+    width: typing.Optional[float] = None
+    height: typing.Optional[float] = None
+    maximized: typing.Optional[bool] = None
+    find_by_exe: typing.Optional[bool] = None
+
+
+yaml.SafeDumper.add_multi_representer(WindowSnapDestination, _dataclass_representer)
+
+
+def get_current_windows() -> typing.Dict[str, WindowSnapDestination]:
+    """Enumerate current top-level windows and return their positions.
+
+    Returns:
+        A dict mapping window title to a `WindowSnapDestination` describing
+        the window's current position/size.
+    """
+    current_windows = {}
+    more_than_one_screen = len(_get_screen_info()) > 1
+    for w in window_snap._win32_helpers.enum_windows():
+        title = w.get("title")
+        rect = w.get("rect")
+        if not title:
+            continue
+        pos_args = {}
+        hwnd = w.get("hwnd")
+        # detect maximized/minimized state via window placement
+        is_maximized = False
+        if hwnd:
+            try:
+                placement = win32gui.GetWindowPlacement(hwnd)
+                show_cmd = placement[1]
+                if show_cmd == win32con.SW_SHOWMINIMIZED:
+                    continue
+                is_maximized = show_cmd == win32con.SW_SHOWMAXIMIZED
+            except Exception:
+                pass
+        # rect is (left, top, width, height)
+        if rect:
+            left, top, width, height = rect
+            if is_maximized or width == 0 or height == 0:
+                pos_args["maximized"] = True
+            else:
+                pos_args.update({"left": left, "top": top, "width": width, "height": height})
+            if more_than_one_screen:
+                monitor_info = _find_monitor_by_rect(left, top, width, height)
+                if monitor_info is not None:
+                    monitor_index, _ = monitor_info
+                    pos_args["monitor"] = monitor_index + 1  # 1-indexed
+        current_windows[title] = WindowSnapDestination(**pos_args)
+    return current_windows
+
+
+def find_exe_names():
+    """Return a mapping of window titles to their executable names.
+
+    Attempts to build a map of window title -> exe (lowercased) using the
+    PID->exe mapping from `win32_helpers`.
+
+    Returns:
+        dict: mapping of window title to executable filename (lowercased).
+    """
+    title_to_exe_map = {}
+    try:
+        pid_map = window_snap._win32_helpers.get_pid_to_exe_map()
+        for w in window_snap._win32_helpers.enum_windows():
+            title = w.get("title")
+            pid = w.get("pid")
+            if title and pid:
+                exe = pid_map.get(pid)
+                if exe:
+                    title_to_exe_map[title] = exe.lower()
+    except Exception as e:
+        _logger.debug("failed get exe names via win32 helpers: %s", e)
+    return title_to_exe_map
+
+
+def _find_monitor_by_rect(left: int, top: int, width: int, height: int):
+    win_center_x = left + (width // 2)
+    win_center_y = top + (height // 2)
+
+    monitors = _get_screen_info()
+    for index, monitor in enumerate(monitors):
+        inside_x = monitor.x <= win_center_x < (monitor.x + monitor.width)
+        inside_y = monitor.y <= win_center_y < (monitor.y + monitor.height)
+        if inside_x and inside_y:
+            return index, monitor
+
+    _logger.warning("Could not determine monitor for rect %s,%s %sx%s", left, top, width, height)
+    return None
+
+
+def _scale_to_dimension(value: typing.Union[float, int, None], dimension: int, base: int):
+    if value is None:
+        return None
+    if (
+        0 < value <= 1
+    ):  # it's a float. 0 means "at the point", 0<x<1 is percentage. 1 is full. Anything other then that is a pixel value.
+        return int(value * dimension) + base
+    else:  # absolute value integer
+        return int(value) + base
+
+
+def snap_window(window_title: str, destination: WindowSnapDestination):
+    """Snap a single window to the provided destination.
+
+    Args:
+        window_title: The window title or executable name (if
+            `destination.find_by_exe` is True).
+        destination: A `WindowSnapDestination` describing where/how to place
+            the window.
+    """
+    _logger.info("Snapping window '%s' to destination: %s", window_title, destination)
+
+    try:
+        hwnd = None
+        if destination.find_by_exe:
+            # window_title here is expected to be an exe name
+            hwnds = window_snap._win32_helpers.find_hwnds_by_exe(window_title)
+            if not hwnds:
+                _logger.warning("No window found for exe '%s', skipping", window_title)
+                return
+            hwnd = hwnds[0]
+        else:
+            hwnds = window_snap._win32_helpers.find_hwnds_by_title(window_title)
+            if not hwnds:
+                _logger.warning("Window '%s' not found, skipping", window_title)
+                return
+            hwnd = hwnds[0]
+    except IndexError:
+        _logger.info("Window '%s' not found, skipping", window_title)
+        return
+    # ensure window is not minimized or maximized before moving/resizing
+    try:
+        win32gui.ShowWindow(hwnd, win32con.SW_RESTORE)
+    except Exception:
+        pass
+
+    # Perform the window snapping logic here
+    _logger.info(
+        "Window '%s' found (hwnd=%s), snapping to destination: %s", window_title, hwnd, destination
+    )
+    screens = _get_screen_info()
+
+    if destination.monitor is not None and destination.monitor >= len(screens):
+        _logger.warning(
+            "Monitor index %d is out of range, skipping monitor assignment", destination.monitor
+        )
+        destination = WindowSnapDestination(
+            monitor=None,
+            left=destination.left,
+            top=destination.top,
+            width=destination.width,
+            height=destination.height,
+            maximized=destination.maximized,
+            find_by_exe=destination.find_by_exe,
+        )
+
+    if destination.monitor is not None:
+        # move to desired monitor
+        if destination.monitor >= len(screens):
+            _logger.warning(
+                "Monitor index %d is out of range, skipping monitor assignment", destination.monitor
+            )
+            return
+
+        screen = screens[destination.monitor]
+        work_left, work_top, work_width, work_height = (
+            window_snap._win32_helpers.get_monitor_work_area_at_point(screen.x + 1, screen.y + 1)
+        )
+
+        if destination.maximized:
+            try:
+                win32gui.SetWindowPos(
+                    hwnd,
+                    None,
+                    work_left,
+                    work_top,
+                    0,
+                    0,
+                    win32con.SWP_NOSIZE | win32con.SWP_NOZORDER,
+                )
+                win32gui.ShowWindow(hwnd, win32con.SW_MAXIMIZE)
+            except Exception:
+                pass
+        else:
+            left, top, width, height = (
+                _scale_to_dimension(v, dimension, pos)
+                for v, dimension, pos in [
+                    (destination.left, work_width, work_left),
+                    (destination.top, work_height, work_top),
+                    (destination.width, work_width, 0),
+                    (destination.height, work_height, 0),
+                ]
+            )
+
+            _logger.debug("Handling %s as %s", destination, (left, top, width, height))
+            if left is not None and top is not None and width is not None and height is not None:
+                window_snap._win32_helpers.set_window_pos(
+                    hwnd, left, top, width, height, activate=False
+                )
+            else:
+                # partial updates
+                try:
+                    cur_left, cur_top, cur_w, cur_h = window_snap._win32_helpers.get_window_rect(
+                        hwnd
+                    )
+                    nl = left if left is not None else cur_left
+                    nt = top if top is not None else cur_top
+                    nw = width if width is not None else cur_w
+                    nh = height if height is not None else cur_h
+                    window_snap._win32_helpers.set_window_pos(hwnd, nl, nt, nw, nh, activate=False)
+                except Exception:
+                    pass
+    else:
+        # no monitor specified, just apply position/size changes
+        if destination.maximized:
+            try:
+                win32gui.ShowWindow(hwnd, win32con.SW_MAXIMIZE)
+            except Exception:
+                pass
+        else:
+            try:
+                cur_left, cur_top, cur_w, cur_h = window_snap._win32_helpers.get_window_rect(hwnd)
+                monitor_info = _find_monitor_by_rect(cur_left, cur_top, cur_w, cur_h)
+                if monitor_info is None:
+                    _logger.debug(
+                        "Could not determine monitor for hwnd %s, using primary monitor", hwnd
+                    )
+                    monitor = screens[0]
+                    work_left, work_top, work_width, work_height = (
+                        window_snap._win32_helpers.get_monitor_work_area_at_point(
+                            monitor.x + 1, monitor.y + 1
+                        )
+                    )
+                else:
+                    _, monitor = monitor_info
+                    work_left, work_top, work_width, work_height = (
+                        window_snap._win32_helpers.get_monitor_work_area_at_point(
+                            cur_left + 1, cur_top + 1
+                        )
+                    )
+
+                left, top, width, height = (
+                    _scale_to_dimension(v, dimension, pos)
+                    for v, dimension, pos in [
+                        (destination.left, work_width, work_left),
+                        (destination.top, work_height, work_top),
+                        (destination.width, work_width, 0),
+                        (destination.height, work_height, 0),
+                    ]
+                )
+
+                _logger.debug("Handling %s as %s", destination, (left, top, width, height))
+                if (
+                    left is not None
+                    and top is not None
+                    and width is not None
+                    and height is not None
+                ):
+                    window_snap._win32_helpers.set_window_pos(
+                        hwnd, left, top, width, height, activate=False
+                    )
+                else:
+                    cur_left, cur_top, cur_w, cur_h = window_snap._win32_helpers.get_window_rect(
+                        hwnd
+                    )
+                    nl = left if left is not None else cur_left
+                    nt = top if top is not None else cur_top
+                    nw = width if width is not None else cur_w
+                    nh = height if height is not None else cur_h
+                    window_snap._win32_helpers.set_window_pos(hwnd, nl, nt, nw, nh, activate=False)
+            except Exception as e:
+                _logger.debug("failed to reposition hwnd %s: %s", hwnd, e)
+
+
+def snap_windows(config):
+    """Apply snapping rules from configuration to all named windows.
+
+    Args:
+        config: Configuration dict which may contain a `windows` mapping.
+    """
+    windows = (config or {}).get("windows")
+    if not windows:
+        _logger.debug("No 'windows' configuration found; nothing to snap.")
+        return
+    for window_name, snap_config in windows.items():
+        _logger.debug("Processing window '%s' with config: %s", window_name, snap_config)
+        try:
+            monitor_value = snap_config.get("monitor") if isinstance(snap_config, dict) else None
+            if monitor_value is not None:
+                if not isinstance(monitor_value, int) or monitor_value < 1:
+                    _logger.warning(
+                        "Invalid monitor value %r for window '%s': must be an integer >= 1, skipping monitor assignment.",
+                        monitor_value,
+                        window_name,
+                    )
+                    snap_config = {k: v for k, v in snap_config.items() if k != "monitor"}
+            destination = window_snap.WindowSnapDestination(
+                **{
+                    k: (v if k != "monitor" else v - 1)  # convert monitor to 0-indexed internally
+                    for k, v in snap_config.items()
+                    if k in window_snap.WindowSnapDestination._fields
+                }
+            )
+        except TypeError as e:
+            _logger.exception(
+                "Invalid configuration for window '%s': %s. Error: %s", window_name, snap_config, e
+            )
+            continue
+        try:
+            window_snap.snap_window(window_name, destination)
+        except Exception as e:
+            _logger.exception("Error occurred while snapping window '%s': %s", window_name, e)

window_snap-0.1.2/window_snap/__main__.py

@@ -0,0 +1,71 @@
+"""Main entry point for the window_snap command-line tool."""
+
+import logging
+
+import click
+import yaml
+
+import window_snap
+import window_snap._conf
+
+_logger = logging.getLogger(__name__)
+
+
+@click.command()
+@click.version_option()
+@click.option(
+    "verbosity",
+    "-v",
+    "--verbose",
+    count=True,
+    help="Increase verbosity (can be used multiple times)",
+)
+@click.option(
+    "--store-current",
+    is_flag=True,
+    help="Store the current position and size of all windows in the config file instead of snapping",
+)
+def main(verbosity: int, store_current: bool):
+    """Snap windows to desired locations.
+
+    Load window positions/sizes from a config file and snap windows accordingly,
+    or store current positions/sizes if --store-current is used.
+    """
+    my_handler = logging.StreamHandler()
+    logging_level = logging.WARNING - (10 * verbosity) if verbosity > 0 else logging.WARNING
+    my_handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    )
+    root_logger = logging.getLogger(None)
+    root_logger.setLevel(logging_level)
+    root_logger.addHandler(my_handler)
+    _logger.debug("Debug logging enabled")  # this will only show if verbosity is set to 2 or higher
+
+    config_path = window_snap._conf.CONFIG_DIR / "config.yaml"
+
+    if store_current:
+        _logger.info("Storing current window positions and sizes to %s", config_path)
+        current_windows = window_snap.get_current_windows()
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        exe_names = window_snap.find_exe_names()
+        with open(config_path, "w") as f:
+            yaml.dump(
+                {
+                    "_config_version": window_snap._conf.CONFIG_VERSION,
+                    "windows": current_windows,
+                    "available_exe_names": exe_names,
+                },
+                f,
+                Dumper=yaml.SafeDumper,
+            )
+        _logger.info("Current window positions and sizes stored successfully")
+        return
+    else:
+        _logger.info("Loading configuration from %s", config_path)
+        config = window_snap.load_config(config_path)
+
+        window_snap.snap_windows(config)
+
+
+if __name__ == "__main__":
+    main()

window_snap-0.1.2/window_snap/_conf.py

@@ -0,0 +1,13 @@
+import pathlib as _pathlib
+
+import decouple as _decouple
+
+_config = _decouple.AutoConfig(search_path=_pathlib.Path.cwd())
+
+CONFIG_DIR: _pathlib.Path = _config(
+    "WINDOW_SNAP_CONFIG_DIR",
+    default=_pathlib.Path.home() / ".config" / "window-snap",
+    cast=_pathlib.Path,
+)
+
+CONFIG_VERSION = "0.1.0"

window_snap-0.1.2/window_snap/_win32_helpers.py

@@ -0,0 +1,275 @@
+import ctypes
+import ctypes.wintypes
+import difflib
+import os
+import time
+import typing
+
+import win32api
+import win32con
+import win32gui
+import win32process
+
+# Toolhelp constants
+TH32CS_SNAPPROCESS = 0x00000002
+
+
+if ctypes.sizeof(ctypes.c_void_p) == 8:
+    ULONG_PTR = ctypes.c_uint64
+else:
+    ULONG_PTR = ctypes.c_uint32
+
+
+class PROCESSENTRY32W(ctypes.Structure):
+    """Structure for process entry used with CreateToolhelp32Snapshot."""
+
+    _fields_ = [
+        ("dwSize", ctypes.wintypes.DWORD),
+        ("cntUsage", ctypes.wintypes.DWORD),
+        ("th32ProcessID", ctypes.wintypes.DWORD),
+        ("th32DefaultHeapID", ULONG_PTR),
+        ("th32ModuleID", ctypes.wintypes.DWORD),
+        ("cntThreads", ctypes.wintypes.DWORD),
+        ("th32ParentProcessID", ctypes.wintypes.DWORD),
+        ("pcPriClassBase", ctypes.wintypes.LONG),
+        ("dwFlags", ctypes.wintypes.DWORD),
+        ("szExeFile", ctypes.c_wchar * 260),
+    ]
+
+
+def enum_windows() -> typing.List[typing.Dict]:
+    """Enumerate visible top-level windows.
+
+    Returns:
+        List[Dict]: A list of window dictionaries containing hwnd, title, pid, and rect.
+    """
+    results = []
+
+    def _cb(hwnd, _):
+        if not win32gui.IsWindowVisible(hwnd):
+            return True
+        try:
+            title = win32gui.GetWindowText(hwnd).strip()
+        except Exception:
+            title = ""
+        if not title:
+            return True
+        try:
+            _, pid = win32process.GetWindowThreadProcessId(hwnd)
+            rect = win32gui.GetWindowRect(hwnd)
+            x1, y1, x2, y2 = rect
+            width = x2 - x1
+            height = y2 - y1
+            if width <= 10 or height <= 10:
+                return True
+            results.append(
+                {"hwnd": hwnd, "title": title, "pid": pid, "rect": (x1, y1, width, height)}
+            )
+        except Exception:
+            pass
+        return True
+
+    win32gui.EnumWindows(_cb, None)
+    return results
+
+
+def get_window_rect(hwnd: int) -> typing.Tuple[int, int, int, int]:
+    """Return the window rectangle in left/top/width/height format.
+
+    Args:
+        hwnd (int): Handle to the target window.
+
+    Returns:
+        Tuple[int, int, int, int]: A tuple of (left, top, width, height).
+    """
+    x1, y1, x2, y2 = win32gui.GetWindowRect(hwnd)
+    return x1, y1, x2 - x1, y2 - y1
+
+
+def get_monitor_work_area_at_point(x: int, y: int) -> typing.Tuple[int, int, int, int]:
+    """Return the work area rectangle for the monitor containing a point.
+
+    Args:
+        x (int): X coordinate of the point.
+        y (int): Y coordinate of the point.
+
+    Returns:
+        Tuple[int, int, int, int]: A tuple of (left, top, width, height) for the monitor work area.
+    """
+    hmonitor = win32api.MonitorFromPoint((x, y), win32con.MONITOR_DEFAULTTONEAREST)
+    info = win32api.GetMonitorInfo(hmonitor)
+    left, top, right, bottom = info["Work"]
+    return left, top, right - left, bottom - top
+
+
+def set_window_pos(
+    hwnd: int, left: int, top: int, width: int, height: int, activate: bool = False
+) -> None:
+    """Position and resize a window without changing its z-order.
+
+    Args:
+        hwnd (int): Handle to the target window.
+        left (int): New left position.
+        top (int): New top position.
+        width (int): New window width.
+        height (int): New window height.
+        activate (bool): If True, activate the window after moving it.
+    """
+    flags = win32con.SWP_NOZORDER | win32con.SWP_NOOWNERZORDER
+    if not activate:
+        flags |= win32con.SWP_NOACTIVATE
+    win32gui.SetWindowPos(hwnd, None, left, top, width, height, flags)
+
+
+# Simple TTL cache for pid->exe mapping
+_pid_exe_cache: typing.Dict[int, typing.Tuple[str, float]] = {}
+_cache_ttl_seconds = 2.0
+
+
+def _build_pid_to_exe_map() -> typing.Dict[int, str]:
+    kernel32 = ctypes.windll.kernel32
+
+    # Set proper argtypes/restype so HANDLE values are not truncated on 64-bit Python
+    kernel32.CreateToolhelp32Snapshot.argtypes = [ctypes.wintypes.DWORD, ctypes.wintypes.DWORD]
+    kernel32.CreateToolhelp32Snapshot.restype = ctypes.wintypes.HANDLE
+    kernel32.Process32FirstW.argtypes = [ctypes.wintypes.HANDLE, ctypes.POINTER(PROCESSENTRY32W)]
+    kernel32.Process32FirstW.restype = ctypes.wintypes.BOOL
+    kernel32.Process32NextW.argtypes = [ctypes.wintypes.HANDLE, ctypes.POINTER(PROCESSENTRY32W)]
+    kernel32.Process32NextW.restype = ctypes.wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [ctypes.wintypes.HANDLE]
+    kernel32.CloseHandle.restype = ctypes.wintypes.BOOL
+
+    invalid_handle_value = ctypes.c_void_p(-1).value
+    snapshot = kernel32.CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0)
+    if snapshot == invalid_handle_value or snapshot is None:
+        raise RuntimeError("CreateToolhelp32Snapshot failed")
+
+    entry = PROCESSENTRY32W()
+    entry.dwSize = ctypes.sizeof(PROCESSENTRY32W)
+    pid_to_exe: typing.Dict[int, str] = {}
+
+    try:
+        success = kernel32.Process32FirstW(snapshot, ctypes.byref(entry))
+        while success:
+            pid = entry.th32ProcessID
+            exe = entry.szExeFile
+            pid_to_exe[pid] = exe
+            success = kernel32.Process32NextW(snapshot, ctypes.byref(entry))
+    finally:
+        kernel32.CloseHandle(snapshot)
+
+    return pid_to_exe
+
+
+def get_pid_to_exe_map(force_refresh: bool = False) -> typing.Dict[int, str]:
+    """Return a cached mapping of process IDs to executable names.
+
+    Args:
+        force_refresh (bool): If True, rebuild the process map even if the cache is fresh.
+
+    Returns:
+        Dict[int, str]: A mapping from PID to executable filename.
+    """
+    global _pid_exe_cache
+    now = time.time()
+    if force_refresh:
+        _pid_exe_cache.clear()
+    # If cache empty or expired, rebuild
+    if not _pid_exe_cache or any(
+        now - ts > _cache_ttl_seconds for _, ts in _pid_exe_cache.values()
+    ):
+        pid_map = _build_pid_to_exe_map()
+        _pid_exe_cache = {pid: (exe, now) for pid, exe in pid_map.items()}
+    return {pid: exe for pid, (exe, ts) in _pid_exe_cache.items()}
+
+
+def find_hwnds_by_title(title: str) -> typing.List[int]:
+    """Return visible top-level window handles matching a title query.
+
+    Uses difflib.get_close_matches to sort candidate titles by similarity.
+
+    Args:
+        title (str): Window title query.
+
+    Returns:
+        List[int]: Matching window handles sorted by closest title matches.
+    """
+    query = title.strip()
+    if not query:
+        return []
+
+    title_to_hwnds: typing.Dict[str, typing.List[int]] = {}
+
+    def _cb(hwnd, _):
+        try:
+            if not win32gui.IsWindowVisible(hwnd):
+                return True
+            t = win32gui.GetWindowText(hwnd).strip()
+            if not t:
+                return True
+            title_to_hwnds.setdefault(t, []).append(hwnd)
+        except Exception:
+            pass
+        return True
+
+    win32gui.EnumWindows(_cb, None)
+    if not title_to_hwnds:
+        return []
+
+    ordered_titles = difflib.get_close_matches(
+        query, list(title_to_hwnds.keys()), n=len(title_to_hwnds), cutoff=0.0
+    )
+
+    # Keep exact-match titles first when present.
+    if query in title_to_hwnds:
+        ordered_titles = [query] + [t for t in ordered_titles if t != query]
+
+    ordered_hwnds: typing.List[int] = []
+    for matched_title in ordered_titles:
+        ordered_hwnds.extend(title_to_hwnds.get(matched_title, []))
+    return ordered_hwnds
+
+
+def find_hwnds_by_exe(exe_name: str) -> typing.List[int]:
+    """Return window handles for processes matching an executable name.
+
+    This normalizes names by stripping paths and extensions so callers can pass
+    either 'chrome', 'chrome.exe', or a full path.
+
+    Args:
+        exe_name (str): Executable name or path to match.
+
+    Returns:
+        List[int]: List of matching window handles.
+    """
+
+    def _norm(n: str) -> str:
+        if not n:
+            return ""
+        # if a bytes-like got here, convert
+        try:
+            n = str(n)
+        except Exception:
+            pass
+        base = os.path.basename(n)
+        name, _ext = os.path.splitext(base)
+        return name.lower()
+
+    pid_map = get_pid_to_exe_map()
+    target_pids = {pid for pid, exe in pid_map.items() if _norm(exe) == _norm(exe_name)}
+    if not target_pids:
+        return []
+    matches: typing.List[int] = []
+    def _cb(hwnd, _):
+        try:
+            if not win32gui.IsWindowVisible(hwnd):
+                return True
+            _, pid = win32process.GetWindowThreadProcessId(hwnd)
+            if pid in target_pids:
+                matches.append(hwnd)
+        except Exception:
+            pass
+        return True
+
+    win32gui.EnumWindows(_cb, None)
+    return matches