WindMouse

https://windmouse.readthedocs.io/en/latest/
Admin
WindMouse is a Python library that generates realistic, human-like mouse movements using a...
Tokens:52,905
Snippets:653
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Install the package with all optional dependencies for development, docs, and testing.

```bash
pip install -e .[all,dev,docs]
```

--------------------------------

### Development install with pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Clones the WindMouse repository and installs it in development mode with all backends and development dependencies.

```bash
git clone https://github.com/AsfhtgkDavid/windmouse.git
cd windmouse
pip install -e .[all,dev]
```

--------------------------------

### Install dependencies with uv

Source: https://windmouse.readthedocs.io/en/latest/contributing.html

Install all dependencies using uv, which is the recommended method. This syncs all dependency groups defined in the project.

```bash
uv sync --all-groups

```

--------------------------------

### Install WindMouse with pip

Source: https://windmouse.readthedocs.io/en/latest/quickref.html

Install WindMouse with pip. Options include basic installation, with PyAutoGUI (recommended), or with AutoHotkey (Windows only).

```bash
# Basic installation
pip install windmouse

# With PyAutoGUI (recommended)
pip install windmouse[pyautogui]

# With AutoHotkey (Windows only)
pip install windmouse[ahk]

```

--------------------------------

### Install windmouse[pyautogui] extra

Source: https://windmouse.readthedocs.io/en/latest/installation.html

Install the PyAutoGUI backend extra to resolve the ImportError that occurs when the backend is missing.

```bash
pip install windmouse[pyautogui]

```

--------------------------------

### Development setup with uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Clones the WindMouse repository and syncs all dependency groups using uv for development.

```bash
git clone https://github.com/AsfhtgkDavid/windmouse.git
cd windmouse
uv sync --all-groups
```

--------------------------------

### Install dependencies with uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Recommended alternative to pip: sync all dependency groups using uv.

```bash
uv sync --all-groups
```

--------------------------------

### Install and use Xvfb for headless servers

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Use on headless Linux servers to provide a virtual display for WindMouse. Install Xvfb with apt-get, then run your script with xvfb-run.

```bash
# Install Xvfb
sudo apt-get install xvfb

# Run your script with virtual display
xvfb-run python your_script.py
```

--------------------------------

### Create and activate a virtual environment, then install WindMouse in development mode

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Sets up a virtual environment and installs WindMouse in editable mode with all development and documentation dependencies. The activation command differs by platform: use 'source venv/bin/activate' on Linux/macOS and 'venv\Scripts\activate' on Windows.

```bash
python -m venv venv
```

```bash
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
```

```bash
pip install -e .[all,dev,docs]
```

--------------------------------

### Install WindMouse with all backends via pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs WindMouse with both PyAutoGUI and AutoHotkey backends at once.

```bash
pip install windmouse[all]
```

--------------------------------

### Install WindMouse core with pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs the core WindMouse library and its NumPy dependency without any controller backends.

```bash
pip install windmouse
```

--------------------------------

### Verify installation

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Run a quick Python command to confirm the PyautoguiMouseController can be imported successfully.

```python
python -c "from windmouse.pyautogui_controller import PyautoguiMouseController; print('Success!')"
```

--------------------------------

### Install WindMouse with AutoHotkey backend via pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs WindMouse with the AutoHotkey backend, which is Windows-only and requires AutoHotkey to be installed and in PATH.

```bash
pip install windmouse[ahk]
```

--------------------------------

### Example function with Google-style docstring

Source: https://windmouse.readthedocs.io/en/latest/contributing.html

Example of a function with a Google-style docstring, including type hints and documentation for parameters, return value, and exceptions.

```python
def example_function(param1: int, param2: str) -> bool:
    """
    Brief description of the function.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When invalid input is provided.
    """
    pass

```

--------------------------------

### Commit message example: docs

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Example of a documentation commit message.

```text
docs: Add troubleshooting section for Linux permissions
```

--------------------------------

### Quick Example: Move mouse to target with PyautoguiMouseController

Source: https://windmouse.readthedocs.io/en/latest/_sources/index.rst.txt

Initializes a PyautoguiMouseController, sets the destination coordinates to (800, 600), and moves the mouse to that target. This is the basic usage example from the documentation.

```python
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Initialize the controller
mouse = PyautoguiMouseController()

# Set destination and move
mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target()
```

--------------------------------

### Import order example

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Shows the standard Python import order: standard library, third-party, then local imports.

```python
# Standard library
import enum
import time
from abc import ABC, abstractmethod

# Third-party
import numpy as np

# Local
from .core import Coordinate
```

--------------------------------

### Linear Interpolation Example

