Utilities and Configuration

def size():
    """
    Get screen size as (width, height) tuple.
    
    Returns:
    Tuple[int, int]: Screen dimensions in pixels (width, height)
    
    Example:
    width, height = pyautogui.size()
    print(f"Screen resolution: {width}x{height}")
    """

def resolution():
    """Alias for size() - get screen resolution as (width, height) tuple."""

def position():
    """
    Get current mouse position as (x, y) tuple.
    
    Returns:
    Tuple[int, int]: Current mouse coordinates (x, y)
    """

def onScreen(x, y=None):
    """
    Check if coordinates are within screen bounds.
    
    Parameters:
    - x (int or tuple): X coordinate, or (x, y) tuple if y is None
    - y (int, optional): Y coordinate
    
    Returns:
    bool: True if coordinates are within screen bounds, False otherwise
    
    Examples:
    pyautogui.onScreen(100, 200)     # Check specific coordinates
    pyautogui.onScreen((100, 200))   # Check coordinate tuple
    """

def sleep(seconds):
    """
    Sleep for specified number of seconds.
    
    Parameters:
    - seconds (float): Time to sleep in seconds
    
    Returns:
    None
    
    Note: This is equivalent to time.sleep() but provided for convenience.
    """

def countdown(seconds):
    """
    Display countdown with printed numbers.
    
    Parameters:
    - seconds (int): Number of seconds to count down from
    
    Returns:
    None
    
    Example:
    pyautogui.countdown(5)  # Prints: 5... 4... 3... 2... 1...
    """

def failSafeCheck():
    """
    Check if mouse is in failsafe position and raise exception if so.
    
    Returns:
    None
    
    Raises:
    FailSafeException: If mouse is in a failsafe corner position and FAILSAFE is True
    
    Note: This function is called automatically by PyAutoGUI functions when FAILSAFE is enabled.
    """

def useImageNotFoundException(value=None):
    """
    Configure whether image location functions raise exceptions when image not found.
    
    Parameters:
    - value (bool, optional): True to raise exceptions, False to return None.
                             If None, returns current setting without changing it.
    
    Returns:
    bool: Current setting (if value is None)
    None: (if value is provided)
    
    When True: locateOnScreen() and similar functions raise ImageNotFoundException
    When False: locateOnScreen() and similar functions return None
    """

def getInfo():
    """
    Get system and PyAutoGUI version information.
    
    Returns:
    Tuple: (platform, python_version, pyautogui_version, pyscreeze_version, 
           pymsgbox_version, pytweening_version, pygetwindow_version)
    
    Example:
    info = pyautogui.getInfo()
    print(f"PyAutoGUI version: {info[2]}")
    """

def printInfo(dontPrint=False):
    """
    Print system and PyAutoGUI version information.
    
    Parameters:
    - dontPrint (bool): If True, return info string instead of printing (default: False)
    
    Returns:
    str: Information string (if dontPrint is True)
    None: (if dontPrint is False, prints to console)
    """

def displayMousePosition(xOffset=0, yOffset=0):
    """
    Continuously display current mouse position and pixel color.
    
    Parameters:
    - xOffset (int): X offset to add to displayed coordinates (default: 0)
    - yOffset (int): Y offset to add to displayed coordinates (default: 0)
    
    Returns:
    None
    
    Note: Runs continuously until interrupted (Ctrl+C). Displays live mouse 
    coordinates and RGB values of pixel under cursor.
    
    Example:
    pyautogui.displayMousePosition()  # Press Ctrl+C to stop
    """

def mouseInfo():
    """
    Launch MouseInfo application for advanced coordinate debugging.
    
    Returns:
    None
    
    Note: Opens separate MouseInfo GUI application with enhanced features
    for coordinate tracking and color analysis. Requires mouseinfo package.
    """

def getPointOnLine(x1, y1, x2, y2, n):
    """
    Get point along line between two points at progress n.
    
    Parameters:
    - x1, y1 (int): Starting point coordinates
    - x2, y2 (int): Ending point coordinates  
    - n (float): Progress along line (0.0 = start, 1.0 = end)
    
    Returns:
    Tuple[float, float]: Coordinates (x, y) at position n along the line
    
    Example:
    # Get midpoint between (0, 0) and (100, 100)
    midpoint = pyautogui.getPointOnLine(0, 0, 100, 100, 0.5)
    # Returns (50.0, 50.0)
    """

