python-win-windows-manager 0.1.0__py3-none-any.whl

python_win_windows_manager-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: python-win-windows-manager
+Version: 0.1.0
+Summary: Window manager and monitor for Windows
+Project-URL: Homepage, https://github.com/username/repo
+Requires-Python: >=3.13
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pywin32>=311
+Description-Content-Type: text/markdown
+
+# Windows Window Manager
+
+A Python library for managing Windows windows using `win32gui` and `ctypes`. This project provides a robust interface for identifying, controlling, and monitoring windows on Windows systems.
+
+## Features
+
+- **Window Identification**: Get detailed information about all open windows (Handle, Title, Class Name, PID, Process Name).
+- **Window Search**: Find windows by title or class name with exact or partial matching.
+- **Window Control**:
+  - Minimize, Maximize, Restore
+  - Close
+  - Move and Resize
+  - Set to Foreground
+- **Real-time Monitoring**: Monitor window creation, destruction, and state changes.
+- **Robust Error Handling**: Handles permissions and invalid handles gracefully.
+
+## Installation
+
+This project uses `uv` for dependency management.
+
+1.  Clone the repository.
+2.  Install dependencies:
+    ```bash
+    uv sync
+    ```
+
+## Usage
+
+### Basic Example
+
+```python
+from window_manager import WindowManager
+
+manager = WindowManager()
+
+# List all visible windows
+windows = manager.get_all_windows(visible_only=True)
+for window in windows:
+    print(window)
+
+# Find a window
+notepad = manager.find_windows(title="Notepad")[0]
+
+# Minimize
+manager.minimize_window(notepad.handle)
+
+# Restore
+manager.restore_window(notepad.handle)
+```
+
+### Monitoring Example
+
+```python
+import time
+from window_manager import WindowMonitor
+
+def callback(event, hwnd, title):
+    print(f"Event: {event}, Window: {title}")
+
+monitor = WindowMonitor(callback=callback)
+monitor.start()
+
+try:
+    while True:
+        time.sleep(1)
+except KeyboardInterrupt:
+    monitor.stop()
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests
+```
+
+## Documentation
+
+See [docs/API.md](docs/API.md) for detailed API documentation.

python_win_windows_manager-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+window_manager/__init__.py,sha256=FxlCI6bfeJ5cHQkSju9MsCd_vGV9f93J6CODRtNV4zc,206
+window_manager/core.py,sha256=ARqSygz2h60acJRVLFf4-X4jwQn47Sv8uq-8PLa8pA8,8228
+window_manager/models.py,sha256=ww4xM4rKU61YFM7MFMkQ5xBxQ_zN5vLxT4ekg4WJdSw,599
+window_manager/monitor.py,sha256=xJ1m62war7U-h-g5qBHgYhhLaQnxYmsOPHi__mkIRs8,5270
+window_manager/utils.py,sha256=ydugYw0ZBnOUHzMi6hJwYvIJZv3tl4GDxumkgnKSDLA,1099
+python_win_windows_manager-0.1.0.dist-info/METADATA,sha256=t30vUbsvNfTUzwgI7jAkbMnZJqIpUlA8Z5LRKIOGH-0,2025
+python_win_windows_manager-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_win_windows_manager-0.1.0.dist-info/RECORD,,

python_win_windows_manager-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

window_manager/__init__.py

@@ -0,0 +1,6 @@
+from .core import WindowManager
+from .models import WindowInfo
+from .monitor import WindowMonitor
+from .utils import setup_logger
+
+__all__ = ["WindowManager", "WindowInfo", "WindowMonitor", "setup_logger"]

window_manager/core.py