Source: https://windmouse.readthedocs.io/en/latest/_sources/algorithm.rst.txt

Shows a simple linear interpolation formula for comparison with WindMouse's non-linear paths.

```python
# Linear
x = start_x + (dest_x - start_x) * t
```

--------------------------------

### AbstractMouseController.__init__(start_x, start_y, dest_x, dest_y, gravity_magnitude, wind_magnitude, max_step, damped_distance)

Source: https://windmouse.readthedocs.io/en/latest/_modules/windmouse/core.html

Initializes a mouse controller with optional start and destination coordinates and WindMouse algorithm parameters.

```APIDOC
## AbstractMouseController.__init__(start_x, start_y, dest_x, dest_y, gravity_magnitude, wind_magnitude, max_step, damped_distance)

### Description
Initializes a mouse controller with optional start and destination coordinates and WindMouse algorithm parameters.

### Parameters
- **start_x** (Coordinate | None) - Optional - Initial x-coordinate. If None, defaults to the current mouse position upon first use.
- **start_y** (Coordinate | None) - Optional - Initial y-coordinate. If None, defaults to the current mouse position upon first use.
- **dest_x** (Coordinate | None) - Optional - Destination x-coordinate. Can be set later if None.
- **dest_y** (Coordinate | None) - Optional - Destination y-coordinate. Can be set later if None.
- **gravity_magnitude** (float) - Optional - magnitude of the gravitational force. Default: 9.
- **wind_magnitude** (float) - Optional - magnitude of the wind force fluctuations. Default: 3.
- **max_step** (float) - Optional - maximum step size (velocity clip threshold). Default: 15.
- **damped_distance** (float) - Optional - distance where wind behavior changes from random to damped. Default: 12.
```

--------------------------------

### Install pyautogui type stubs for mypy

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Install type stubs for pyautogui to resolve mypy errors in WindMouse code.

```bash
pip install types-pyautogui
```

--------------------------------

### Install WindMouse with pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/quickref.rst.txt

Install WindMouse with pip. The base package installs core functionality; the [pyautogui] extra adds PyAutoGUI support (recommended), and the [ahk] extra adds AutoHotkey support on Windows only.

```bash
# Basic installation
pip install windmouse

# With PyAutoGUI (recommended)
pip install windmouse[pyautogui]

# With AutoHotkey (Windows only)
pip install windmouse[ahk]
```

--------------------------------

### Example function with docstring

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Shows the required Google/NumPy style docstring format for public APIs, including Args, Returns, and Raises sections.

```python
def example_function(param1: int, param2: str) -> bool:
    """
    Brief description of the function.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When invalid input is provided.
    """
    pass
```

--------------------------------

### Install WindMouse with PyAutoGUI backend via pip

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs WindMouse with the PyAutoGUI backend, which works on Windows, macOS, and Linux.

```bash
pip install windmouse[pyautogui]
```

--------------------------------

### Bug report example: ValueError with None start_position

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Example bug report showing a ValueError when start_position has None for x. It includes environment details, steps to reproduce, expected vs actual behavior, and the traceback.

```text
Title: ValueError when using None as start_position

**Environment:**
- Python 3.11
- Windows 11
- WindMouse 1.0.0
- PyAutoGUI backend

**Steps to Reproduce:**
```python
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()
mouse.start_position = (None, Coordinate(100))
mouse.dest_position = (Coordinate(500), Coordinate(500))
mouse.move_to_target()
```

**Expected:** Should use current x position
**Actual:** Raises ValueError

**Traceback:**
```
ValueError: start_x cannot be None when start_y is set
```
```

--------------------------------

### Optimized WindMouse Configuration

Source: https://windmouse.readthedocs.io/en/latest/_sources/algorithm.rst.txt

Example configuration for performance-critical applications, increasing max_step and gravity_magnitude, and reducing tick_delay and step_duration.

```python
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController(
    max_step=20,  # Increase speed
    gravity_magnitude=12,  # More direct
)

mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target(
    tick_delay=0,  # No delay
    step_duration=0.01  # Fast transitions
)
```

--------------------------------

### Add WindMouse with uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Adds WindMouse as a dependency using the uv package installer.

```bash
uv add windmouse
```

--------------------------------

### Context manager pattern for WindMouse controller

Source: https://windmouse.readthedocs.io/en/latest/usage.html

Create a context manager for cleanup, even though it is not built-in. The example shows defining windmouse_controller and using it with a with statement, passing gravity_magnitude=10.

