Engine API

class autokey.scripting.Engine(config_manager, runner)

Provides access to the internals of AutoKey.

Note that any configuration changes made using this API while the configuration window is open will not appear until it is closed and re-opened.

create_abbreviation(folder, description, abbr, contents)

DEPRECATED. Use engine.create_phrase() with appropriate keyword arguments instead. Create a new text phrase inside the given folder and assign the abbreviation given.

Usage: engine.create_abbreviation(folder, description, abbr, contents)

When the given abbreviation is typed, it will be replaced with the given text.

Parameters:

• folder – folder to place the abbreviation in, retrieved using engine.get_folder()

• description – description for the phrase

• abbr – the abbreviation that will trigger the expansion

• contents – the expansion text

Raises:

Exception – if the specified abbreviation is not unique

create_folder(title: str, parent_folder=None, temporary=False)

Create and return a new folder.

Usage: engine.create_folder("new folder"), parent_folder=folder, temporary=True

Descriptions for the optional arguments:

Parameters:

parentFolder – Folder to make this folder a subfolder of. If

passed as a folder, it will be that folder within auotkey. If passed as pathlib.Path, it will be created or added at that path. Paths expand ~ to $HOME. :param temporary: Folders created with temporary=True are

not persisted. Used for single-source rc-style scripts. Cannot be used if parent_folder is a Path.

If a folder of that name already exists, this will return it unchanged. If the folder wasn’t already added to autokey, it will be. The ‘temporary’ property is not touched to avoid deleting an existing folder. Note that if more than one folder has the same title, only the first match will be returned.

create_hotkey(folder, description, modifiers, key, contents)

DEPRECATED. Use engine.create_phrase() with appropriate keyword arguments instead.

Create a text hotkey

Usage: engine.create_hotkey(folder, description, modifiers, key, contents)

When the given hotkey is pressed, it will be replaced with the given text. Modifiers must be given as a list of strings, with the following values permitted:

<ctrl> <alt> <super> <hyper> <meta> <shift>

The key must be an unshifted character (i.e. lowercase)

Parameters:

• folder – folder to place the abbreviation in, retrieved using engine.get_folder()

• description – description for the phrase

• modifiers – modifiers to use with the hotkey (as a list)

• key – the hotkey

• contents – the expansion text

Raises:

Exception – if the specified hotkey is not unique

create_phrase(folder, name: str, contents: str, abbreviations: str | List[str] | None = None, hotkey: Tuple[List[Key | str], Key | str] | None = None, send_mode: SendMode = SendMode.CB_CTRL_V, window_filter: str | None = None, show_in_system_tray: bool = False, always_prompt: bool = False, temporary=False, replace_existing_hotkey=False)

Create a new text phrase inside the given folder. Use engine.get_folder(folder_name) to retrieve the folder you wish to create the Phrase in. If the folder is a temporary one, the phrase will be created as temporary.

The first three arguments (folder, name and contents) are required. All further arguments are optional and considered to be keyword-argument only. Do not rely on the order of the optional arguments. The optional parameters can be used to configure the newly created Phrase.

Usage (minimal example): engine.create_phrase(folder, name, contents)

Further concrete examples: C{ engine.create_phrase(folder, “My new Phrase”, “This is the Phrase content”, abbreviations=[“abc”, “def”], hotkey=([engine.Key.SHIFT], engine.Key.NP_DIVIDE), send_mode=engine.SendMode.CB_CTRL_SHIFT_V, window_filter=”konsole.Konsole”, show_in_system_tray=True) }

Descriptions for the optional arguments:

abbreviations may be a single string or a list of strings. Each given string is assigned as an abbreviation to the newly created phrase.

hotkey parameter: The hotkey parameter accepts a 2-tuple, consisting of a list of modifier keys in the first element and an unshifted (lowercase) key as the second element. Modifier keys must be given as a list of strings (or Key enum instances), with the following values permitted:

<ctrl> <alt> <super> <hyper> <meta> <shift>

The key must be an unshifted character (i.e. lowercase) or a Key enum instance. Modifier keys from the list above are NOT allowed here. Example: ([“<ctrl>”, “<alt>”], “9”) to assign “<Ctrl>+<Alt>+9” as a hotkey. The Key enum contains objects representing various special keys and is available as an attribute of the “engine” object, named “Key”. So to access a function key, you can use the string “<f12>” or engine.Key.F12 See the AutoKey Wiki for an overview of all available keys in the enumeration.

