Metadata-Version: 2.4
Name: advanced_automation_utilities
Version: 1.0.0
Summary: Personal use automation utilities library.
Author-email: Guido Iván Gross <grossguidoivan@gmail.com>
License: MIT License
        
        Copyright (c) 2.026 Guido Iván Gross
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Keywords: automation,utilities,windows,mouse,keyboard,screen,timing,sound,system,macro,bot,rpa
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: mss>=6.1.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: opencv-python>=4.5.5
Requires-Dist: psutil>=5.8.0
Requires-Dist: PyGetWindow>=0.0.9
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: winrt-Windows.Foundation>=3.0
Requires-Dist: winrt-Windows.Foundation.Collections>=3.0
Requires-Dist: winrt-Windows.Graphics.Imaging>=3.0
Requires-Dist: winrt-Windows.Media.Ocr>=3.0
Requires-Dist: winrt-Windows.Storage.Streams>=3.0
Dynamic: license-file

# **Advanced Automation Utilities**

Personal use automation utilities library. A powerful, native Python library for Windows automation, featuring Context Manager-based async chaining and zero dependence on heavy GUI automation libraries. It leverages native `ctypes` hooks for maximum speed, security, and lower overhead.

---

## **Purpose**

**This library is designed for scripts and applications that need:**

- Reliable, human-like mouse movements natively in Windows.
- Low-level keyboard hooks and precise inputs.
- Fast and accurate screen vision (OCR and image matching).
- Asynchronous execution and method chaining.
- Reliable timing, sound, and system-level operations.

---

## **Requirements**

### **Dependencies**

**Standard library modules are used where possible; only external dependencies are listed:**

- `mss` (6.1.0 or higher)
- `numpy` (1.21.0 or higher)
- `opencv-python` (4.5.5 or higher)
- `psutil` (5.8.0 or higher)
- `PyGetWindow` (0.0.9 or higher)
- `pyperclip` (1.8.2 or higher)
- `winrt-Windows.Foundation` (3.0 or higher)
- `winrt-Windows.Foundation.Collections` (3.0 or higher)
- `winrt-Windows.Graphics.Imaging` (3.0 or higher)
- `winrt-Windows.Media.Ocr` (3.0 or higher)
- `winrt-Windows.Storage.Streams` (3.0 or higher)

### **Python version**

Python (3.10 or higher)

### **Operating System**

**Any of the following:**

- Windows (10 or higher)
- Linux (Any modern distribution capable of running Python 3.10)
- MacOS (10.15 or higher)

> [!WARNING]
> **Linux and MacOS Limitations:** This library is heavily optimized and written for Windows. On Linux and MacOS, **Keyboard, Mouse, Sound, OCR features, Window Management, and Power options** are completely unsupported because they rely on native Windows APIs (`ctypes.windll`, `winrt`, `winsound`, etcetera). Only Timing, Screen (image search and pixel color), and Clipboard functionalities will work natively on these systems.

---

## **Features**

### **Physics (Human Simulation)**

Both **Mouse** and **Keyboard** actions are governed by highly configurable dataclasses (`MousePhysics` and `KeyboardPhysics`) designed to mimic human behavior perfectly. 

You can pass a custom physics object to their respective facades to alter their simulation parameters:
```python
from advanced_automation_utilities.mouse import MousePhysics, Mouse
from advanced_automation_utilities.keyboard import KeyboardPhysics, Keyboard

# Configure human-like Bézier curve mouse movements
mouse_physics = MousePhysics(
    speed = 1500,
    minimum_speed = 0,
    maximum_speed = 0,
    speed_variation = 0.1,
    duration = 0,
    duration_variation = 0,
    base_duration = 0.1,
    base_duration_variation = 0.1,
    inconsistency = 0.25,
    target_radius = 25,
    readjustment_duration_ratio = 0.25,
    click_delay = 0.05,
    click_delay_variation = 0.1,
    click_duration = 0.05,
    click_duration_variation = 0.1,
    scroll_speed = 1000,
    scroll_speed_variation = 0.1,
    scroll_duration = 0,
    scroll_duration_variation = 0,
    scroll_step = 120,
    scroll_pause_variation = 0.1
)
mouse = Mouse(mouse_physics)

# Configure advanced typing simulation with errors and delayed realizations
keyboard_physics = KeyboardPhysics(
    press_delay = 0.15,
    press_delay_variation = 0.5,
    press_duration = 0.05,
    press_duration_variation = 0.1,
    hotkey_delay = 0.01,
    hotkey_delay_variation = 0.5,
    typing_error_chance = 0.025,
    typing_error_correction_delay = 0.25,
    typing_error_correction_delay_variation = 0.5,
    typing_error_delayed_realization_chance = 0.5,
    auto_repeat = True
)
keyboard = Keyboard(keyboard_physics)
```