```python
from contextlib import contextmanager
from windmouse.pyautogui_controller import PyautoguiMouseController

@contextmanager
def windmouse_controller(**kwargs):
    """Context manager for WindMouse controller."""
    controller = PyautoguiMouseController(**kwargs)
    try:
        yield controller
    finally:
        # Cleanup if needed
        pass

# Usage
with windmouse_controller(gravity_magnitude=10) as mouse:
    mouse.dest_position = (Coordinate(800), Coordinate(600))
    mouse.move_to_target()

```

--------------------------------

### Build documentation with make html

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Build the documentation locally using Make and view the generated HTML in the default browser. The commands for opening the file differ by operating system.

```bash
cd docs
make html

# View in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux
start _build/html/index.html  # Windows
```

--------------------------------

### Commit message example: feat

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Example of a feature commit message.

```text
feat: Add support for circular mouse paths

Implements a new CircularPathController that moves the mouse
in circular trajectories instead of WindMouse paths.
```

--------------------------------

### Commit message example: fix

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Example of a bug fix commit message.

```text
fix: Correct velocity clamping calculation

The max_step parameter was not being applied correctly in
close-range scenarios. This fixes the clamping logic.
```

--------------------------------

### Build documentation locally with make html or sphinx-build

Source: https://windmouse.readthedocs.io/en/latest/contributing.html

Build the documentation locally. The first block uses the Makefile (make html) and includes commands to open the generated HTML in a browser on macOS, Linux, or Windows. The second block builds the same output using Sphinx directly with sphinx-build -b html.

```bash
cd docs
make html

# View in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux
start _build/html/index.html  # Windows

```

```bash
sphinx-build -b html docs docs/_build/html

```

--------------------------------

### Install Linux dependencies for PyAutoGUI

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs additional Linux dependencies required by PyAutoGUI on Ubuntu/Debian, Fedora, and Arch Linux.

```bash
# Ubuntu/Debian
sudo apt-get install python3-tk python3-dev

# Fedora
sudo dnf install python3-tkinter python3-devel

# Arch Linux
sudo pacman -S tk
```

--------------------------------

### Add WindMouse with all backends via uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Adds WindMouse with all backends using uv.

```bash
uv add "windmouse[all]"
```

--------------------------------

### Resource Management (AHK)

Source: https://windmouse.readthedocs.io/en/latest/_sources/examples.rst.txt

Demonstrates creating a single AHK instance and reusing it for multiple AHKMouseController instances, allowing efficient resource management.

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

# Create AHK instance once
ahk = AHK()

# Reuse for multiple controllers
mouse1 = AHKMouseController(ahk)
mouse2 = AHKMouseController(ahk)

# Use different controllers
mouse1.dest_position = (Coordinate(100), Coordinate(100))
mouse1.move_to_target()

mouse2.dest_position = (Coordinate(500), Coordinate(500))
mouse2.move_to_target()
```

--------------------------------

### Set start and destination separately with PyautoguiMouseController

Source: https://windmouse.readthedocs.io/en/latest/usage.html

Set start and destination coordinates independently. If start_position is not set, the controller automatically uses the current mouse position.

```python
mouse = PyautoguiMouseController()

# Set start position explicitly
mouse.start_position = (Coordinate(100), Coordinate(100))

# Set destination
mouse.dest_position = (Coordinate(500), Coordinate(500))

# Or set coordinates individually
mouse.dest_x = Coordinate(800)
mouse.dest_y = Coordinate(600)

mouse.move_to_target()

```

--------------------------------

### PyAutoGUI Backend (Cross-Platform)

Source: https://windmouse.readthedocs.io/en/latest/_sources/usage.rst.txt

Create a PyautoguiMouseController instance, set destination coordinates, and move to target with default settings.

```APIDOC
## PyautoguiMouseController

### Description
Create a controller instance for cross-platform mouse movement using PyAutoGUI backend.

### Constructor
`PyautoguiMouseController()`

### Properties
- `dest_position` (tuple of Coordinate) - Set the destination coordinates.

### Methods
#### move_to_target()
Moves the mouse to the destination with default settings.

**Parameters** (optional):
- `tick_delay` (float, default: 0) - Sleep time in seconds between each movement step.
- `step_duration` (float, default: 0.1) - Duration in seconds for each individual movement step.
- `hold_button` (HoldMouseButton, default: HoldMouseButton.NONE) - Specifies which mouse button to hold during movement.

**Example**
```python
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

mouse = PyautoguiMouseController()
mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target()
```
```

--------------------------------

### Example of good reStructuredText documentation

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Example of good reStructuredText documentation. It shows how to structure a section with a heading, a subheading, and an embedded Python code block that customizes physics parameters.

```rst
Advanced Usage
==============

This section covers advanced usage patterns.

Custom Physics
--------------

You can customize the physics parameters:

