plover.engine – Steno engine

The steno engine is the core of Plover; it handles communication between the machine and the translation and formatting subsystems, and manages configuration and dictionaries.

class plover.engine.StenoEngine(config: Any, controller: Any, keyboard_emulation: Any)

config

A dictionary containing configuration options.

Type:

Dict[str, Any]

controller

An instance of Controller for managing commands sent to this Plover instance. This is provided during startup.

Type:

plover.oslayer.controller.Controller

keyboard_emulation

An instance of KeyboardEmulation provided during startup.

Type:

plover.oslayer.keyboardcontrol.KeyboardEmulation

HOOKS

A list of all the possible engine hooks. See Engine Hooks below for a list of valid hooks.

Type:

List[str]

machine_state

The connection state of the current machine. One of stopped, initializing, connected or disconnected.

Type:

str

output

True if steno output is enabled, False otherwise.

Type:

bool

_config

A Config object containing the engine’s configuration.

Type:

plover.config.Config

translator_state

A _State object containing the current state of the translator.

Type:

plover.translation._State

starting_stroke_state

A StartingStrokeState representing the initial state of the formatter.

Type:

StartingStrokeState

dictionaries

A StenoDictionaryCollection of all the dictionaries Plover has loaded for the current system. This includes disabled dictionaries and dictionaries that failed to load.

Type:

plover.steno_dictionary.StenoDictionaryCollection

_in_engine_thread() → bool

Returns whether we are currently in the same thread that the engine is running on.

This is useful because event listeners for machines and others are run on separate threads, and we want to be able to run engine events on the same thread as the main engine.

start() → None

Starts the steno engine.

quit(code: int = 0) → None

Quits the steno engine, ensuring that all pending tasks are completed before exiting.

restart() → None

Quits and restarts the steno engine, ensuring that all pending tasks are completed.

run() → None

Starts the steno engine, translating any strokes that are input.

join() → int

Joins any sub-threads if necessary and returns an exit code.

load_config() → bool

Loads the Plover configuration file and returns True if it was loaded successfully, False if not.

reset_machine() → None

Resets the machine state and Plover’s connection with the machine, if necessary, and loads all the configuration and dictionaries.

_send_engine_command(command: str) → None

Runs the specified Plover command, which can be either a built-in command like set_config or one from an external plugin.

command is a string containing the command and its argument (if any), separated by a colon. For example, lookup sends the lookup command (the same as stroking {PLOVER:LOOKUP}), and run_shell:foo sends the run_shell command with the argument foo.

toggle_output()

Toggles steno mode.

See output to get the current state, or set_output() to set the state to a specific value.

set_output(enabled: bool) → None

Enables or disables steno mode.

Set enabled to True to enable steno mode, or False to disable it.

__getitem__(setting: str) → Any

Returns the value of the configuration property setting.

__setitem__(setting: str, value: Any) → None

Sets the configuration property setting to value.

get_suggestions(translation: str)

Returns a list of suggestions for the specified translation.

clear_translator_state(undo: bool = False) → None

Resets the translator to an empty state, as if Plover had just started up, clearing the entire translation stack.

If undo is True, this also reverts all previous translations on the stack (which could include a lot of backspaces).

hook_connect(hook: str, callback: Callable[[...], Any]) → None

Adds callback to the list of handlers that are called when the hook hook gets triggered. Raises a KeyError if hook is not in HOOKS.

The expected signature of the callback is depends on the hook; see Engine Hooks for more information.

hook_disconnect(hook: str, callback: Callable[[...], Any]) → None

Removes callback from the list of handlers that are called when the hook hook is triggered. Raises a KeyError if hook is not in HOOKS, and a ValueError if callback was never added as a handler in the first place.

The following methods simply provide a way to access the underlying StenoDictionaryCollection. See the documentation there for more complete information.

lookup(translation: Tuple[str, ...]) → str

Returns the first translation for the steno outline translation using all the filters.

raw_lookup(translation: Tuple[str, ...]) → str

Like lookup(), but without any of the filters.

lookup_from_all(translation: Tuple[str, ...])

