Best Practices

Type Safety

Always use Coordinate type for coordinates to ensure type safety:

from windmouse import Coordinate

# Good ✓
mouse.dest_position = (Coordinate(800), Coordinate(600))

# Avoid - may work but not type-safe
# mouse.dest_position = (800, 600)

Error Handling

Handle exceptions gracefully:

from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

try:
    mouse = PyautoguiMouseController()
    mouse.dest_position = (Coordinate(800), Coordinate(600))
    mouse.move_to_target()
except ValueError as e:
    print(f"Configuration error: {e}")
except ImportError as e:
    print(f"Missing dependency: {e}")
except OSError as e:
    print(f"Platform error: {e}")

Resource Management

For AHK backend, reuse the AHK instance across multiple controllers to avoid resource overhead:

from ahk import AHK
from windmouse.ahk_controller import AHKMouseController
from windmouse import Coordinate

# Good ✓ - Create once, reuse multiple times
ahk = AHK()
mouse1 = AHKMouseController(ahk)
mouse2 = AHKMouseController(ahk)

# Avoid - Creates new AHK instance each time
# mouse1 = AHKMouseController(AHK())
# mouse2 = AHKMouseController(AHK())

Controller Reuse

Reuse controller instances for multiple movements:

# Good ✓ - Reuse controller
mouse = PyautoguiMouseController()
for target in targets:
    mouse.dest_position = target
    mouse.move_to_target()

# Avoid - Creates unnecessary instances
# for target in targets:
#     mouse = PyautoguiMouseController()
#     mouse.dest_position = target
#     mouse.move_to_target()

Adding Natural Variation

Use random offsets and parameter variations to make movements less predictable:

import random
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Vary physics parameters
mouse = PyautoguiMouseController(
    gravity_magnitude=random.randint(8, 12),
    wind_magnitude=random.randint(2, 5),
    max_step=random.randint(12, 18)
)

# Add random offset to target
target_x = Coordinate(800 + random.randint(-10, 10))
target_y = Coordinate(600 + random.randint(-10, 10))
mouse.dest_position = (target_x, target_y)
mouse.move_to_target()