@@ -0,0 +1,228 @@
+import logging
+import win32gui
+import win32process
+import win32con
+import psutil
+from typing import List, Optional, Tuple, Dict, Any
+from .models import WindowInfo
+from .utils import setup_logger
+
+logger = setup_logger()
+
+class WindowManagerError(Exception):
+    """Base exception for WindowManager errors."""
+    pass
+
+class WindowManager:
+    """
+    Core class for managing Windows windows.
+    """
+    
+    def __init__(self):
+        """Initializes the WindowManager."""
+        self._logger = logger
+    
+    def get_all_windows(self, visible_only: bool = True) -> List[WindowInfo]:
+        """
+        Retrieves all open windows.
+        
+        Args:
+            visible_only: If True, only returns visible windows.
+            
+        Returns:
+            A list of WindowInfo objects.
+        """
+        windows: List[WindowInfo] = []
+        
+        def enum_handler(hwnd, ctx):
+            if visible_only and not win32gui.IsWindowVisible(hwnd):
+                return
+            
+            try:
+                title = win32gui.GetWindowText(hwnd)
+                class_name = win32gui.GetClassName(hwnd)
+                
+                # Get process ID
+                _, pid = win32process.GetWindowThreadProcessId(hwnd)
+                
+                # Get process name
+                try:
+                    process = psutil.Process(pid)
+                    process_name = process.name()
+                except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                    process_name = "Unknown"
+                
+                # Get window rect
+                try:
+                    rect = win32gui.GetWindowRect(hwnd)
+                except Exception:
+                    rect = None
+                
+                window_info = WindowInfo(
+                    handle=hwnd,
+                    title=title,
+                    class_name=class_name,
+                    pid=pid,
+                    process_name=process_name,
+                    rect=rect,
+                    is_visible=win32gui.IsWindowVisible(hwnd)
+                )
+                windows.append(window_info)
+            except Exception as e:
+                self._logger.warning(f"Error processing window {hwnd}: {e}")
+            
+        try:
+            win32gui.EnumWindows(enum_handler, None)
+        except Exception as e:
+            self._logger.error(f"Failed to enumerate windows: {e}")
+            raise WindowManagerError(f"Failed to enumerate windows: {e}")
+            
+        return windows
+
+    def find_windows(self, title: Optional[str] = None, class_name: Optional[str] = None, process_name: Optional[str] = None, exact_match: bool = False) -> List[WindowInfo]:
+        """
+        Finds windows matching the given criteria.
+        
+        Args:
+            title: The window title to search for.
+            class_name: The window class name to search for.
+            exact_match: If True, requires exact string match. Otherwise, checks for containment.
+            
+        Returns:
+            A list of matching WindowInfo objects.
+        """
+        all_windows = self.get_all_windows(visible_only=False)
+        matched_windows = []
+        
+        for window in all_windows:
+            match = True
+            
+            if title:
+                if exact_match:
+                    if window.title != title:
+                        match = False
+                else:
+                    if title.lower() not in window.title.lower():
+                        match = False
+            
+            if match and class_name:
+                if exact_match:
+                    if window.class_name != class_name:
+                        match = False
+                else:
+                    if class_name.lower() not in window.class_name.lower():
+                        match = False
+            
+            if match and process_name:
+                if window.process_name is None or window.process_name.lower() != process_name.lower():
+                    match = False
+            
+            if match and (title or class_name or process_name):
+                matched_windows.append(window)
+                
+        return matched_windows
+
+    def get_window_by_handle(self, handle: int) -> Optional[WindowInfo]:
+        """
+        Retrieves window information by handle.
+        
+        Args:
+            handle: The window handle.
+            
+        Returns:
+            A WindowInfo object if found, otherwise None.
+        """
+        if not win32gui.IsWindow(handle):
+            return None
+            
+        try:
+            title = win32gui.GetWindowText(handle)
+            class_name = win32gui.GetClassName(handle)
+            _, pid = win32process.GetWindowThreadProcessId(handle)
+            
+            try:
+                process = psutil.Process(pid)
+                process_name = process.name()
+            except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                process_name = "Unknown"
+                
+            try:
+                rect = win32gui.GetWindowRect(handle)
+            except Exception:
+                rect = None
+
+            return WindowInfo(
+                handle=handle,
+                title=title,
+                class_name=class_name,
+                pid=pid,
+                process_name=process_name,
+                rect=rect,
+                is_visible=win32gui.IsWindowVisible(handle)
+            )
+        except Exception as e:
+            self._logger.error(f"Error getting window info for handle {handle}: {e}")
+            return None
+
+    def close_window(self, handle: int) -> bool:
+        """Closes the window with the given handle."""
+        try:
+            win32gui.PostMessage(handle, win32con.WM_CLOSE, 0, 0)
+            self._logger.info(f"Closed window {handle}")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to close window {handle}: {e}")
+            return False
+
+    def minimize_window(self, handle: int) -> bool:
+        """Minimizes the window."""
+        try:
+            win32gui.ShowWindow(handle, win32con.SW_MINIMIZE)
+            self._logger.info(f"Minimized window {handle}")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to minimize window {handle}: {e}")
+            return False
+
+    def maximize_window(self, handle: int) -> bool:
+        """Maximizes the window."""
+        try:
+            win32gui.ShowWindow(handle, win32con.SW_MAXIMIZE)
+            self._logger.info(f"Maximized window {handle}")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to maximize window {handle}: {e}")
+            return False
+
+    def restore_window(self, handle: int) -> bool:
+        """Restores the window."""
+        try:
+            win32gui.ShowWindow(handle, win32con.SW_RESTORE)
+            self._logger.info(f"Restored window {handle}")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to restore window {handle}: {e}")
+            return False
+            
+    def move_window(self, handle: int, x: int, y: int, width: int, height: int) -> bool:
+        """Moves and resizes the window."""
+        try:
+            win32gui.MoveWindow(handle, x, y, width, height, True)
+            self._logger.info(f"Moved window {handle} to ({x}, {y}, {width}, {height})")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to move window {handle}: {e}")
+            return False
+
+    def set_foreground(self, handle: int) -> bool:
+        """Brings the window to the foreground."""
+        try:
+            # Sometimes setting foreground requires specific conditions or tricks
+            # like attaching thread input if the foreground lock timeout is set.
+            # For simplicity, we just try SetForegroundWindow.
+            win32gui.SetForegroundWindow(handle)
+            self._logger.info(f"Set window {handle} to foreground")
+            return True
+        except Exception as e:
+            self._logger.error(f"Failed to set foreground window {handle}: {e}")
+            return False

