ahk Python Wrapper

By default, all ahk methods are blocking, meaning the Python script waits for the AHK command to finish. To run commands in the background while your Python script continues, use blocking=False.

Key Characteristics of Non-blocking calls:

• They return a FutureResult object.
• They are isolated in a new AHK process that terminates after completion.
• They do not inherit previous global state changes (like set_coord_mode).
• You can wait for completion using future_result.result(timeout=N).

Example: Moving mouse while tracking position

import time
from ahk import AHK

ahk = AHK()
ahk.mouse_position = (200, 200)

# Start moving mouse in background
future = ahk.mouse_move(x=100, y=100, speed=30, blocking=False)

# Python continues immediately
while True:
    pos = ahk.mouse_position
    print(f"Current position: {pos}")
    if pos == (100, 100):
        break

# Ensure the background task is finished
future.result(timeout=10)

from ahk import AHK
ahk = AHK()
future_result = ahk.mouse_move(100, 100, speed=40, blocking=False)
# ... do other work ...
future_result.result(timeout=10)

Hotkeys and Hotstrings run in a separate background process. To use them, you must explicitly call ahk.start_hotkeys().

• Hotkeys: Map key combinations (using AHK syntax like #n for Win+n) to Python callback functions.
• Hotstrings: Can perform text replacement (e.g., btw $\rightarrow$ by the way) or trigger a Python callback.

If you add or remove hotkeys/hotstrings while the process is running, the underlying AHK process is automatically restarted. Use ahk.block_forever() in scripts that only serve hotkeys to prevent the Python script from exiting immediately.

from ahk import AHK

def my_callback():
    print('Hello callback!')

ahk = AHK()

# Register a hotkey (Win + n)
ahk.add_hotkey('#n', callback=my_callback)

# Register a hotstring (replacement)
ahk.add_hotstring('btw', 'by the way')

# Register a hotstring (callback)
ahk.add_hotstring('trigger', my_callback)

ahk.start_hotkeys()
ahk.block_forever()

While the ahk Python API maintains consistent function signatures across versions, the underlying behavior changes when using AutoHotkey v2 due to changes in the AutoHotkey engine. Notable differences include:

• Error Handling: Functions that find and return windows may raise a TargetError in v2 instead of returning None when a window or control is not found.
• ControlSend Behavior: In v1, ahk.control_send (or Window.send/Control.send) sends keys to the topmost controls if no control is specified. In v2, keys are sent directly to the window. You should specify the control parameter explicitly in v2 to ensure consistent behavior.
• TrayTip Limitations: The secondstowait parameter for ahk.show_traytip is not supported in v2. Specifying it will trigger a warning and the parameter will be ignored.
• Missing Features: Some sound functions available in v1 are not yet implemented in the v2 version of the library.
• SendMode: The default SendMode in v2 is Input, whereas v1 defaults to Event. Consequently, mouse speed parameters in mouse_move or mouse_drag will be ignored in v2 unless the send mode is manually changed.
• TitleMatchMode: The default TitleMatchMode is 2 in v2, compared to 1 in v1. You can control this using the title_match_mode keyword argument in methods like win_get, or by using set_title_match_mode to change the global default (note: non-blocking calls run in separate processes and are not affected by set_title_match_mode).

By default, the library searches for AutoHotkey v1 binaries. To use AutoHotkey v2, you must explicitly specify it using one of the following methods:

1. executable_path: Provide the direct path to the v2 binary via the executable_path keyword argument in the AHK constructor.
2. AHK_PATH environment variable: Set the AHK_PATH environment variable to the location of your v2 binary.
3. version keyword argument: Pass version='v2' to the AHK constructor. This enables the library to search for v2 binary names and default installation locations.

If you provide the version keyword (either 'v1' or 'v2'), the library performs a check to ensure the discovered binary matches the requested version. If omitted, the version is determined automatically from the binary.

from ahk import AHK

# Method 1: Explicit path
ahk = AHK(executable_path=r'C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe')

# Method 2: Using the version keyword
ahk = AHK(version='v2')

An extension consists of two parts: an AutoHotkey function and a Python function.

1. AHK Function: Must accept zero or more arguments and return a formatted message using FormatResponse(message_type_name, payload).
2. Python Function: Must accept an instance of AHK (or AsyncAHK) as its first parameter. Use the @extension.register decorator to bind the Python function to the extension.

To use the extension automatically, instantiate AHK with extensions='auto'.

from ahk import AHK
from ahk.extensions import Extension

# 1. The AHK code
script_text = r'''
SimpleMath(lhs, rhs, operator) {
    if (operator = "+") {
        result := (lhs + rhs)
    } else {
        return FormatResponse("ahk.message.ExceptionResponseMessage", Format("Invalid operator: {}", operator))
    }
    return FormatResponse("ahk.message.IntegerResponseMessage", result)
}
'''

# 2. The Extension object
simple_math_extension = Extension(script_text=script_text)

# 3. The Python registration
@simple_math_extension.register
def simple_math(ahk: AHK, lhs: int, rhs: int, operator: str) -> int:
    args = [str(lhs), str(rhs), operator]
    return ahk.function_call('SimpleMath', args, blocking=True)

# 4. Usage
ahk = AHK(extensions='auto')
print(ahk.simple_math(2, 2, '+')) # 4