API Reference

This page provides detailed API documentation for all public classes, functions, and types in the WindMouse library.

Core Module

wind_mouse Function

windmouse.core.wind_mouse(start_x, start_y, dest_x, dest_y, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

WindMouse algorithm.

Parameters:

  • start_x (NewType(Coordinate, int)) – x coordinate of start point.

  • start_y (NewType(Coordinate, int)) – y coordinate of start point.

  • dest_x (NewType(Coordinate, int)) – x coordinate of destination point.

  • dest_y (NewType(Coordinate, int)) – y coordinate of destination point.

  • gravity_magnitude (float) – magnitude of the gravitational force

  • wind_magnitude (float) – magnitude of the wind force fluctuations

  • max_step (float) – maximum step size (velocity clip threshold)

  • damped_distance (float) – distance where wind behavior changes from random to damped

Return type:

Generator[tuple[NewType(Coordinate, int), NewType(Coordinate, int)], None, None]

Returns:

Generator which yields current x,y coordinates

AbstractMouseController Class

class windmouse.core.AbstractMouseController(start_x=None, start_y=None, dest_x=None, dest_y=None, *, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

Bases: ABC

Abstract Mouse controller class.

Parameters:
__init__(start_x=None, start_y=None, dest_x=None, dest_y=None, *, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

Initialize Mouse controller.

Parameters:

  • start_x (Optional[NewType(Coordinate, int)]) – Initial x-coordinate. If None, defaults to the current mouse position upon first use.

  • start_y (Optional[NewType(Coordinate, int)]) – Initial y-coordinate. If None, defaults to the current mouse position upon first use.

  • dest_x (Optional[NewType(Coordinate, int)]) – Destination x-coordinate. Can be set later if None.

  • dest_y (Optional[NewType(Coordinate, int)]) – Destination y-coordinate. Can be set later if None.

  • gravity_magnitude (float) – See :py:attr: core.wind_mouse.gravity_magnitude

  • wind_magnitude (float) – See :py:attr: core.wind_mouse.wind_magnitude

  • max_step (float) – See :py:attr: core.wind_mouse.max_step

  • damped_distance (float) – See :py:attr: core.wind_mouse.damped_distance

move_to_target(tick_delay=0, step_duration=0.1, hold_button=HoldMouseButton.NONE)[source]

Moves the mouse to the target coordinates using a generated path.

Parameters:

  • tick_delay (float) – Sleep time between movement updates (in seconds).

  • step_duration (float) – Duration of each movement step. Lower values result in faster overall movement.

  • hold_button (HoldMouseButton) – Which mouse button to hold down during movement (for drag & drop).

Return type:

None

property start_x: Coordinate | None

Start x coordinate None means current mouse x coordinate

property start_y: Coordinate | None

Start y coordinate None means current mouse y coordinate

property start_position: tuple[Coordinate | None, Coordinate | None]

Synonym for self.start_x, self.start_y

property dest_x: Coordinate | None

Destination x coordinate

property dest_y: Coordinate | None

Destination y coordinate

property dest_position: tuple[Coordinate | None, Coordinate | None]

Synonym for self.dest_x, self.dest_y

abstractmethod tick(step_duration=0.1)[source]

Advances the mouse cursor to the next point in the trajectory.

This method is designed to be called iteratively in a loop. It moves the mouse one step towards the current target.

Parameters:

step_duration (float) – The duration of this single movement step (in seconds). Used to control the overall speed of the gesture.

Return type:

bool

Returns:

True if the cursor moved to a new point (movement continues). False if the target has been reached or no path remains.

Types and Enums

class windmouse.core.HoldMouseButton(value)[source]
NONE = 'none'
LEFT = 'left'
RIGHT = 'right'
MIDDLE = 'middle'
windmouse.core.Coordinate = NewType('Coordinate', int)

Type alias for coordinate values. Provides type safety for x and y coordinates.

Example:

from windmouse import Coordinate
x = Coordinate(100)
y = Coordinate(200)

Constants

windmouse.core.GRAVITY_MAGNITUDE_DEFAULT = 9

Default gravity magnitude value.

windmouse.core.WIND_MAGNITUDE_DEFAULT = 3

Default wind magnitude value.

windmouse.core.MAX_STEP_DEFAULT = 15

Default maximum step size value.

windmouse.core.DAMPED_DISTANCE_DEFAULT = 12

Default damped distance value.

PyAutoGUI Controller

Cross-platform mouse controller using PyAutoGUI.

class windmouse.pyautogui_controller.PyautoguiMouseController(start_x=None, start_y=None, dest_x=None, dest_y=None, *, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

Bases: AbstractMouseController

Mouse controller implementation using pyautogui.

Parameters:
tick(step_duration=0.1)[source]

Advances the mouse cursor to the next point in the trajectory.

This method is designed to be called iteratively in a loop. It moves the mouse one step towards the current target.

Parameters:

step_duration (float) – The duration of this single movement step (in seconds). Used to control the overall speed of the gesture.

Return type:

bool

Returns:

True if the cursor moved to a new point (movement continues). False if the target has been reached or no path remains.

AutoHotkey Controller

Windows-only mouse controller using AutoHotkey.

class windmouse.ahk_controller.AHKMouseController(ahk, start_x=None, start_y=None, dest_x=None, dest_y=None, *, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

Bases: AbstractMouseController

Parameters:
__init__(ahk, start_x=None, start_y=None, dest_x=None, dest_y=None, *, gravity_magnitude=9, wind_magnitude=3, max_step=15, damped_distance=12)[source]

Initialize Mouse controller.

Parameters:

  • start_x (Optional[NewType(Coordinate, int)]) – Initial x-coordinate. If None, defaults to the current mouse position upon first use.

  • start_y (Optional[NewType(Coordinate, int)]) – Initial y-coordinate. If None, defaults to the current mouse position upon first use.

  • dest_x (Optional[NewType(Coordinate, int)]) – Destination x-coordinate. Can be set later if None.

  • dest_y (Optional[NewType(Coordinate, int)]) – Destination y-coordinate. Can be set later if None.

  • gravity_magnitude (float) – See :py:attr: core.wind_mouse.gravity_magnitude

  • wind_magnitude (float) – See :py:attr: core.wind_mouse.wind_magnitude

  • max_step (float) – See :py:attr: core.wind_mouse.max_step

  • damped_distance (float) – See :py:attr: core.wind_mouse.damped_distance

  • ahk (AHK[Any])

tick(step_duration=2)[source]

Advances the mouse cursor to the next point in the trajectory.

This method is designed to be called iteratively in a loop. It moves the mouse one step towards the current target.

Parameters:

step_duration (float) – The duration of this single movement step (in seconds). Used to control the overall speed of the gesture.

Return type:

bool

Returns:

True if the cursor moved to a new point (movement continues). False if the target has been reached or no path remains.

Exported Types

The main windmouse package exports commonly used types and enums for convenience:

from windmouse import Coordinate, HoldMouseButton

Common Exceptions

ValueError

Raised when destination coordinates are not set before movement.

OSError

Raised when trying to use AHK backend on non-Windows platforms or when trying to import non-installed backends.

For error handling examples, see Examples.

See Also