window_manager/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class WindowInfo:
+    """
+    Represents information about a window.
+    """
+    handle: int
+    title: str
+    class_name: str
+    pid: int
+    process_name: Optional[str] = None
+    rect: Optional[tuple[int, int, int, int]] = None  # (left, top, right, bottom)
+    is_visible: bool = False
+    
+    def __str__(self):
+        return (f"Window(handle={self.handle}, title='{self.title}', "
+                f"class='{self.class_name}', pid={self.pid}, "
+                f"process='{self.process_name}')")

window_manager/monitor.py

@@ -0,0 +1,164 @@
+import ctypes
+from ctypes import wintypes
+import threading
+import time
+import win32con
+import win32api
+import win32gui
+from typing import Callable, Optional
+from .utils import setup_logger
+
+logger = setup_logger("WindowMonitor")
+
+# Constants for SetWinEventHook
+EVENT_MIN = 0x00000001
+EVENT_MAX = 0x7FFFFFFF
+EVENT_SYSTEM_FOREGROUND = 0x0003
+EVENT_OBJECT_CREATE = 0x8000
+EVENT_OBJECT_DESTROY = 0x8001
+EVENT_OBJECT_SHOW = 0x8002
+EVENT_OBJECT_HIDE = 0x8003
+EVENT_OBJECT_NAMECHANGE = 0x800C
+WINEVENT_OUTOFCONTEXT = 0x0000
+
+# Callback function type
+WinEventProcType = ctypes.WINFUNCTYPE(
+    None,
+    wintypes.HANDLE,
+    wintypes.DWORD,
+    wintypes.HWND,
+    wintypes.LONG,
+    wintypes.LONG,
+    wintypes.DWORD,
+    wintypes.DWORD
+)
+
+user32 = ctypes.windll.user32
+
+class WindowMonitor:
+    """
+    Monitors window events such as creation, destruction, and state changes.
+    """
+    
+    def __init__(self, callback: Optional[Callable[[str, int, int], None]] = None):
+        """
+        Initializes the WindowMonitor.
+        
+        Args:
+            callback: A function to call when an event occurs. 
+                      Signature: callback(event_name, hwnd, id_object)
+        """
+        self._callback = callback
+        self._hook = None
+        self._thread = None
+        self._stop_event = threading.Event()
+        self._logger = logger
+
+    def _event_handler(self, hWinEventHook, event, hwnd, idObject, idChild, dwEventThread, dwmsEventTime):
+        """
+        Internal callback for SetWinEventHook.
+        """
+        if idObject != 0: # OBJID_WINDOW = 0
+            return
+
+        event_name = "Unknown"
+        if event == EVENT_OBJECT_CREATE:
+            event_name = "Create"
+        elif event == EVENT_OBJECT_DESTROY:
+            event_name = "Destroy"
+        elif event == EVENT_OBJECT_SHOW:
+            event_name = "Show"
+        elif event == EVENT_OBJECT_HIDE:
+            event_name = "Hide"
+        elif event == EVENT_SYSTEM_FOREGROUND:
+            event_name = "Foreground"
+        elif event == EVENT_OBJECT_NAMECHANGE:
+            event_name = "NameChange"
+        
+        # Only log/callback for interesting events on actual windows
+        # Filter out some noise if necessary, but for now report all OBJID_WINDOW
+        
+        # We can try to get window title here, but be careful as the window might be destroying
+        title = ""
+        try:
+            if event != EVENT_OBJECT_DESTROY:
+                 # win32gui.GetWindowText might fail if window is gone
+                 length = user32.GetWindowTextLengthW(hwnd)
+                 buff = ctypes.create_unicode_buffer(length + 1)
+                 user32.GetWindowTextW(hwnd, buff, length + 1)
+                 title = buff.value
+        except Exception:
+            pass
+
+        log_msg = f"Event: {event_name}, HWND: {hwnd}, Title: {title}"
+        self._logger.info(log_msg)
+        
+        if self._callback:
+            try:
+                self._callback(event_name, hwnd, title)
+            except Exception as e:
+                self._logger.error(f"Error in user callback: {e}")
+
+    def _run(self):
+        """
+        The thread function that runs the message loop.
+        """
+        self._logger.info("Starting monitor thread...")
+        
+        # Keep reference to the callback to prevent garbage collection
+        self._c_callback = WinEventProcType(self._event_handler)
+        
+        # Set hook
+        self._hook = user32.SetWinEventHook(
+            EVENT_MIN,
+            EVENT_MAX,
+            0,
+            self._c_callback,
+            0,
+            0,
+            WINEVENT_OUTOFCONTEXT
+        )
+        
+        if not self._hook:
+            self._logger.error("Failed to set win event hook")
+            return
+            
+        # Message loop
+        msg = wintypes.MSG()
+        while not self._stop_event.is_set():
+            # PeekMessage is non-blocking, so we can check stop_event
+            # But SetWinEventHook needs a message pump.
+            # GetMessage blocks.
+            # We can use MsgWaitForMultipleObjects or just PeekMessage with a sleep.
+            
+            if user32.PeekMessageW(ctypes.byref(msg), 0, 0, 0, 1): # PM_REMOVE = 1
+                if msg.message == win32con.WM_QUIT:
+                    break
+                user32.TranslateMessage(ctypes.byref(msg))
+                user32.DispatchMessageW(ctypes.byref(msg))
+            else:
+                time.sleep(0.01) # Small sleep to avoid CPU spin
+        
+        # Unhook
+        user32.UnhookWinEvent(self._hook)
+        self._logger.info("Monitor thread stopped.")
+
+    def start(self):
+        """Starts the monitoring thread."""
+        if self._thread and self._thread.is_alive():
+            self._logger.warning("Monitor already running")
+            return
+
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        """Stops the monitoring thread."""
+        if not self._thread or not self._thread.is_alive():
+            return
+            
+        self._stop_event.set()
+        self._thread.join(timeout=2)
+        if self._thread.is_alive():
+            self._logger.warning("Monitor thread did not stop gracefully")

window_manager/utils.py

@@ -0,0 +1,38 @@
+import logging
+import sys
+from typing import Optional
+
+def setup_logger(name: str = "WindowManager", level: int = logging.INFO, log_file: Optional[str] = None) -> logging.Logger:
+    """
+    Sets up a logger with the specified name, level, and optional file output.
+    
+    Args:
+        name: The name of the logger.
+        level: The logging level.
+        log_file: Optional path to a log file.
+        
+    Returns:
+        A configured logging.Logger instance.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    
+    if logger.hasHandlers():
+        return logger
+        
+    formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+    
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+    
+    # File handler
+    if log_file:
+        file_handler = logging.FileHandler(log_file, encoding='utf-8')
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+        
+    return logger