plover.steno_dictionary – Steno dictionary

This module handles dictionaries, which Plover uses to look up translations for input steno strokes. Plover’s steno engine uses a StenoDictionaryCollection to look up possible translations across multiple dictionaries, which can be configured by the user.

class plover.steno_dictionary.StenoDictionary

Represents a single steno dictionary.

classmethod create(resource: str) StenoDictionary

Creates a new empty steno dictionary, saved at the path resource. If resource refers to an asset path or the dictionary class is read-only (i.e. readonly is true), this call will fail.

classmethod load(resource: str) StenoDictionary

Loads a dictionary from the file at resource and returns the dictionary object. If resource refers to an asset path or the file is not writable by the user, the dictionary will be read-only.

save()

Saves the contents of the dictionary to the file it was loaded from. This may need to be called after adding dictionary entries.

enabled: bool

True if the dictionary is enabled, which means Plover can use it to look up translations, False otherwise.

readonly: bool

True if the dictionary is read-only, either because the dictionary class does not support it or the file itself is read-only. For most dictionaries this will be False.

timestamp: int

The Unix timestamp in seconds when the file was last loaded or saved.

path: str

The path to the dictionary file.

clear()

Removes all entries in the dictionary.

items() List[Tuple[Tuple[str], str]]

Returns the list of items in the dictionary.

update(*args: Iterable[Iterable[Tuple[Tuple[str], str]], **kwargs: Iterable[Tuple[Tuple[str], str]])

Adds the entries provided in args and kwargs to the dictionary. Each item in args is an iterable containing steno entries (perhaps batch-loaded from other dictionaries); each key-value pair in kwargs corresponds to one steno entry.

:type args: :type kwargs:

The following methods are available to perform various lookup functionality:

__getitem__(key: Tuple[str]) str

Returns the translation for the steno outline key, or raises a KeyError if it is not in the dictionary.

__setitem__(key: Tuple[str], value: str)

Sets the translation for the steno outline key to value. Fails if the dictionary is read-only.

__delitem__(key: Tuple[str])

Deletes the translation for the steno outline key. Fails if the dictionary is read-only.

__contains__(key: Tuple[str]) bool

Returns True if the dictionary contains a translation for the steno outline key.

get(key: Tuple[str][, fallback=None]) str | None

Returns the translation for the steno outline key, or fallback if it is not in the dictionary.

reverse: Dict[str, List[Tuple[str]]]

A dictionary mapping translations to possible steno outlines.

casereverse: Dict[str, List[Tuple[str]]]

A case-insensitive version of reverse.

reverse_lookup(value: str) List[Tuple[str]]

Returns the list of steno outlines that translate to value.

casereverse_lookup(value: str) List[Tuple[str]]

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

The dictionary provides the following interface to access the longest key in the dictionary, to be used to automatically filter out some dictionaries to speed up lookups.

longest_key: int

The number of strokes in the longest key in this dictionary.

add_longest_key_listener(callback: Function[int, any])

Adds a callback that gets called when the longest_key in a dictionary changes, such as when entries are added or removed. callback is called with the new longest key as a parameter.

remove_longest_key_listener(callback: Function[int, any])

Removes callback if it has been registered as a callback for changes to longest_key. callback is called with the new longest key as a parameter.

In addition, dictionary implementors should implement the following methods for reading and writing to dictionary files:

_load(filename: str)

Reads the dictionary at filename and loads its contents into the current dictionary. This is only called when the dictionary is first initialized so it is guaranteed to be empty.

_save(filename: str)

Writes the contents of the dictionary to filename.

class plover.steno_dictionary.StenoDictionaryCollection([dicts: List[StenoDictionary] = None])

A collection of steno dictionaries for the same steno system. Plover would typically look up outlines in these dictionaries in order until it can find a translation, but the interface also allows you to access translations from all dictionaries.

dicts: List[StenoDictionary]

A list of StenoDictionary objects, in decreasing order of priority.

set_dicts(dicts: List[StenoDictionary])

Sets the list of dictionaries to dicts.

first_writable() StenoDictionary

Returns the first dictionary that is writable, or raises KeyError if none of the dictionaries are writable.

set(key: Tuple[str], value: str[, path: str = None])

Adds a dictionary entry mapping the steno outline key to the translation value. If path is specified, the entry is added there, otherwise, it is added to the first writable dictionary.

save([path_list: List[str] = None])

Saves all of the dictionaries whose paths are in path_list. If path_list is not specified, all writable dictionaries are saved. Fails if any of the dictionaries are read-only.

__getitem__(path: str) StenoDictionary

Returns the dictionary at the specified path, or raises a KeyError if that dictionary is not part of this collection.

get(path: str) StenoDictionary | None

Returns the dictionary at the specified path, or None if it is not part of this collection.

StenoDictionaryCollection supports filters, to remove words that satisfy certain criteria from lookup results. The interface to work with them is as follows:

filters: List[Function[Tuple[str], str, bool]]

The list of filters currently active. Each filter is a function that takes a steno outline and a translation and returns a Boolean value. If a filter returns True, the corresponding entry is removed from lookup results.

add_filter(f: Function[Tuple[str], str, bool])

Adds f to the list of filters.

remove_filter(f: Function[Tuple[str], str, bool])

Removes f from the list of filters.

To look up dictionary entries, the interface is similar to StenoDictionary:

lookup(key: Tuple[str]) str | None

Returns the first available translation for the steno outline key from the highest-priority dictionary that is not filtered out by filters. If none of the dictionaries have an entry for this outline, returns None.

raw_lookup(key: Tuple[str]) str | None

Like lookup(), but returns the first translation from the highest-priority dictionary regardless of the active filters.

lookup_from_all(key: Tuple[str]) List[Tuple[str, StenoDictionary]]

Returns the list of translations for the steno outline key from all dictionaries, except those that are filtered out by :attr:filters. Each translation also contains information on which dictionary it was from.

raw_lookup_from_all(key: Tuple[str]) List[Tuple[str, StenoDictionary]]

Like lookup_from_all(), but returns all results, including the ones that have been filtered out by filters.

reverse_lookup(value: str) List[Tuple[str]]

Returns the list of steno outlines from all dictionaries that translate to value.

casereverse_lookup(value: str) List[Tuple[str]]

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

You can also access the longest key across all dictionaries:

longest_key: int

The longest key across all dictionaries.