keyboard.py

Sub-module providing ‘keyboard awareness’.

class Keystroke(ucs='', code=None, name=None)

A unicode-derived class for describing a single keystroke.

A class instance describes a single keystroke received on input, which may contain multiple characters as a multibyte sequence, which is indicated by properties is_sequence returning True.

When the string is a known sequence, code matches terminal class attributes for comparison, such as term.KEY_LEFT.

The string-name of the sequence, such as u'KEY_LEFT' is accessed by property name, and is used by the __repr__() method to display a human-readable form of the Keystroke this class instance represents. It may otherwise by joined, split, or evaluated just as as any other unicode string.

Class constructor.

static __new__(cls, ucs='', code=None, name=None)

Class constructor.

property is_sequence

Whether the value represents a multibyte sequence (bool).

property name

String-name of key sequence, such as u'KEY_LEFT' (str).

property code

Integer keycode value of multibyte sequence (int).

get_keyboard_codes()

Return mapping of keycode integer values paired by their curses key-name.

Return type:

dict

Returns:

Dictionary of (code, name) pairs for curses keyboard constant values and their mnemonic name. Such as key 260, with the value of its identity, u'KEY_LEFT'.

These keys are derived from the attributes by the same of the curses module, with the following exceptions:

• KEY_DELETE in place of KEY_DC

• KEY_INSERT in place of KEY_IC

• KEY_PGUP in place of KEY_PPAGE

• KEY_PGDOWN in place of KEY_NPAGE

• KEY_ESCAPE in place of KEY_EXIT

• KEY_SUP in place of KEY_SR

• KEY_SDOWN in place of KEY_SF

This function is the inverse of get_curses_keycodes(). With the given override “mixins” listed above, the keycode for the delete key will map to our imaginary KEY_DELETE mnemonic, effectively erasing the phrase KEY_DC from our code vocabulary for anyone that wishes to use the return value to determine the key-name by keycode.

get_keyboard_sequences(term)

Return mapping of keyboard sequences paired by keycodes.

Parameters:

term (blessed.Terminal) – Terminal instance.

Returns:

mapping of keyboard unicode sequences paired by keycodes as integer. This is used as the argument mapper to the supporting function resolve_sequence().

Return type:

OrderedDict

Initialize and return a keyboard map and sequence lookup table, (sequence, keycode) from Terminal instance term, where sequence is a multibyte input sequence of unicode characters, such as u'\x1b[D', and keycode is an integer value, matching curses constant such as term.KEY_LEFT.

The return value is an OrderedDict instance, with their keys sorted longest-first.

_alternative_left_right(term)

Determine and return mapping of left and right arrow keys sequences.

Parameters:

term (blessed.Terminal) – Terminal instance.

Return type:

dict

Returns:

Dictionary of sequences term._cuf1, and term._cub1, valued as KEY_RIGHT, KEY_LEFT (when appropriate).

This function supports get_terminal_sequences() to discover the preferred input sequence for the left and right application keys.

It is necessary to check the value of these sequences to ensure we do not use u' ' and u'\b' for KEY_RIGHT and KEY_LEFT, preferring their true application key sequence, instead.

DEFAULT_SEQUENCE_MIXIN = (('\n', 343), ('\r', 343), ('\x08', 263), ('\t', 512), ('\x1b', 361), ('\x7f', 263), ('\x1b[A', 259), ('\x1b[B', 258), ('\x1b[C', 261), ('\x1b[D', 260), ('\x1b[1;2A', 337), ('\x1b[1;2B', 336), ('\x1b[1;2C', 402), ('\x1b[1;2D', 393), ('\x1b[F', 360), ('\x1b[H', 262), ('\x1b[K', 360), ('\x1b[U', 338), ('\x1b[V', 339), ('\x1bOM', 343), ('\x1bOj', 513), ('\x1bOk', 514), ('\x1bOl', 515), ('\x1bOm', 516), ('\x1bOn', 517), ('\x1bOo', 518), ('\x1bOX', 519), ('\x1bOp', 520), ('\x1bOq', 521), ('\x1bOr', 522), ('\x1bOs', 523), ('\x1bOt', 524), ('\x1bOu', 525), ('\x1bOv', 526), ('\x1bOw', 527), ('\x1bOx', 528), ('\x1bOy', 529), ('\x1b[1~', 362), ('\x1b[2~', 331), ('\x1b[3~', 330), ('\x1b[4~', 385), ('\x1b[5~', 339), ('\x1b[6~', 338), ('\x1b[7~', 262), ('\x1b[8~', 360), ('\x1b[OA', 259), ('\x1b[OB', 258), ('\x1b[OC', 261), ('\x1b[OD', 260), ('\x1b[OF', 360), ('\x1b[OH', 262), ('\x1bOP', 265), ('\x1bOQ', 266), ('\x1bOR', 267), ('\x1bOS', 268))

In a perfect world, terminal emulators would always send exactly what the terminfo(5) capability database plans for them, accordingly by the value of the TERM name they declare.

But this isn’t a perfect world. Many vt220-derived terminals, such as those declaring ‘xterm’, will continue to send vt220 codes instead of their native-declared codes, for backwards-compatibility.

This goes for many: rxvt, putty, iTerm.

These “mixins” are used for all terminals, regardless of their type.

Furthermore, curses does not provide sequences sent by the keypad, at least, it does not provide a way to distinguish between keypad 0 and numeric 0.

CURSES_KEYCODE_OVERRIDE_MIXIN = (('KEY_DELETE', 330), ('KEY_INSERT', 331), ('KEY_PGUP', 339), ('KEY_PGDOWN', 338), ('KEY_ESCAPE', 361), ('KEY_SUP', 337), ('KEY_SDOWN', 336), ('KEY_UP_LEFT', 348), ('KEY_UP_RIGHT', 349), ('KEY_CENTER', 350), ('KEY_BEGIN', 354))

Override mixins for a few curses constants with easier mnemonics: there may only be a 1:1 mapping when only a keycode (int) is given, where these phrases are preferred.

_CURSES_KEYCODE_ADDINS = ('TAB', 'KP_MULTIPLY', 'KP_ADD', 'KP_SEPARATOR', 'KP_SUBTRACT', 'KP_DECIMAL', 'KP_DIVIDE', 'KP_EQUAL', 'KP_0', 'KP_1', 'KP_2', 'KP_3', 'KP_4', 'KP_5', 'KP_6', 'KP_7', 'KP_8', 'KP_9')

Though we may determine keynames and codes for keyboard input that generate multibyte sequences, it is also especially useful to aliases a few basic ASCII characters such as KEY_TAB instead of u'\t' for uniformity.

Furthermore, many key-names for application keys enabled only by context manager keypad() are surprisingly absent. We inject them here directly into the curses module.