0
# Utilities and Configuration
1

2
Helper functions for debugging, system information, timing controls, and animation easing functions. These utilities provide essential support functionality for PyAutoGUI operations including configuration management, debugging tools, and smooth animation capabilities.
3

4
## Capabilities
5

6
### Screen and Position Utilities
7

8
Basic screen dimension and position information functions.
9

10
```python { .api }
11
def size():
12
    """
13
    Get screen size as (width, height) tuple.
14
    
15
    Returns:
16
    Tuple[int, int]: Screen dimensions in pixels (width, height)
17
    
18
    Example:
19
    width, height = pyautogui.size()
20
    print(f"Screen resolution: {width}x{height}")
21
    """
22

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

26
def position():
27
    """
28
    Get current mouse position as (x, y) tuple.
29
    
30
    Returns:
31
    Tuple[int, int]: Current mouse coordinates (x, y)
32
    """
33

34
def onScreen(x, y=None):
35
    """
36
    Check if coordinates are within screen bounds.
37
    
38
    Parameters:
39
    - x (int or tuple): X coordinate, or (x, y) tuple if y is None
40
    - y (int, optional): Y coordinate
41
    
42
    Returns:
43
    bool: True if coordinates are within screen bounds, False otherwise
44
    
45
    Examples:
46
    pyautogui.onScreen(100, 200)     # Check specific coordinates
47
    pyautogui.onScreen((100, 200))   # Check coordinate tuple
48
    """
49
```
50

51
### Timing and Sleep Functions
52

53
Control timing and add delays between operations.
54

55
```python { .api }
56
def sleep(seconds):
57
    """
58
    Sleep for specified number of seconds.
59
    
60
    Parameters:
61
    - seconds (float): Time to sleep in seconds
62
    
63
    Returns:
64
    None
65
    
66
    Note: This is equivalent to time.sleep() but provided for convenience.
67
    """
68

69
def countdown(seconds):
70
    """
71
    Display countdown with printed numbers.
72
    
73
    Parameters:
74
    - seconds (int): Number of seconds to count down from
75
    
76
    Returns:
77
    None
78
    
79
    Example:
80
    pyautogui.countdown(5)  # Prints: 5... 4... 3... 2... 1...
81
    """
82
```
83

84
### Failsafe and Safety Functions
85

86
Functions for managing PyAutoGUI's safety mechanisms and error handling.
87

88
```python { .api }
89
def failSafeCheck():
90
    """
91
    Check if mouse is in failsafe position and raise exception if so.
92
    
93
    Returns:
94
    None
95
    
96
    Raises:
97
    FailSafeException: If mouse is in a failsafe corner position and FAILSAFE is True
98
    
99
    Note: This function is called automatically by PyAutoGUI functions when FAILSAFE is enabled.
100
    """
101

102
def useImageNotFoundException(value=None):
103
    """
104
    Configure whether image location functions raise exceptions when image not found.
105
    
106
    Parameters:
107
    - value (bool, optional): True to raise exceptions, False to return None.
108
                             If None, returns current setting without changing it.
109
    
110
    Returns:
111
    bool: Current setting (if value is None)
112
    None: (if value is provided)
113
    
114
    When True: locateOnScreen() and similar functions raise ImageNotFoundException
115
    When False: locateOnScreen() and similar functions return None
116
    """
117
```
118

119
### System Information
120

121
Get information about the current system and PyAutoGUI configuration.
122

123
```python { .api }
124
def getInfo():
125
    """
126
    Get system and PyAutoGUI version information.
127
    
128
    Returns:
129
    Tuple: (platform, python_version, pyautogui_version, pyscreeze_version, 
130
           pymsgbox_version, pytweening_version, pygetwindow_version)
131
    
132
    Example:
133
    info = pyautogui.getInfo()
134
    print(f"PyAutoGUI version: {info[2]}")
135
    """
136

137
def printInfo(dontPrint=False):
138
    """
139
    Print system and PyAutoGUI version information.
140
    
141
    Parameters:
142
    - dontPrint (bool): If True, return info string instead of printing (default: False)
143
    
144
    Returns:
145
    str: Information string (if dontPrint is True)
146
    None: (if dontPrint is False, prints to console)
147
    """
148
```
149

150
### Debug and Development Tools
151

152
Tools for debugging mouse positions and developing automation scripts.
153

154
```python { .api }
155
def displayMousePosition(xOffset=0, yOffset=0):
156
    """
157
    Continuously display current mouse position and pixel color.
158
    
159
    Parameters:
160
    - xOffset (int): X offset to add to displayed coordinates (default: 0)
161
    - yOffset (int): Y offset to add to displayed coordinates (default: 0)
162
    
163
    Returns:
164
    None
165
    
166
    Note: Runs continuously until interrupted (Ctrl+C). Displays live mouse 
167
    coordinates and RGB values of pixel under cursor.
168
    
169
    Example:
170
    pyautogui.displayMousePosition()  # Press Ctrl+C to stop
171
    """
172

173
def mouseInfo():
174
    """
175
    Launch MouseInfo application for advanced coordinate debugging.
176
    
177
    Returns:
178
    None
179
    
180
    Note: Opens separate MouseInfo GUI application with enhanced features
181
    for coordinate tracking and color analysis. Requires mouseinfo package.
182
    """
183
```
184