.. code-block:: python

   from windmouse.pyautogui_controller import PyautoguiMouseController

   mouse = PyautoguiMouseController(
       gravity_magnitude=12,
       wind_magnitude=5
   )

See :doc:`algorithm` for details on parameter effects.
```

--------------------------------

### Set start and destination coordinates separately

Source: https://windmouse.readthedocs.io/en/latest/_sources/usage.rst.txt

Sets start and destination coordinates independently before calling move_to_target(). If start_position is not set, the controller automatically uses the current mouse position.

```python
mouse = PyautoguiMouseController()

# Set start position explicitly
mouse.start_position = (Coordinate(100), Coordinate(100))

# Set destination
mouse.dest_position = (Coordinate(500), Coordinate(500))

# Or set coordinates individually
mouse.dest_x = Coordinate(800)
mouse.dest_y = Coordinate(600)

mouse.move_to_target()
```

--------------------------------

### Build documentation with sphinx-build

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Build the documentation directly with Sphinx, bypassing the Makefile. This command outputs HTML to docs/_build/html.

```bash
sphinx-build -b html docs docs/_build/html
```

--------------------------------

### Add WindMouse with AutoHotkey backend via uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Adds WindMouse with the AutoHotkey backend using uv.

```bash
uv add "windmouse[ahk]"
```

--------------------------------

### Add WindMouse with PyAutoGUI backend via uv

Source: https://windmouse.readthedocs.io/en/latest/_sources/installation.rst.txt

Adds WindMouse with the PyAutoGUI backend using uv.

```bash
uv add "windmouse[pyautogui]"
```

--------------------------------

### Test with different parameters

Source: https://windmouse.readthedocs.io/en/latest/_sources/contributing.rst.txt

Test the controller with different parameter sets. Each configuration is passed as keyword arguments to the constructor, then the destination is set and the movement is triggered.

```python
test_configs = [
    {"gravity_magnitude": 5, "wind_magnitude": 8},
    {"gravity_magnitude": 12, "wind_magnitude": 1},
    {"max_step": 5, "damped_distance": 30},
]

for config in test_configs:
    mouse = PyautoguiMouseController(**config)
    mouse.dest_position = (Coordinate(500), Coordinate(500))
    mouse.move_to_target()
```

--------------------------------

### Testing: parameter configurations

Source: https://windmouse.readthedocs.io/en/latest/contributing.html

Test different parameter configurations for the mouse controller. Use this to verify behavior with various gravity, wind, and damping settings.

```python
test_configs = [
    {"gravity_magnitude": 5, "wind_magnitude": 8},
    {"gravity_magnitude": 12, "wind_magnitude": 1},
    {"max_step": 5, "damped": 30},
]

for config in test_configs:
    mouse = PyautoguiMouseController(**config)
    mouse.dest_position = (Coordinate(500), Coordinate(500))
    mouse.move_to_target()
```

--------------------------------

### Basic Movement with PyAutoGUI (Cross-Platform)

Source: https://windmouse.readthedocs.io/en/latest/_sources/examples.rst.txt

Creates a PyautoguiMouseController with default parameters and moves to a target coordinate. Use this for cross-platform mouse movement.

```python
from windmouse.pyautogui_controller import PyautoguiMouseController
from windmouse import Coordinate

# Create controller with default parameters
mouse = PyautoguiMouseController()

# Move to target
mouse.dest_position = (Coordinate(800), Coordinate(600))
mouse.move_to_target()
```

--------------------------------

### AutoHotkey Backend (Windows)

Source: https://windmouse.readthedocs.io/en/latest/_sources/usage.rst.txt

Create an AHKMouseController instance with AHK, set destination coordinates, and move to target.

```APIDOC
## AHKMouseController

### Description
Create a controller instance for Windows-specific mouse movement using AutoHotkey backend.

### Constructor
`AHKMouseController(ahk)`

**Parameters**:
- `ahk` (AHK) - An initialized AHK instance.

### Properties
- `dest_position` (tuple of Coordinate) - Set the destination coordinates.

### Methods
#### move_to_target()
Moves the mouse to the destination with default settings.

**Parameters** (optional):
- `tick_delay` (float, default: 0) - Sleep time in seconds between each movement step.
- `step_duration` (float, default: 0.1) - Duration in seconds for each individual movement step.
- `hold_button` (HoldMouseButton, default: HoldMouseButton.NONE) - Specifies which mouse button to hold during movement.

**Example**
```python
from ahk import AHK
from windmouse.ahk_controller import AHKMouseController
from windmouse import Coordinate

ahk = AHK()
mouse = AHKMouseController(ahk)
mouse.dest_position = (Coordinate(1920), Coordinate(1080))
mouse.move_to_target()
```
```
Tokens:
Raw