send_mode: This parameter configures how AutoKey sends the phrase content, for example by typing or by pasting using the clipboard. It accepts items from the SendMode enumeration, which is also available from the engine object as engine.SendMode. The parameter defaults to engine.SendMode.KEYBOARD. Available send modes are:

KEYBOARD CB_CTRL_V CB_CTRL_SHIFT_V CB_SHIFT_INSERT SELECTION

To paste the Phrase using “<shift>+<insert>, set send_mode=engine.SendMode.CB_SHIFT_INSERT

window_filter: Accepts a string which will be used as a regular expression to match window titles or applications using the WM_CLASS attribute.

Parameters:

• folder – folder to place the abbreviation in, retrieved using engine.get_folder()

• name – Name/description for the phrase.

• contents – the expansion text

• abbreviations – Can be a single string or a list (or other iterable) of strings. Assigned to the Phrase

• hotkey – A tuple containing a keyboard combination that will be assigned as a hotkey. First element is a list of modifiers, second element is the key.

• send_mode – The pasting mode that will be used to expand the Phrase. Used to configure, how the Phrase is expanded. Defaults to typing using the “CTRL+V” method.

• window_filter – A string containing a regular expression that will be used as the window filter.

• show_in_system_tray – A boolean defaulting to False. If set to True, the new Phrase will be shown in the tray icon context menu.

• always_prompt – A boolean defaulting to False. If set to True, the Phrase expansion has to be manually confirmed, each time it is triggered.

• temporary –

  Hotkeys created with temporary=True are not persisted as .jsons, and are replaced if the description is not unique within the folder.

  Used for single-source rc-style scripts.

• replace_existing_hotkey – If true, instead of warning if the hotkey is already in use by another phrase or folder, it removes the hotkey from those clashes and keeps this phrase’s hotkey.

Raises:

ValueError – If a given abbreviation or hotkey is already in use or parameters are otherwise invalid

:return The created Phrase object. This object is NOT considered part of the public API and exposes the raw

internals of AutoKey. Ignore it, if you don’t need it or don’t know what to do with it. It can be used for _really_ advanced use cases, where further customizations are desired. Use at your own risk. No guarantees are made about the object’s structure. Read the AutoKey source code for details.

get_folder(title: str)

Retrieve a folder by its title

Usage: engine.get_folder(title)

Note that if more than one folder has the same title, only the first match will be returned.

get_macro_arguments()

Get the arguments supplied to the current script via its macro

Usage: engine.get_macro_arguments()

Returns:

the arguments

Return type:

list(str())

get_script_arguments()

Get the arguments supplied to the current script via the scripting api

Usage: engine.get_script_arguments()

Returns:

the arguments

Return type:

list[Any]

get_script_keyword_arguments()

Get the arguments supplied to the current script via the scripting api as keyword args.

Usage: engine.get_script_keyword_arguments()

Returns:

the arguments

Return type:

Dict[str, Any]

get_triggered_abbreviation() → Tuple[str | None, str | None]

This function can be queried by a script to get the abbreviation text that triggered it’s execution.

If a script is triggered by an abbreviation, this function returns a tuple containing two strings. First element is the abbreviation text. The second element is the trigger character that finally caused the execution. It is typically some whitespace character, like ‘ ‘, ‘ ‘ or a newline character. It is empty, if the abbreviation was configured to “trigger immediately”.

If the script execution was triggered by a hotkey, a call to the DBus interface, the tray icon, the “Run” button in the main window or any other means, this function returns a tuple containing two None values.

Usage: abbreviation, trigger_character = engine.get_triggered_abbreviation() You can determine if the script was triggered by an abbreviation by simply testing the truth value of the first returned value.

Returns:

Abbreviation that triggered the script execution, if any.

Return type:

Tuple[Optional[str], Optional[str]]

remove_all_temporary(folder=None, in_temp_parent=False)

Removes all temporary folders and phrases, as well as any within temporary folders. Useful for rc-style scripts that want to change a set of keys.

run_script(description, *args, **kwargs)

Run an existing script using its description or path to look it up

Usage: engine.run_script(description, 'foo', 'bar', foobar='foobar')

Parameters:

description – description of the script to run. If parsable as

an absolute path to an existing file, that will be run instead. :raise Exception: if the specified script does not exist

run_script_from_macro(args)

Used internally by AutoKey for phrase macros

run_system_command_from_macro(args)

Used internally by AutoKey for system macros

set_return_value(val)

Store a return value to be used by a phrase macro

Usage: engine.set_return_value(val)

Parameters:

val – value to be stored