Sync API

The sync API is generated automatically from the async API using unasync.

The sync API is the default API described in most of the README.

class ahk._sync.engine.AHK(*, TransportClass=None, directives=None, executable_path='')[source]

__init__(*, TransportClass=None, directives=None, executable_path='')[source]

add_hotkey(keyname, callback, ex_handler=None)[source]

Register a function to be called when a hotkey is pressed.

Key notes:

You must call the start_hotkeys method for the hotkeys to be active
All hotkeys run in a single AHK process instance (but Python callbacks also get their own thread and can run simultaneously)
If you add a hotkey after the hotkey thread/instance is active, it will be restarted automatically
async functions are not directly supported as callbacks, however you may write a synchronous function that calls asyncio.run/loop.create_task etc.

Parameters:

keyname (str) – the key trigger for the hotkey, such as #n (win+n)
callback (Callable[[], Any]) – callback function to call when the hotkey is triggered
ex_handler (Optional[Callable[[str, Exception], Any]]) – a function which accepts two parameters: the keyname for the hotkey and the exception raised by the callback function.

Return type:

None

Returns:

add_hotstring(trigger, replacement_or_callback, ex_handler=None, options='')[source]

Register a hotstring, e.g., ::btw::by the way

Key notes:

You must call the start_hotkeys method for registered hotstrings to be active
All hotstrings (and hotkeys) run in a single AHK process instance separate from other AHK processes.

Parameters:

trigger (str) – the trigger phrase for the hotstring, e.g., btw
replacement_or_callback (Union[str, Callable[[], Any]]) – the replacement phrase (e.g., by the way) or a Python callable to execute in response to the hotstring trigger
ex_handler (Optional[Callable[[str, Exception], Any]]) – a function which accepts two parameters: the hotstring and the exception raised by the callback function.
options (str) – the hotstring options – same meanings as in AutoHotkey.

Return type:

None

Returns:

set_title_match_mode(title_match_mode, /)[source]

Sets the default title match mode

Has no effect for Window/Control instance methods (these always use hwnd)

Does not affect methods called with blocking=True (because these run in a separate AHK process)

Reference: https://www.autohotkey.com/docs/commands/SetTitleMatchMode.htm

Parameters:: title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) – the match mode (and/or match speed) to set as the default title match mode. Can be 1, 2, 3, ‘Regex’, ‘Fast’, ‘Slow’ or a tuple of these.
Return type:: None
Returns:: None

get_title_match_mode()[source]

Get the title match mode.

I.E. the current value of A_TitleMatchMode

Return type:: str

get_title_match_speed()[source]

Get the title match mode speed.

I.E. the current value of A_TitleMatchModeSpeed

Return type:: str

set_coord_mode(target, relative_to='Screen')[source]

Return type:: None

get_coord_mode(target)[source]

Return type:: str