Returns all translations for the steno outline translation using all the filters.

raw_lookup_from_all(translation: Tuple[str, ...])

Like lookup_from_all(), but without any of the filters.

reverse_lookup(translation: str)

Returns the list of steno outlines that translate to translation.

casereverse_lookup(translation: str)

Like reverse_lookup(), but performs a case-insensitive lookup.

add_dictionary_filter(dictionary_filter: Callable[[Tuple[str, ...], str], bool]) → None

Adds dictionary_filter to the list of dictionary filters.

See StenoDictionaryCollection.filters for more information.

remove_dictionary_filter(dictionary_filter: Callable[[Tuple[str, ...], str], bool]) → None

Removes dictionary_filter from the list of dictionary filters.

add_translation(strokes: Tuple[str, ...], translation: str, dictionary_path: str | None = None) → None

Adds a steno entry mapping the steno outline strokes to translation in the dictionary at dictionary_path, if specified, or the first writable dictionary.

class plover.engine.StartingStrokeState(attach=False, capitalize=False, space_char=' ', space_placement=None)

An object representing the starting state of the formatter before any strokes are input.

attach

Whether to delete the space before the translation when the initial stroke is translated.

Type:

bool

capitalize

Whether to capitalize the translation when the initial stroke is translated.

Type:

bool

space_char

The character to use as a space.

Type:

str

space_placement

The space placement to use for this state. One of Before Output or After Output. If None, the current engine configuration is used.

Type:

Optional[str]

class plover.engine.MachineParams(type, options, keymap)

An object representing the current state of the machine.

type

The name of the machine. This is the same as the name of the plugin that provides the machine’s functionality. Keyboard by default.

Type:

str

options

A dictionary of machine specific options. See plover.config for more information.

Type:

Dict[str, Any]

keymap

A Keymap mapping the current system to this machine.

Type:

plover.machine.keymap.Keymap

class plover.engine.ErroredDictionary(path: str, exception: Any)

A placeholder class for a dictionary that failed to load.

This is a subclass of StenoDictionary.

path

The path to the dictionary file.

Type:

str

exception

The exception that caused the dictionary loading to fail.

Type:

Any

Engine Hooks

Plover uses engine hooks to allow plugins to listen to engine events. By calling engine.hook_connect and passing the name of one of the hooks below and a function, you can write handlers that are called when Plover hooks get triggered.

hook stroked(stroke: plover.steno.Stroke)

The user just sent a stroke.

hook translated(old, new)

hook machine_state_changed(machine_type: str, machine_state: str)

Either the machine type was changed by the user, or the connection state of the machine changed. machine_type is the name of the machine (e.g. Gemini PR), and machine_state is one of stopped, initializing, connected or disconnected.

hook output_changed(enabled: bool)

The user requested to either enable or disable steno output. enabled is True if output is enabled, False otherwise.

hook config_changed(config: Dict[str, Any])

The configuration was changed, or it was loaded for the first time. config is a dictionary containing only the changed fields. Call the hook function with the StenoEngine.config to initialize your plugin based on the full configuration.

hook dictionaries_loaded(dictionaries: plover.steno_dictionary.StenoDictionaryCollection)

The dictionaries were loaded, either when Plover starts up or the system is changed or when the engine is reset.

hook send_string(s: str)

Plover just sent the string s over keyboard output.

hook send_backspaces(b: int)

Plover just sent backspaces over keyboard output. b is the number of backspaces sent.

hook send_key_combination(c: str)

Plover just sent a keyboard combination over keyboard output. c is a string representing the keyboard combination, for example Alt_L(Tab).

hook add_translation()

The Add Translation command was activated – open the Add Translation tool.

hook focus()

The Show command was activated – reopen Plover’s main window and bring it to the front.

hook configure()

The Configure command was activated – open the configuration window.

hook lookup()

The Lookup command was activated – open the Lookup tool.

hook suggestions()

The Suggestions command was activated – open the Suggestions tool.

hook quit()

The Quit command was activated – wrap up any pending tasks and quit Plover.