### **Mouse Utilities (mouse)**

**Native pointer manipulation with Bézier-curve physics for human-like behavior:**

- **MouseInfo().coordinates:** Gets the current (X, Y) coordinates of the pointer.
  ```python
  x, y = MouseInfo().coordinates
  ```
- **MouseInfo().x:** Gets the current X coordinate of the pointer.
  ```python
  x = MouseInfo().x
  ```
- **MouseInfo().y:** Gets the current Y coordinate of the pointer.
  ```python
  y = MouseInfo().y
  ```
- **MouseInfo().pixel_color():** Gets the RGB color of the pixel currently under the pointer.
  ```python
  r, g, b = MouseInfo().pixel_color()
  ```
- **MouseInfo().on_screen:** Checks if the pointer is currently within the bounds of any screen.
  ```python
  is_visible = MouseInfo().on_screen
  ```
- **move():** Moves the pointer to the specified coordinates smoothly based on the configured physics.
  ```python
  Mouse().move(x = 250, y = 500)
  ```
- **click():** Clicks the mouse at its current position or at specified coordinates.
  ```python
  Mouse().click()
  Mouse().click(x = 100, y = 200) # Moves before clicking
  ```
- **double_click():** Performs a double click.
  ```python
  Mouse().double_click()
  ```
- **right_click():** Performs a right click.
  ```python
  Mouse().right_click()
  ```
- **middle_click():** Performs a middle click.
  ```python
  Mouse().middle_click()
  ```
- **hold_click():** Holds down a mouse button.
  ```python
  Mouse().hold_click()
  ```
- **release_click():** Releases a previously held mouse button.
  ```python
  Mouse().release_click()
  ```
- **drag_and_drop():** Drags an item from start to end coordinates smoothly.
  ```python
  Mouse().drag_and_drop(start_x = 100, start_y = 100, end_x = 500, end_y = 500)
  ```
- **scroll():** Scrolls the mouse wheel by the specified amount.
  ```python
  Mouse().scroll(amount = -1000)
  ```

### **Keyboard Utilities (keyboard)**

**Low-level keyboard interaction and information retrieval:**

- **KeyboardInfo().is_pressed():** Returns True if the specified key is currently physically pressed down.
  ```python
  is_shift_down = KeyboardInfo().is_pressed("shift")
  ```
- **press_key():** Presses and immediately releases a single key.
  ```python
  Keyboard().press_key("a")
  ```
- **hold_key():** Presses a key and holds it down.
  ```python
  Keyboard().hold_key("shift")
  ```
- **release_key():** Releases a previously held key.
  ```python
  Keyboard().release_key("shift")
  ```
- **hotkey():** Holds down a combination of keys and releases them in reverse order.
  ```python
  Keyboard().hotkey("ctrl", "c")
  ```
- **block_key():** Blocks all physical input from a specific key.
  ```python
  Keyboard().block_key("esc")
  ```
- **unblock_key():** Unblocks a previously blocked key.
  ```python
  Keyboard().unblock_key("esc")
  ```
- **write():** Types a string character by character with advanced, human-like typing error simulations, delays, and physics.
  ```python
  Keyboard().write("Hello, world!")
  ```

### **Screen Utilities (screen)**

**Advanced computer vision leveraging OpenCV and Windows OCR:**

- **ScreenInfo().resolution:** Gets the (width, height) resolution of the primary screen.
  ```python
  width, height = ScreenInfo().resolution
  ```
- **ScreenInfo().width:** Gets the width of the primary screen.
  ```python
  width = ScreenInfo().width
  ```
- **ScreenInfo().height:** Gets the height of the primary screen.
  ```python
  height = ScreenInfo().height
  ```
- **ScreenInfo().pixel_color():** Gets the RGB color of a specific pixel coordinate.
  ```python
  r, g, b = ScreenInfo().pixel_color(250, 500)
  ```
- **locate_image():** Searches for a template image on the screen and returns its central coordinates. Supports multi-monitor setups.
  ```python
  x, y = Screen().locate_image("button.png", monitor_index = 0)
  ```