def run(commandStr, _ssCount=None):
    """
    Execute PyAutoGUI operations using command string mini-language.
    
    Parameters:
    - commandStr (str): Command string with PyAutoGUI operations
    - _ssCount (int, optional): Internal screenshot counter
    
    Returns:
    None
    
    Command syntax includes:
    - click(x, y) - Click at coordinates
    - move(x, y) - Move mouse to coordinates  
    - type(text) - Type text
    - key(keyname) - Press key
    - sleep(seconds) - Sleep for duration
    
    Example:
    pyautogui.run('click(100, 200); type("Hello"); key(enter)')
    """

def linear(n):
    """
    Linear interpolation - constant speed movement.
    
    Parameters:
    - n (float): Progress value 0.0 to 1.0
    
    Returns:
    float: Interpolated value 0.0 to 1.0
    """

def easeInQuad(n):
    """Quadratic ease-in - slow start, accelerating."""

def easeOutQuad(n):
    """Quadratic ease-out - fast start, decelerating."""

def easeInOutQuad(n):
    """Quadratic ease-in-out - slow start and end, fast middle."""

def easeInCubic(n):
    """Cubic ease-in - very slow start, strong acceleration."""

def easeOutCubic(n):
    """Cubic ease-out - fast start, strong deceleration."""

def easeInOutCubic(n):
    """Cubic ease-in-out - slow start and end, very fast middle."""

def easeInQuart(n):
    """Quartic ease-in - extremely slow start."""

def easeOutQuart(n):
    """Quartic ease-out - extremely slow end."""

def easeInOutQuart(n):
    """Quartic ease-in-out - extremely slow start and end."""

def easeInQuint(n):
    """Quintic ease-in - very gradual acceleration."""

def easeOutQuint(n):
    """Quintic ease-out - very gradual deceleration."""

def easeInOutQuint(n):
    """Quintic ease-in-out - very smooth curve."""

def easeInSine(n):
    """Sine ease-in - smooth, gentle acceleration."""

def easeOutSine(n):
    """Sine ease-out - smooth, gentle deceleration."""

def easeInOutSine(n):
    """Sine ease-in-out - very smooth S-curve."""

def easeInExpo(n):
    """Exponential ease-in - very slow start, rapid acceleration."""

def easeOutExpo(n):
    """Exponential ease-out - rapid start, very slow end."""

def easeInOutExpo(n):
    """Exponential ease-in-out - very slow start and end."""

def easeInCirc(n):
    """Circular ease-in - curved acceleration."""

def easeOutCirc(n):
    """Circular ease-out - curved deceleration."""

def easeInOutCirc(n):
    """Circular ease-in-out - smooth circular curve."""

def easeInElastic(n):
    """Elastic ease-in - bouncy acceleration effect."""

def easeOutElastic(n):
    """Elastic ease-out - bouncy deceleration effect."""

def easeInOutElastic(n):
    """Elastic ease-in-out - bouncy at both ends."""

def easeInBack(n):
    """Back ease-in - slight reverse before forward motion."""

def easeOutBack(n):
    """Back ease-out - slight overshoot before settling."""

def easeInOutBack(n):
    """Back ease-in-out - reverse at start, overshoot at end."""

def easeInBounce(n):
    """Bounce ease-in - bouncing acceleration effect."""

def easeOutBounce(n):
    """Bounce ease-out - bouncing deceleration effect."""

def easeInOutBounce(n):
    """Bounce ease-in-out - bouncing at both ends."""

# Timing and safety configuration
PAUSE: float = 0.1                    # Global pause between function calls (seconds)
FAILSAFE: bool = True                 # Enable failsafe mechanism (move mouse to corner to abort)
MINIMUM_DURATION: float = 0.1         # Minimum duration for mouse movements (seconds)
MINIMUM_SLEEP: float = 0.05          # Minimum sleep time (seconds)
DARWIN_CATCH_UP_TIME: float = 0.01   # macOS interface catch-up time (seconds)

# Screenshot logging for debugging
LOG_SCREENSHOTS: bool = False         # Enable screenshot logging
LOG_SCREENSHOTS_LIMIT: int = 10       # Maximum number of logged screenshots

# Failsafe trigger coordinates
FAILSAFE_POINTS: List[Tuple[int, int]] # Screen corner coordinates that trigger failsafe

import pyautogui
import time

# Basic screen information
screen_width, screen_height = pyautogui.size()
print(f"Screen size: {screen_width}x{screen_height}")

mouse_x, mouse_y = pyautogui.position()
print(f"Mouse position: ({mouse_x}, {mouse_y})")

# Check if coordinates are valid
if pyautogui.onScreen(100, 200):
    print("Coordinates (100, 200) are on screen")

# Timing and delays
print("Starting in 3 seconds...")
pyautogui.countdown(3)  # Visual countdown

