keyboard.py — Blessed 1.17.7 documentation

# keyboard.py

Sub-module providing ‘keyboard awareness’.

class `Keystroke`

  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[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.