- **locate_text():** Uses OCR to find specific text on the screen and returns its central coordinates. Supports multi-monitor setups.
  ```python
  x, y = Screen().locate_text("Submit", monitor_index = 0)
  ```
- **read_text():** Uses OCR to extract all readable text from the screen or a specific region. Supports multi-monitor setups.
  ```python
  text = Screen().read_text(monitor_index = 0)
  ```

### **Timing Utilities (timing)**

**Delays, chronometers, and condition-based execution flow:**

- **wait():** Pauses execution for an exact amount of seconds.
  ```python
  Timing().wait(2.5)
  ```
- **wait_random():** Pauses execution for a random duration between two limits.
  ```python
  Timing().wait_random(min_seconds = 1.0, max_seconds = 3.0)
  ```
- **wait_until():** Halts execution until a given function or lambda condition evaluates to True.
  ```python
  # Waits until the shift key is pressed
  Timing().wait_until(lambda: KeyboardInfo().is_pressed("shift"))
  ```
- **start_stop_timer():** Standard chronometer to keep track of elapsed time across code segments.
  ```python
  start = start_stop_timer()
  # ... perform actions ...
  end = start_stop_timer()
  elapsed_time = end - start
  ```
- **measure_time():** A decorator to automatically measure and print the execution time of any function.
  ```python
  @measure_time
  def heavy_task(): pass
  ```

### **Sound Utilities (sound)**

**Audio playback and text-to-speech features:**

- **play_beep_sound():** Plays a motherboard beep with a specific frequency and duration.
  ```python
  Sound().play_beep_sound(frequency = 1000, duration = 0.5)
  ```
- **play_audio():** Plays an audio file from the file system.
  ```python
  Sound().play_audio("alert.wav")
  ```
- **play_system_sound():** Plays a default Windows system sound.
  ```python
  Sound().play_system_sound("warning")
  ```
- **speak():** Synthesizes text to speech using the default Windows voice.
  ```python
  Sound().speak("Hello, world!")
  ```

### **System Utilities (system)**

**High-level operating system actions and process management:**

- **SystemInfo().clipboard_text:** Gets the current text content of the Windows clipboard.
  ```python
  text = SystemInfo().clipboard_text
  ```
- **SystemInfo().active_window_title:** Gets the title of the currently focused/active window.
  ```python
  title = SystemInfo().active_window_title
  ```
- **SystemInfo().is_process_running():** Checks if a specific process is currently running.
  ```python
  is_running = SystemInfo().is_process_running("notepad.exe")
  ```
- **set_clipboard_text():** Sets the text content of the Windows clipboard.
  ```python
  System().set_clipboard_text("Text to paste later")
  ```
- **open_process():** Opens a process or file with optional arguments.
  ```python
  System().open_process("notepad.exe")
  ```
- **kill_process():** Terminates an active process by its name.
  ```python
  System().kill_process("notepad.exe", force = True)
  ```
- **focus_window():** Brings a specific window to the foreground by its title.
  ```python
  System().focus_window("Untitled - Notepad")
  ```
- **resize_window():** Resizes a specific window to the specified dimensions by its title.
  ```python
  System().resize_window("Untitled - Notepad", width = 800, height = 600)
  ```
- **move_window():** Moves a specific window to the specified coordinates by its title.
  ```python
  System().move_window("Untitled - Notepad", x = 100, y = 100)
  ```
- **close_window():** Gently closes a specific window by its title.
  ```python
  System().close_window("Untitled - Notepad")
  ```
- **enable_kill_switch():** Enables a global kill switch (Ctrl + Shift + Alt + K by default) to abort execution instantly.
  ```python
  System().enable_kill_switch()
  ```
- **disable_kill_switch():** Disables the global kill switch.
  ```python
  System().disable_kill_switch()
  ```
- **lock():** Locks the Windows session (Win+L).
  ```python
  System().lock()
  ```
- **sign_out():** Signs out the current Windows user.
  ```python
  System().sign_out()
  ```
- **sleep():** Puts the computer into sleep mode.
  ```python
  System().sleep()
  ```
- **hibernate():** Puts the computer into hibernation mode.
  ```python
  System().hibernate()
  ```
- **shutdown():** Turns off the computer.
  ```python
  System().shutdown()
  ```
- **restart():** Restarts the computer.
  ```python
  System().restart()
  ```

---

## **Installation**

```bash
pip install advanced_automation_utilities
```

---

## **Update**

```bash
pip install -U advanced_automation_utilities
```
