v1.0.0

V1

Version 1.0 is a nearly-complete rewrite of the library, includes a major overhaul of the internals, bringing major improvements (as well as some breaking changes in the public API).

Major features/improvements

Here are some of the big improvements coming in 1.0
(code samples are preliminary and subject to change)

Python callbacks for hotkeys

Previously, hotkeys could only be setup to run AutoHotkey scripts as callbacks. Now, Python callables are supported as callbacks.

from ahk import AHK

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

ahk = AHK()
# when WIN + n is pressed, fire `my_callback`
ahk.add_hotkey('#n', callback=my_callback)
ahk.start_hotkeys()  # start the hotkey process thread
ahk.block_forever()  # not strictly needed in all scripts -- stops the script from exiting; sleep forever

Now whenever you press your hotkeys, the python callback will fire.

You can also add an exception handler for your callback:

from ahk import AHK
ahk = AHK()

def go_boom():
    raise Exception('boom!')

def my_ex_handler(hotkey: str, exception: Exception):
    print('exception with callback for hotkey', hotkey, 'Here was the error:', exception)

ahk.add_hotkey('#n', callback=go_boom, ex_handler=my_ex_handler)

Hotstrings are now supported

Hotstrings can also be added to the hotkey process thread.

In addition to Hotstrings supporting normal AHK string replacements, you can also provide Python callbacks (with optional exception handlers) in response to hotstrings triggering.

from ahk import AHK
ahk = AHK()

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

ahk.add_hotstring('btw', 'by the way')  # string replacements
ahk.add_hotstring('btw', my_callback) # call python function in response to hotstring

More of the AutoHotkey API is available

• Support for controls is added
• win_ methods are now available and can be called without a Window object
• TitleMatchMode, CoordMode, DetectHiddenWindows now exposed, both as parameters to functions affected by these settings as well as default change via set_ methods e.g., set_title_match_mode.
• clipboard support is added
• block_input is implemented

Improvements for 'Nonblocking' API

• Virtually all methods that call into AutoHotkey now support the blocking keyword argument (previously, only select methods could do this)
• Nonblocking functionality is now supported in the Async API
• Instead of returning a process object, nonblocking calls now return a concurrent.futures.Future object or a asyncio.Task object (for the Async API), allowing you to more easily get results from nonblocking calls and/or await their completion.

Fully type-hinted API (PEP 561 compliant)

Enjoy all the benefits of a completely type-hinted API. Great for type-hinting and validating your own code, as well as just getting the various intellisense/IDE features that typically come with type-hinted code.

AutoHotkey process is now run as a daemon for performance

This is mostly an internal API change, but it has some impacts on users as well. Mainly, this brings a significant performance boost, stability, and the ability to implement a few more methods that were not possible in the previous execution model.

In v0.13.0, the daemon mode feature was released. Daemon mode uses a single AutoHotkey process to run all of the code (rather than creating a new AutoHotkey process for every method invocation). This is now the default execution model. Additionally, the underlying AutoHotkey code interacts with Python through an explicit messaging protocol, allowing for AutoHotkey to explicitly indicate return types.

Other minor improvements

• run_script can now alternatively accept a path to an autohotkey script instead of only accepting a literal script as a string.

Deprecations and Breaking Changes

While most of the Public API is the same as in v0, there are some significant changes

• Support for Python 3.6 - 3.7 is dropped. The new minimum Python version is 3.8
• Original HotKey implementation has been removed and replaced by add_hotkey. AHK script strings are no longer supported for hotkeys -- only python callbacks are allowed (but your callback can call run_script if you wish).
• ActionChain has been removed
• For clarity, many parameters like blocking have become keyword-only
• The behavior of send/send_input is slightly different - escaping sequences like `n, `r, `t `,, and similar are no longer required to be escaped. However, braces and similar sequences still need to be escaped -- e.g., in 0.x you would do ahk.send_input('hello`, world{!}') -- in 1.x you would do ahk.send_input('hello, world{!}')
• find_window[s][_by] methods no longer use generators. Using list_windows is recommended instead (which is what is now used by these methods).
• In the async API, property setters (e.g., win.title = 'new title') are no longer supported. Use set_ methods (e.g., win.set_title('new title') instead. Setters are still supported in sync API.
• In the async API, property getters (e.g., await win.title) are deprecated. Use get_ methods (e.g., await get_title()) instead. Properties are not deprecated in the sync API.
• run_script no longer accepts the deocde parameter (all output is expected to be in UTF-8) use of Popen keyword arguments have also been removed.
• All encoding keyword arguments have been removed. Encoding is now correctly handled for you and expected to be UTF-8 for inputs and outputs.