The Script Engine

The script module, most essentially, houses the ScriptEngine class.

The ScriptEngine is responsible for rendering autohotkey code from jinja templates and executing that code. This is the heart of how this package works. Every other major component either inherits from this class or utilizes an instance of this class.

The current implementation of how autohotkey code is executed is by calling the autohotkey executable with subprocess.

ahk.script.DEFAULT_EXECUTABLE_PATH = C:\Program Files\AutoHotkey\AutoHotkey.exe

The deafult path to look for AutoHotkey, if not specified some other way

class ahk.script.AsyncScriptEngine(executable_path='', directives=None, **kwargs)

async run_script(script_text, decode=True, blocking=True, **runkwargs)

async version of run_script

Parameters

• script_text (str) – a string containing AutoHotkey code

• decode – If True, attempt to decode the stdout of the completed process. If False, returns the completed process. Only has effect when blocking=True

• blocking – If True, script must finish before returning. If False, function returns a asyncio.process object immediately without blocking

• runkwargs – keyword arguments passed to subprocess.Popen or subprocess.run

Returns

A string of the decoded stdout if blocking and decode are True.

A bytes object of stdout if blocking is True and decode is False.

asyncio.subprocess.Process object if blocking is False.

ahk.script.DEFAULT_EXECUTABLE_PATH = 'C:\\Program Files\\AutoHotkey\\AutoHotkey.exe'

The deafult path to look for AutoHotkey, if not specified some other way

exception ahk.script.ExecutableNotFoundError

class ahk.script.ScriptEngine(executable_path='', directives=None, **kwargs)

__init__(executable_path='', directives=None, **kwargs)

This class is typically not used directly. AHK components inherit from this class and the arguments for this class should usually be passed in to AHK.

Parameters

• executable_path (str) –

  the path to the AHK executable. If not provided explicitly in this argument, the path to the AHK executable is resolved in the following order:

  • The AHK_PATH environment variable, if present

  • DEFAULT_EXECUTABLE_PATH if the file exists

  If environment variable not present, tries to look for ‘AutoHotkey.exe’ or ‘AutoHotkeyA32.exe’ with shutil.which

• directives (Optional[Set]) – a set of directives to apply to all generated AHK scripts

Raises

ExecutableNotFound – if AHK executable cannot be found or the specified file does not exist

async a_run_script(script_text, decode=True, blocking=True, **runkwargs)

async version of run_script

Parameters

• script_text (str) – a string containing AutoHotkey code

• decode – If True, attempt to decode the stdout of the completed process. If False, returns the completed process. Only has effect when blocking=True

• blocking – If True, script must finish before returning. If False, function returns a asyncio.process object immediately without blocking

• runkwargs – keyword arguments passed to subprocess.Popen or subprocess.run

Returns

A string of the decoded stdout if blocking and decode are True.

A bytes object of stdout if blocking is True and decode is False.

asyncio.subprocess.Process object if blocking is False.

static escape_sequence_replace(*args, **kwargs)

render_template(template_name, directives=None, blocking=True, **kwargs)

Renders a given jinja template and returns a string of script text

Parameters

• template_name – the name of the jinja template to render

• directives – additional AHK directives to add to the resulting script

• blocking – whether the template should be rendered to block (use #Persistent directive)

• kwargs – keywords passed to template rendering

Returns

An AutoHotkey script as a string

>>> from ahk import AHK
>>> ahk = AHK()
>>> ahk.render_template('keyboard/send_input.ahk', s='Hello')
'#NoEnv\n#Persistent\n\n\nSendInput Hello\n\nExitApp\n'

run_script(script_text, decode=True, blocking=True, **runkwargs)

Given an AutoHotkey script as a string, execute it

Parameters

• script_text (str) – a string containing AutoHotkey code

• decode – If True, attempt to decode the stdout of the completed process. If False, returns the completed process. Only has effect when blocking=True

• blocking – If True, script must finish before returning. If False, function returns a subprocess.Popen object immediately without blocking

• runkwargs – keyword arguments passed to subprocess.Popen or subprocess.run

Returns

A string of the decoded stdout if blocking and decode are True.

subprocess.CompletedProcess if blocking is True and decode is False.

subprocess.Popen object if blocking is False.

>>> from ahk import AHK
>>> ahk = AHK()
>>> ahk.run_script('FileAppend, Hello World, *')
'Hello World'
>>> ahk.run_script('FileAppend, Hello World, *', decode=False)
CompletedProcess(args=['C:\\pathto\\AutoHotkey.exe', '/ErrorStdOut', '*'], returncode=0, stdout=b'Hello World', stderr=b'')
>>> ahk.run_script('FileAppend, Hello World, *', blocking=False)
<subprocess.Popen at 0x18a599cde10>