185
### Mathematical Utilities
186

187
Utility functions for coordinate calculations and geometry.
188

189
```python { .api }
190
def getPointOnLine(x1, y1, x2, y2, n):
191
    """
192
    Get point along line between two points at progress n.
193
    
194
    Parameters:
195
    - x1, y1 (int): Starting point coordinates
196
    - x2, y2 (int): Ending point coordinates  
197
    - n (float): Progress along line (0.0 = start, 1.0 = end)
198
    
199
    Returns:
200
    Tuple[float, float]: Coordinates (x, y) at position n along the line
201
    
202
    Example:
203
    # Get midpoint between (0, 0) and (100, 100)
204
    midpoint = pyautogui.getPointOnLine(0, 0, 100, 100, 0.5)
205
    # Returns (50.0, 50.0)
206
    """
207
```
208

209
### Command String Interface
210

211
Execute PyAutoGUI operations using a mini-language command string format.
212

213
```python { .api }
214
def run(commandStr, _ssCount=None):
215
    """
216
    Execute PyAutoGUI operations using command string mini-language.
217
    
218
    Parameters:
219
    - commandStr (str): Command string with PyAutoGUI operations
220
    - _ssCount (int, optional): Internal screenshot counter
221
    
222
    Returns:
223
    None
224
    
225
    Command syntax includes:
226
    - click(x, y) - Click at coordinates
227
    - move(x, y) - Move mouse to coordinates  
228
    - type(text) - Type text
229
    - key(keyname) - Press key
230
    - sleep(seconds) - Sleep for duration
231
    
232
    Example:
233
    pyautogui.run('click(100, 200); type("Hello"); key(enter)')
234
    """
235
```
236

237
## Tweening and Easing Functions
238

239
PyAutoGUI includes comprehensive easing functions from PyTweening for smooth animations. All movement functions (moveTo, dragTo, etc.) accept a `tween` parameter.
240

241
### Linear Function
242
```python { .api }
243
def linear(n):
244
    """
245
    Linear interpolation - constant speed movement.
246
    
247
    Parameters:
248
    - n (float): Progress value 0.0 to 1.0
249
    
250
    Returns:
251
    float: Interpolated value 0.0 to 1.0
252
    """
253
```
254

255
### Quadratic Easing
256
```python { .api }
257
def easeInQuad(n):
258
    """Quadratic ease-in - slow start, accelerating."""
259

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

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

267
### Cubic Easing
268
```python { .api }
269
def easeInCubic(n):
270
    """Cubic ease-in - very slow start, strong acceleration."""
271

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

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

279
### Quartic Easing
280
```python { .api }
281
def easeInQuart(n):
282
    """Quartic ease-in - extremely slow start."""
283

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

287
def easeInOutQuart(n):
288
    """Quartic ease-in-out - extremely slow start and end."""
289
```
290

291
### Quintic Easing
292
```python { .api }
293
def easeInQuint(n):
294
    """Quintic ease-in - very gradual acceleration."""
295

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

299
def easeInOutQuint(n):
300
    """Quintic ease-in-out - very smooth curve."""
301
```
302

303
### Sine Easing
304
```python { .api }
305
def easeInSine(n):
306
    """Sine ease-in - smooth, gentle acceleration."""
307

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

311
def easeInOutSine(n):
312
    """Sine ease-in-out - very smooth S-curve."""
313
```
314

315
### Exponential Easing
316
```python { .api }
317
def easeInExpo(n):
318
    """Exponential ease-in - very slow start, rapid acceleration."""
319

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

323
def easeInOutExpo(n):
324
    """Exponential ease-in-out - very slow start and end."""
325
```
326

327
### Circular Easing
328
```python { .api }
329
def easeInCirc(n):
330
    """Circular ease-in - curved acceleration."""
331

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

335
def easeInOutCirc(n):
336
    """Circular ease-in-out - smooth circular curve."""
337
```
338

339
### Elastic Easing
340
```python { .api }
341
def easeInElastic(n):
342
    """Elastic ease-in - bouncy acceleration effect."""
343

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

347
def easeInOutElastic(n):
348
    """Elastic ease-in-out - bouncy at both ends."""
349
```
350

351
### Back Easing
352
```python { .api }
353
def easeInBack(n):
354
    """Back ease-in - slight reverse before forward motion."""
355

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

359
def easeInOutBack(n):
360
    """Back ease-in-out - reverse at start, overshoot at end."""
361
```
362

363
### Bounce Easing
364
```python { .api }
365
def easeInBounce(n):
366
    """Bounce ease-in - bouncing acceleration effect."""
367

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

371
def easeInOutBounce(n):
372
    """Bounce ease-in-out - bouncing at both ends."""
373
```
374

375
## Global Configuration Constants
376

