acme.helpers.KeyHandler

module documentation

This module implements a handler for keyboard inputs.

It should run on *IX-alikes and Windows OS.

Class	`FunctionKey`	POSIX function keys.
Function	`flushInput`	Flush the input buffer of stdin. This is necessary to remove any remaining characters in the input buffer that may have been left by a previous getch() call.
Function	`getch`	getch() -> key character
Function	`loop`	Endless loop that reads single chars from the keyboard and then executes a handler function for that key (from the dictionary commands).
Function	`readline`	Read a line from the console. Catch EOF (^D) and Keyboard Interrup (^C). I that case None is returned.
Function	`stopLoop`	Stop the keyboard loop.
Function	`waitForKeypress`	Wait for a keypress for a maximum of s seconds. If no key was pressed then return None.
Type Alias	`Commands`	Mapping between characters and callback functions.
Function	`_getKey`	Read and process a keypress. If the key is a start of a sequence then process all further keys until a single sequence has been identified and full read. Then return the key as a function key enum.
Variable	`_errorInGetch`	Internal variable to indicate that getch() does not work properly.
Variable	`_functionKeys`	List of all function keys.
Variable	`_stopLoop`	Internal variable to indicate to stop the keyboard loop.
Variable	`_timeout`	Timeout for getch() in seconds.

def flushInput(): ¶

Flush the input buffer of stdin. This is necessary to remove any remaining characters in the input buffer that may have been left by a previous getch() call.

def getch() -> str | FunctionKey | None: ¶

getch() -> key character

Read a single keypress from stdin and return the resulting character. Nothing is echoed to the console. This call will block if a keypress is not already available, but will not wait for Enter to be pressed.

If the pressed key was a modifier key, nothing will be detected; if it were a special function key, it may return the first character of of an escape sequence, leaving additional characters in the buffer.

Returns
`str \| FunctionKey \| None`	A single character str or a FunctionKey enum value.

Endless loop that reads single chars from the keyboard and then executes a handler function for that key (from the dictionary commands).

Parameters
commands:`Commands`	A dictionary of `Commands` that map between input keys and callbacks.
quit:`str \| None`	If a single 'key' value is set in quit and this key is pressed, then the loop terminates.
catchKeyboardInterrupt:`bool \| None`	If catchKeyboardInterrupt is True, then this event is handled as the "^C" key, otherweise a KeyboardInterrupt event is raised.
headless:`bool \| None`	If headless is True, then operate differently. Ignore all key inputs, but handle a keyboard interrupt. If in this case the quit key is set then the loop is just interrupted. Otherwise tread the keyboard interrupt as the "^C" key. It must also be handled in commands.
ignoreException:`bool \| None`	If ignoreException is True then exceptions raised during command execution are ignore, or passed on otherwise.
catchAll:`Callable \| None`	If this attribute is set to a callback function then this callback is called in case a pressed key was not found in commands.
nextKey:`str \| None`	A simulated key-press that is interpreted when first calling the function.
postCommandHandler:`Callable \| None`	A handler callback that is called after running a command.
exceptionHandler:`Callable \| None`	A handler callback that is called in case an exception happened during the execution of a command.

def readline(prompt: str = '>') -> str: ¶

Read a line from the console. Catch EOF (^D) and Keyboard Interrup (^C). I that case None is returned.

Parameters
prompt:`str`	The prompt to display before the input.

Returns
`str`	The input line or None.

def stopLoop(): ¶

Stop the keyboard loop.

def waitForKeypress(s: float) -> str | None: ¶

Wait for a keypress for a maximum of s seconds. If no key was pressed then return None.

Parameters
s:`float`	Maximum time to wait in seconds.

Returns
`str \| None`	The key that was pressed or None.

Commands = ¶

Mapping between characters and callback functions.

Value

dict[str, Callable[[str], str | None]]

def _getKey(nextKeyCB: Callable) -> str | FunctionKey: ¶

Read and process a keypress. If the key is a start of a sequence then process all further keys until a single sequence has been identified and full read. Then return the key as a function key enum.

Parameters
nextKeyCB:`Callable`	A function the provides the next key from a keypress.

Returns
`str \| FunctionKey`	Either a string with a single non-function key, or a function key enum value.

_errorInGetch: bool = ¶

Internal variable to indicate that getch() does not work properly.

_functionKeys: tuple[FunctionKey, str] = ¶

List of all function keys.

_stopLoop: bool = ¶

Internal variable to indicate to stop the keyboard loop.

_timeout: int = ¶

Timeout for getch() in seconds.