pyautogui.sleep(1.5)    # Sleep for 1.5 seconds

# System information
info = pyautogui.getInfo()
print(f"Platform: {info[0]}")
print(f"PyAutoGUI version: {info[2]}")

# Print all system info
pyautogui.printInfo()

# Smooth movement with easing
pyautogui.moveTo(400, 300, duration=2.0, tween=pyautogui.easeInOutQuad)
pyautogui.moveTo(600, 500, duration=1.5, tween=pyautogui.easeOutBounce)

# Debug mouse position (run in separate script)
# pyautogui.displayMousePosition()  # Press Ctrl+C to stop

# Failsafe configuration
original_failsafe = pyautogui.FAILSAFE
pyautogui.FAILSAFE = False    # Disable failsafe temporarily
# ... perform operations that might trigger failsafe ...
pyautogui.FAILSAFE = original_failsafe  # Restore setting

# Image exception configuration
pyautogui.useImageNotFoundException(True)  # Raise exceptions
try:
    location = pyautogui.locateOnScreen('missing.png')
except pyautogui.ImageNotFoundException:
    print("Image not found - exception raised")

pyautogui.useImageNotFoundException(False)  # Return None instead
location = pyautogui.locateOnScreen('missing.png')
if location is None:
    print("Image not found - None returned")

# Mathematical utilities
start_point = (100, 100)
end_point = (300, 400)

# Get points along the line for smooth animation
for i in range(11):  # 11 points (0.0 to 1.0 in steps of 0.1)
    progress = i / 10.0
    x, y = pyautogui.getPointOnLine(start_point[0], start_point[1], 
                                  end_point[0], end_point[1], progress)
    print(f"Point at {progress*100}%: ({x}, {y})")

# Command string interface
pyautogui.run('''
    click(100, 200);
    sleep(0.5);
    type("Hello World");
    key(enter);
    move(300, 400)
''')

# Configuration management
def setup_pyautogui_config():
    """Configure PyAutoGUI for specific automation task"""
    # Save original settings
    original_pause = pyautogui.PAUSE
    original_failsafe = pyautogui.FAILSAFE
    
    # Apply task-specific settings
    pyautogui.PAUSE = 0.5           # Slower for stability
    pyautogui.FAILSAFE = True       # Keep safety enabled
    pyautogui.LOG_SCREENSHOTS = True  # Enable debugging
    
    return original_pause, original_failsafe

def restore_pyautogui_config(original_pause, original_failsafe):
    """Restore original PyAutoGUI configuration"""
    pyautogui.PAUSE = original_pause
    pyautogui.FAILSAFE = original_failsafe
    pyautogui.LOG_SCREENSHOTS = False

# Usage
saved_config = setup_pyautogui_config()
try:
    # Perform automation tasks with custom configuration
    pyautogui.click(100, 100)
    pyautogui.typewrite("Configured automation")
finally:
    # Always restore original configuration
    restore_pyautogui_config(*saved_config)

# Advanced debugging workflow
def debug_automation_script():
    """Debug automation script with position tracking"""
    print("Position debugging mode - move mouse to desired locations")
    print("Press Ctrl+C when done")
    
    positions = []
    try:
        while True:
            x, y = pyautogui.position()
            pixel_color = pyautogui.pixel(x, y)
            
            print(f"\rMouse: ({x:4}, {y:4}) | RGB: {pixel_color} | "
                  f"On screen: {pyautogui.onScreen(x, y)}", end='')
            
            time.sleep(0.1)
            
    except KeyboardInterrupt:
        print("\nDebug session ended")
        return positions

# Performance testing with different easing functions
def test_easing_performance():
    """Test different easing functions for movement performance"""
    easing_functions = [
        ('linear', pyautogui.linear),
        ('easeInQuad', pyautogui.easeInQuad),
        ('easeOutQuad', pyautogui.easeOutQuad),
        ('easeInOutQuad', pyautogui.easeInOutQuad),
        ('easeInBounce', pyautogui.easeInBounce),
        ('easeOutBounce', pyautogui.easeOutBounce)
    ]
    
    start_pos = (100, 100)
    end_pos = (500, 400)
    duration = 1.0
    
    for name, func in easing_functions:
        print(f"Testing {name} easing...")
        start_time = time.time()
        pyautogui.moveTo(start_pos[0], start_pos[1])
        pyautogui.moveTo(end_pos[0], end_pos[1], duration=duration, tween=func)
        elapsed = time.time() - start_time
        print(f"  Completed in {elapsed:.2f} seconds")
        time.sleep(0.5)  # Brief pause between tests

# Run performance test
# test_easing_performance()