control_click(button='L', click_count=1, options='', control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Parameters:

button (Literal['L', 'R', 'M', 'LEFT', 'RIGHT', 'MIDDLE']) – the mouse button to use
click_count (int) – how many times to click
options (str) – options – same meaning as in AutoHotkey
control (str) – the control to click
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

Returns:

control_get_text(*, control='', title='', text='', exclude_title='', exclude_text='', title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog to ControlGetText

Parameters:

control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

Returns:

control_get_position(control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog to ControlGetPos

Parameters:

control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[Position, FutureResult[Position]]

Returns:

control_send(keys, control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for ControlSend

Reference: https://www.autohotkey.com/docs/commands/ControlSend.htm

Parameters:

keys (str) –
control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

Returns:

start_hotkeys()[source]

Start the Autohotkey process for triggering hotkeys

Return type:: None

stop_hotkeys()[source]

Stop the Autohotkey process for triggering hotkeys

Return type:: None

set_detect_hidden_windows(value)[source]

Analog for AutoHotkey’s DetectHiddenWindows

Parameters:: value (bool) – The setting value. True to turn on hidden window detection, False to turn it off.
Return type:: None

list_windows(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Enumerate all windows matching the criteria.

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[List[Window], FutureResult[List[Window]]]

Returns:

get_mouse_position(coord_mode=None, *, blocking=True)[source]

Analog for MouseGetPos

Parameters:

coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
blocking (bool) –

Return type:

Union[Tuple[int, int], FutureResult[Tuple[int, int]]]

Returns:

property mouse_position: Tuple[int, int]

Convenience property for get_mouse_position

Returns:

mouse_move(x=None, y=None, *, speed=None, relative=False, blocking=True)[source]

Analog for MouseMove

Parameters:

x (Union[str, int, None]) –
y (Union[str, int, None]) –
speed (Optional[int]) –
relative (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

Returns:

a_run_script(*args, **kwargs)[source]

Deprecated. Use run_script instead.

Return type:: Union[str, FutureResult[str]]

get_active_window(blocking=True)[source]

Gets the currently active window.

Parameters:: blocking (bool) –
Return type:: Union[Window, None, FutureResult[Optional[Window]]]
Returns:

property active_window: Window | None

Gets the currently active window

Returns:

find_windows(func=None, *, title_match_mode=None, title='', text='', exclude_title='', exclude_text='', exact=None)[source]

Return type:: List[Window]

find_windows_by_class(class_name, *, exact=None, title_match_mode=None)[source]

Return type:: List[Window]

find_windows_by_text(text, exact=None, title_match_mode=None)[source]

Return type:: List[Window]

find_windows_by_title(title, exact=None, title_match_mode=None)[source]

Return type:: List[Window]

find_window(func=None, *, title_match_mode=None, title='', text='', exclude_title='', exclude_text='', exact=None)[source]

Return type:: Optional[Window]

find_window_by_class(class_name, exact=None, title_match_mode=None)[source]

Return type:: Optional[Window]

find_window_by_text(text, exact=None, title_match_mode=None)[source]

Return type:: Optional[Window]

find_window_by_title(title, exact=None, title_match_mode=None)[source]

Return type:: Optional[Window]

get_volume(device_number=1)[source]

Return type:: float

key_down(key, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

key_press(key, *, release=True, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

key_release(key, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

key_state(key_name, *, mode=None, blocking=True)[source]

Return type:: Union[int, float, str, None, FutureResult[str], FutureResult[int], FutureResult[float], FutureResult[None]]

key_up(key, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

key_wait(key_name, *, timeout=None, logical_state=False, released=False, blocking=True)[source]

Return type:: Union[int, FutureResult[int]]

run_script(script_text_or_path, /, *, blocking=True, timeout=None)[source]

Return type:: Union[str, FutureResult[str]]

set_send_level(level)[source]

Return type:: None

get_send_level()[source]

Return type:: int

send(s, *, raw=False, key_delay=None, key_press_duration=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

send_raw(s, *, key_delay=None, key_press_duration=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

send_input(s, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

type(s, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

send_play(s, *, key_delay=None, key_press_duration=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

set_capslock_state(state=None, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

set_volume(value, device_number=1, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

show_traytip(title, text, second=1.0, type_id=1, *, silent=False, large_icon=False, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

show_error_traytip(title, text, second=1.0, *, silent=False, large_icon=False, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

show_info_traytip(title, text, second=1.0, *, silent=False, large_icon=False, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

show_warning_traytip(title, text, second=1.0, *, silent=False, large_icon=False, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

show_tooltip(text='', x=None, y=None, which=1)[source]

Return type:: None

hide_tooltip(which=1)[source]

Return type:: None

sound_beep(frequency=523, duration=150, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

sound_get(device_number=1, component_type='MASTER', control_type='VOLUME', *, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

sound_play(filename, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

sound_set(value, device_number=1, component_type='MASTER', control_type='VOLUME', *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_get(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[Window, None, FutureResult[Optional[Window]]]

win_get_text(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

win_get_title(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

win_get_class(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

win_get_position(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[Position, None, FutureResult[Optional[Position]]]

win_get_idlast(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[Window, None, FutureResult[Optional[Window]]]

win_get_pid(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[int, None, FutureResult[Optional[int]]]

win_get_process_name(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[None, str, FutureResult[Optional[str]]]

win_get_process_path(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[str, None, FutureResult[Optional[str]]]

win_get_count(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[int, FutureResult[int]]

win_get_minmax(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[None, int, FutureResult[Optional[int]]]

win_get_control_list(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[List[Control], None, FutureResult[Optional[List[Control]]]]

win_get_from_mouse_position(*, blocking=True)[source]

Return type:: Union[Window, None, FutureResult[Optional[Window]]]

win_exists(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[bool, FutureResult[bool]]

win_activate(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_title(new_title, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_always_on_top(toggle, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_bottom(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_top(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_disable(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_enable(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_redraw(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_style(style, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[bool, FutureResult[bool]]

win_set_ex_style(style, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[bool, FutureResult[bool]]

win_set_region(options, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[bool, FutureResult[bool]]

win_set_transparent(transparency, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_set_trans_color(color, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

windows(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)

Enumerate all windows matching the criteria.

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[List[Window], FutureResult[List[Window]]]

Returns:

right_click(x=None, y=None, click_count=None, direction=None, *, relative=None, blocking=True, coord_mode=None)[source]

Return type:: Optional[FutureResult[None]]

click(x=None, y=None, button=None, click_count=None, direction=None, *, relative=None, blocking=True, coord_mode=None)[source]

Return type:: Optional[FutureResult[None]]

image_search(image_path, upper_bound=(0, 0), lower_bound=None, *, color_variation=None, coord_mode=None, scale_height=None, scale_width=None, transparent=None, icon=None, blocking=True)[source]

https://www.autohotkey.com/docs/commands/ImageSearch.htm

Return type:: Union[Tuple[int, int], None, FutureResult[Optional[Tuple[int, int]]]]

mouse_drag(x, y, *, from_position=None, speed=None, button=1, relative=None, blocking=True, coord_mode=None)[source]

Return type:: None

pixel_get_color(x, y, *, coord_mode=None, alt=False, slow=False, rgb=True, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

pixel_search(search_region_start, search_region_end, color, variation=0, *, coord_mode=None, fast=True, rgb=True, blocking=True)[source]

Return type:: Union[Tuple[int, int], None, FutureResult[Optional[Tuple[int, int]]]]

win_close(title='', text='', seconds_to_wait=None, exclude_title='', exclude_text='', *, blocking=True, title_match_mode=None, detect_hidden_windows=None)[source]

Return type:: Optional[FutureResult[None]]

win_kill(title='', text='', seconds_to_wait=None, exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_minimize(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_maximize(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_restore(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_wait(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Return type:: Union[Window, FutureResult[Window]]

win_wait_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Return type:: Union[Window, FutureResult[Window]]

win_wait_not_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Return type:: Union[Window, FutureResult[Window]]

win_wait_close(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_show(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_hide(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

win_is_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Union[bool, FutureResult[bool]]

win_move(x, y, *, width=None, height=None, title='', text='', exclude_title='', exclude_text='', title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

get_clipboard(*, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

set_clipboard(s, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

get_clipboard_all(*, blocking=True)[source]

Return type:: Union[bytes, FutureResult[bytes]]

set_clipboard_all(contents, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

on_clipboard_change(callback, ex_handler=None)[source]

Return type:: None

clip_wait(timeout=None, wait_for_any_data=False, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

block_input(value, /)[source]

Return type:: None

reg_delete(key_name, value_name=None, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

reg_write(value_type, key_name, value_name=None, value=None, *, blocking=True)[source]

Return type:: Optional[FutureResult[None]]

reg_read(key_name, value_name=None, *, blocking=True)[source]

Return type:: Union[str, FutureResult[str]]

block_forever()[source]

Return type:: NoReturn

class ahk._sync.transport.FutureResult(future)[source]

__init__(future)[source]

result(timeout=None)[source]

Return type:: TypeVar(T_SyncFuture)