`plover.system` – Steno systems#

plover.system provides a way of accessing properties of the current steno system. This module is a bit of a special one; every time the steno system is changed, Plover automatically changes the values of the data members below based on the system module that is about to be loaded. So rather than letting you access all installed systems, system itself always refers to the one that is currently active.

plover.system.setup(name: str)#

Find a system plugin named name, then change the values of the data members such that they all refer to the steno system described by that plugin.

Raises a KeyError if there is no plugin by this name.

Plugin-Defined Fields#

The fields below all refer to the values based on the active steno system. Authors of system plugins will also need to define these.

plover.system.KEYS: Tuple[str]#

A tuple of all the keys in the system. This should be given in steno order, i.e. the order they should appear on the paper tape, and the order they should be used to form strokes in.

Each key must be one of the following:

a left-hand key, which has a hyphen following the letter (e.g. S-);
a right-hand key, which has a hyphen preceding the letter (e.g. -F);
a key that does not belong to either hand and does not have a hyphen (e.g. # or *).

Key names must be one letter long, excluding the hyphen, and may consist of any letter or symbol except space, - and /.

Key names may be either lowercase or uppercase, but uppercase key names are preferred unless required to disambiguate between letters on the same side, or the official documents for the steno theory use this notation. For example, the Spanish Melani system uses casing to disambiguate between the thumb key vowels (I-, A-, -E, -O) and the final bank vowels (-i, -e, -a, -o), but the Italian Michela system uses uppercase on all left-bank keys and lowercase on all right-bank keys.

plover.system.IMPLICIT_HYPHEN_KEYS: Tuple[str]#

A tuple of all keys in KEYS that, when included in a stroke, will cause the string representation of that stroke to not have a hyphen.

Many systems require a hyphen to separate the left and right sides of a stroke in steno notation; for example, K-R in English Stenotype is interpreted as pressing the left-hand K- key and the right-hand -R key. However, if one of the keys in that stroke is also in IMPLICIT_HYPHEN_KEYS, then the hyphen is omitted, such as the A- key in KAT (K-, A-, -T).

If you want your system to simply display all the keys in order without a hyphen, and there are no keys of the same label on either side, set this field to be equivalent to KEYS.

plover.system.NUMBER_KEY: str | None#: If the system has a designated key that is used to enter numbers, this is the name of that key. On systems using the standard Stenotype layout with a number bar, for example, this will be #, but systems may choose a different number key, or none at all.

plover.system.NUMBERS: Dict[str, str]#

A dictionary mapping steno key labels to the numeric representations. This is used in conjunction with NUMBER_KEY to interpret steno strokes that include numbers. For example, if S- is mapped to 1- ({"S-": "1-"}), then pressing # and S- together is interpreted as 1-.

If the system does not support numbers, this dictionary may be left empty.

plover.system.FERAL_NUMBER_KEY: bool | None#: If True, steno notation with a number key anywhere outside the standard steno order will still be considered valid, for example 1-8# in the English Stenotype layout. False if not defined.

plover.system.UNDO_STROKE_STENO: str | None#: If the system has a designated stroke for undoing the last stroke, this is the string representation of that stroke. English Stenotype, for example, uses *, but systems may choose to not have one, since undoing can be implemented as a dictionary entry.

plover.system.SUFFIX_KEYS: Tuple[str]#: A list of singular keys that can be used as suffixes without being written into a separate stroke. For example, -G is mapped to the suffix -ing, so you can write TPAEULG (failing) in one stroke, rather than TPAEUL/-G in two strokes, without defining a separate dictionary entry.

plover.system.KEYMAPS: Dict[str, Dict[str, str | Tuple[str]]]#

A dictionary mapping steno machine names to keymaps mapping system (logical) keys, or actions, to machine (physical) keys.

You should at least define a keymap for the Keyboard machine so the system can be used out of the box by someone with a keyboard, but defining one for every built-in machine type that can physically support your system would be ideal.

The values in each keymap can be either a string, if only one machine key is mapped to each action, or a tuple of strings, if multiple keys can be used for the same action. For example, in the Gemini PR keymap below, the S1- and S2- keys on the machine can be used to write the P- steno key, and the T- key on the machine can be used to write L-.

{
  "Gemini PR": {
    "P-":  ("S1-", "S2-"),
    "L-":  "T-",
    # ...
  },
  # ...
}

When multiple keys are mapped to the same action, only one of the provided keys needs to be pressed to register as part of the stroke.

In addition to the steno keys defined in KEYS, other valid actions are no-op for all machines, and arpeggiate for Keyboard only. Arpeggiate mode for keyboards will only work if the arpeggiate action is mapped.

plover.system.ORTHOGRAPHY_RULES: List[str, str]#

A list of rules to transform spellings of words when adding suffixes based on the language’s orthography. When a suffix is defined in a dictionary, Plover will by default attach it to the end of the previous word without a spelling change, but some rules will need to be defined in languages where a change is required.

Each item in the list is a tuple consisting of two regular expression strings. The left string is the pattern of the original word and the added suffix, and the right string is what it should be replaced with. (If you are not familiar with Python’s regular expression syntax, see the official documentation for the re module.)

For example, to describe the orthography rule used to generate the word lying (lie + -ing) in English, we start by writing a regular expression to describe the pattern:

r"^lie \^ ing$"

Note the ^ in the middle, with spaces around it – this is the pattern for attaching suffixes to words.

Of course, there are other words that follow this pattern (like die and vie), so we can change this to catch the entire class of words:

r"^(.+)ie \^ ing$"

We can then write a substitution rule to replace ie with y:

r"\1ying"

So the entire rule is written as:

[
  # ...
  (r"^(.+)ie \^ ing$", r"\1ying"),
  # ...
]

plover.system.DICTIONARIES_ROOT: str | None#

The path to the default dictionaries for this system. This may be written either as a relative path, or using an asset path. Typically you would want this directory to be included in your plugin code.

If there are no dictionaries to include, set this to None.

plover.system.DEFAULT_DICTIONARIES: Tuple[str]#: A tuple of the file names of default dictionaries for this system, relative to DICTIONARIES_ROOT. If there are no dictionaries to include, set this to an empty tuple.

plover.system.ORTHOGRAPHY_RULES_ALIASES: Dict[str, str]#

A dictionary mapping a suffix to a possible variation of that suffix, if the spelling changes depending on the root word.

Plover attempts to use both suffixes when constructing the final word, and looks up the candidates in ORTHOGRAPHY_WORDS to select the final translation. See ORTHOGRAPHY_WORDS for more information.

For example, -able and -ible are variants of the same suffix, so we can define a mapping {"able": "ible"} so that writing, say, read{^able} (readable) and discern{^able} (discernible) will both resolve to their correct spellings without having to define separate strokes.

If no such ambiguity is present in the language, this may be empty.

plover.system.ORTHOGRAPHY_WORDLIST: str | None#

A file name containing an orthography dictionary for this system, primarily for disambiguating orthography substitutions, relative to DICTIONARIES_ROOT. If there is no word list, set this to None.

Each line in this word list consists of a word and a number, separated by a space. See ORTHOGRAPHY_WORDS for more information.

Computed Fields#

The fields below are automatically calculated from the values defined by plugin authors, and will not need to be defined separately.

plover.system.NAME: str#: The full name of the current system. Given the default English Stenotype system, this name would be English Stenotype. This name will match the name provided in the entry point for the system.

plover.system.IMPLICIT_HYPHENS: Set[str]#: A set containing the same items as IMPLICIT_HYPHEN_KEYS, but without the hyphens. This is calculated by Plover to be used for steno stroke normalization and should rarely be accessed instead of IMPLICIT_HYPHEN_KEYS.

plover.system.KEY_ORDER: Dict[str, int]#: A dictionary mapping steno key labels (both the keys themselves and number equivalents) to their index in the steno order defined in KEYS. The first key (# in English Stenotype) will map to 0, the second key (S-, as well as its numeric equivalent 1-) to 1, and so on.

plover.system.ORTHOGRAPHY_WORDS: Dict[str, int]#

A dictionary mapping words to their priority in the orthography dictionary (lower means higher priority).

Plover uses this dictionary to select a translation candidate when it encounters a suffix attachment. After attempting to join the root word and the suffix using dictionary lookup, ORTHOGRAPHY_RULES or a simple join, the candidate with the highest priority in the dictionary is selected as the final translation.

If ORTHOGRAPHY_WORDLIST is None, this will be empty.

plover.system – Steno systems#

Plugin-Defined Fields#

Computed Fields#

`plover.system` – Steno systems#