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.
python
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:
python
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](https://www.autohotkey.com/docs/Hotstrings.htm) 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.
python
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](https://docs.python.org/3/library/concurrent.futures.html#future-objects) or a [`asyncio.Task` object](https://docs.python.org/3/library/asyncio-task.html#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](https://peps.python.org/pep-0561/) 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](https://github.com/spyoungtech/ahk/releases/tag/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.