377
```python { .api }
378
# Timing and safety configuration
379
PAUSE: float = 0.1                    # Global pause between function calls (seconds)
380
FAILSAFE: bool = True                 # Enable failsafe mechanism (move mouse to corner to abort)
381
MINIMUM_DURATION: float = 0.1         # Minimum duration for mouse movements (seconds)
382
MINIMUM_SLEEP: float = 0.05          # Minimum sleep time (seconds)
383
DARWIN_CATCH_UP_TIME: float = 0.01   # macOS interface catch-up time (seconds)
384

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

389
# Failsafe trigger coordinates
390
FAILSAFE_POINTS: List[Tuple[int, int]] # Screen corner coordinates that trigger failsafe
391
```
392

393
## Usage Examples
394

395
```python
396
import pyautogui
397
import time
398

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

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

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

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

414
pyautogui.sleep(1.5)    # Sleep for 1.5 seconds
415

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

421
# Print all system info
422
pyautogui.printInfo()
423

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

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

431
# Failsafe configuration
432
original_failsafe = pyautogui.FAILSAFE
433
pyautogui.FAILSAFE = False    # Disable failsafe temporarily
434
# ... perform operations that might trigger failsafe ...
435
pyautogui.FAILSAFE = original_failsafe  # Restore setting
436

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

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

449
# Mathematical utilities
450
start_point = (100, 100)
451
end_point = (300, 400)
452

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

460
# Command string interface
461
pyautogui.run('''
462
    click(100, 200);
463
    sleep(0.5);
464
    type("Hello World");
465
    key(enter);
466
    move(300, 400)
467
''')
468

469
# Configuration management
470
def setup_pyautogui_config():
471
    """Configure PyAutoGUI for specific automation task"""
472
    # Save original settings
473
    original_pause = pyautogui.PAUSE
474
    original_failsafe = pyautogui.FAILSAFE
475
    
476
    # Apply task-specific settings
477
    pyautogui.PAUSE = 0.5           # Slower for stability
478
    pyautogui.FAILSAFE = True       # Keep safety enabled
479
    pyautogui.LOG_SCREENSHOTS = True  # Enable debugging
480
    
481
    return original_pause, original_failsafe
482

483
def restore_pyautogui_config(original_pause, original_failsafe):
484
    """Restore original PyAutoGUI configuration"""
485
    pyautogui.PAUSE = original_pause
486
    pyautogui.FAILSAFE = original_failsafe
487
    pyautogui.LOG_SCREENSHOTS = False
488

489
# Usage
490
saved_config = setup_pyautogui_config()
491
try:
492
    # Perform automation tasks with custom configuration
493
    pyautogui.click(100, 100)
494
    pyautogui.typewrite("Configured automation")
495
finally:
496
    # Always restore original configuration
497
    restore_pyautogui_config(*saved_config)
498

499
# Advanced debugging workflow
500
def debug_automation_script():
501
    """Debug automation script with position tracking"""
502
    print("Position debugging mode - move mouse to desired locations")
503
    print("Press Ctrl+C when done")
504
    
505
    positions = []
506
    try:
507
        while True:
508
            x, y = pyautogui.position()
509
            pixel_color = pyautogui.pixel(x, y)
510
            
511
            print(f"\rMouse: ({x:4}, {y:4}) | RGB: {pixel_color} | "
512
                  f"On screen: {pyautogui.onScreen(x, y)}", end='')
513
            
514
            time.sleep(0.1)
515
            
516
    except KeyboardInterrupt:
517
        print("\nDebug session ended")
518
        return positions
519

520
# Performance testing with different easing functions
521
def test_easing_performance():
522
    """Test different easing functions for movement performance"""
523
    easing_functions = [
524
        ('linear', pyautogui.linear),
525
        ('easeInQuad', pyautogui.easeInQuad),
526
        ('easeOutQuad', pyautogui.easeOutQuad),
527
        ('easeInOutQuad', pyautogui.easeInOutQuad),
528
        ('easeInBounce', pyautogui.easeInBounce),
529
        ('easeOutBounce', pyautogui.easeOutBounce)
530
    ]
531
    
532
    start_pos = (100, 100)
533
    end_pos = (500, 400)
534
    duration = 1.0
535
    
536
    for name, func in easing_functions:
537
        print(f"Testing {name} easing...")
538
        start_time = time.time()
539
        pyautogui.moveTo(start_pos[0], start_pos[1])
540
        pyautogui.moveTo(end_pos[0], end_pos[1], duration=duration, tween=func)
541
        elapsed = time.time() - start_time
542
        print(f"  Completed in {elapsed:.2f} seconds")
543
        time.sleep(0.5)  # Brief pause between tests
544

545
# Run performance test
546
# test_easing_performance()
547
```
548

549
## Integration Notes
550

551
### PyTweening Integration
552
- All easing functions provided by PyTweening library
553
- Used in mouse movement and dragging operations
554
- Provides natural, smooth animations for better user experience
555

556
### MouseInfo Integration  
557
- `mouseInfo()` function launches separate debugging application
558
- Enhanced coordinate tracking and color analysis tools
559
- Useful for developing and debugging automation scripts
560

561
### Cross-Platform Considerations
562
- Some utilities may behave differently across platforms
563
- Screen size detection works on all platforms
564
- Mouse position tracking available universally
565
- Easing functions work consistently across platforms