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
. Ifresource
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. Ifresource
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 beFalse
.
- 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
andkwargs
to the dictionary. Each item inargs
is an iterable containing steno entries (perhaps batch-loaded from other dictionaries); each key-value pair inkwargs
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 aKeyError
if it is not in the dictionary.
- __setitem__(key: Tuple[str], value: str)#
Sets the translation for the steno outline
key
tovalue
. 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 outlinekey
.
- get(key: Tuple[str][, fallback=None]) str | None #
Returns the translation for the steno outline
key
, orfallback
if it is not in the dictionary.
- reverse: Dict[str, List[Tuple[str]]]#
A dictionary mapping translations to possible steno outlines.
- 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 thelongest_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 tolongest_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 translationvalue
. Ifpath
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
. Ifpath_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 byfilters
. If none of the dictionaries have an entry for this outline, returnsNone
.
- 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 byfilters
.
- 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.