pt_input_extras.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363
  1. """Augmentations to prompt_toolkit's input-parsing tables."""
  2. from __future__ import annotations
  3. import re
  4. # kitty CSI-u ORs lock-key state into the modifier parameter of every key event while a lock is
  5. # on: CapsLock=64, NumLock=128, both=192. Every fixed-modifier CSI-u (and legacy CSI-tilde /
  6. # CSI-letter) registration therefore needs lock-offset twins, or those events leak into the prompt
  7. # as literal text. The xterm modifyOtherKeys ``ESC[27;N;CP~`` encoding never carries lock bits.
  8. # See #88221, #89651.
  9. _LOCK_BIT_OFFSETS = (0, 64, 128, 192)
  10. def _lock_variants(modifier: int) -> tuple[int, ...]:
  11. """``modifier`` plus its CapsLock/NumLock/both twins."""
  12. return tuple(modifier + off for off in _LOCK_BIT_OFFSETS)
  13. def _lock_twins(modifier: int) -> tuple[int, ...]:
  14. """Only the lock twins of ``modifier`` (never the base value)."""
  15. return _lock_variants(modifier)[1:]
  16. def _clear_vt100_prefix_cache() -> None:
  17. """Drop prompt_toolkit's memoized prefix-match answers after mutating ``ANSI_SEQUENCES``.
  18. The cache is module-global and lazily filled per prefix, so parsers created before an install
  19. would keep stale ``False`` answers and misparse newly registered sequences.
  20. """
  21. try:
  22. from prompt_toolkit.input.vt100_parser import _IS_PREFIX_OF_LONGER_MATCH_CACHE
  23. _IS_PREFIX_OF_LONGER_MATCH_CACHE.clear()
  24. except Exception:
  25. pass
  26. def _install(build, *, overwrite: bool) -> int:
  27. """Install ``build(ANSI_SEQUENCES, Keys) -> {seq: key}`` into prompt_toolkit's table; return
  28. the number of entries changed (0 when prompt_toolkit is unavailable).
  29. ``overwrite=True`` replaces differing entries; ``overwrite=False`` behaves like ``setdefault``
  30. so existing/user registrations win. Clears the VT100 prefix cache when anything changed.
  31. """
  32. try:
  33. from prompt_toolkit.input.ansi_escape_sequences import ANSI_SEQUENCES
  34. from prompt_toolkit.keys import Keys
  35. except Exception:
  36. return 0
  37. changed = 0
  38. for seq, key in build(ANSI_SEQUENCES, Keys).items():
  39. if (ANSI_SEQUENCES.get(seq) != key) if overwrite else (seq not in ANSI_SEQUENCES):
  40. ANSI_SEQUENCES[seq] = key
  41. changed += 1
  42. if changed:
  43. _clear_vt100_prefix_cache()
  44. return changed
  45. def install_keypress_data_normalization() -> int:
  46. """Normalize KeyPress data for extended-key aliases that map to a single plain character
  47. (Shift+Space → ``' '``, Shift+letter → uppercase, keypad digits/operators).
  48. Root cause of #88071: ``Vt100Parser._call_handler`` builds ``KeyPress(key, match.group(0))`` — the *key*
  49. is correctly remapped by ``ANSI_SEQUENCES``, but the *data* field still carries the full raw escape text
  50. (e.g. ``"\\x1b[32;2u"``). prompt_toolkit's default character-insert binding (``self-insert``,
  51. ``basic.py``) inserts ``event.data``, so the raw CSI bytes land in the prompt buffer. For a plain space
  52. both fields are ``' '`` so it is invisible; for any mapped extended sequence the escape text is what
  53. gets inserted.
  54. """
  55. try:
  56. import prompt_toolkit.input.vt100_parser as _vt100_mod
  57. from prompt_toolkit.keys import Keys as _PtKeys
  58. except Exception:
  59. return 0
  60. _orig_call_handler = _vt100_mod.Vt100Parser._call_handler
  61. if getattr(_orig_call_handler, "_hermes_char_data_normalized", False):
  62. return 0
  63. def _patched_call_handler(self, key, insert_text):
  64. # A single plain character mapped from an extended sequence must carry the mapped
  65. # character as its data — self-insert inserts event.data and the raw CSI would leak.
  66. if (isinstance(key, str) and len(key) == 1 and not isinstance(key, _PtKeys)
  67. and isinstance(insert_text, str) and insert_text.startswith("\x1b")):
  68. insert_text = key
  69. return _orig_call_handler(self, key, insert_text)
  70. _patched_call_handler._hermes_char_data_normalized = True
  71. _vt100_mod.Vt100Parser._call_handler = _patched_call_handler
  72. return 1
  73. def _install_enter_alias(modifier: int) -> int:
  74. """Map <modifier>+Enter (Kitty CSI-u ``ESC[13;<m>u`` plus lock twins, xterm ``ESC[27;<m>;13~``
  75. / ``;13u``) to (Escape, ControlM) so the Alt+Enter newline handler fires.
  76. Stock prompt_toolkit maps the tilde form to plain ControlM (i.e. Shift+Enter == Enter, the very
  77. bug this fixes), so these keys are overwritten unconditionally.
  78. """
  79. def build(_seqs, keys):
  80. alt_enter = (keys.Escape, keys.ControlM)
  81. seqs = [f"\x1b[13;{m}u" for m in _lock_variants(modifier)] + [f"\x1b[27;{modifier};13~", f"\x1b[27;{modifier};13u"]
  82. return dict.fromkeys(seqs, alt_enter)
  83. return _install(build, overwrite=True)
  84. def install_shift_enter_alias() -> int:
  85. """Map Shift+Enter to (Escape, ControlM). macOS Terminal and stock Windows Terminal send the
  86. same byte for Enter and Shift+Enter, so nothing can be done for them here.
  87. """
  88. return _install_enter_alias(2)
  89. def install_ctrl_enter_alias() -> int:
  90. """Map Ctrl+Enter to (Escape, ControlM); otherwise Kitty/mintty/xterm over SSH insert raw CSI.
  91. Stock prompt_toolkit maps only the tilde form ``\\x1b[27;5;13~`` (to plain ``Keys.ControlM``, which this
  92. deliberately overwrites — same bug-fix rationale as install_shift_enter_alias). Without this alias,
  93. Kitty/mintty/xterm-with-modifyOtherKeys users over SSH never get a Ctrl+Enter newline — the keystroke
  94. arrives as a raw CSI sequence that falls through to the default character-insert handler. See #22379.
  95. """
  96. return _install_enter_alias(5)
  97. def install_cmd_backspace_alias() -> int:
  98. """Map Cmd+Backspace -> ControlU and Cmd+ForwardDelete -> ControlK.
  99. Kitty/modifyOtherKeys report Cmd as the super bit (8), yielding unmapped sequences that insert
  100. literally. Forward-delete is not a CSI-u codepoint, so it uses the CSI tilde form ``ESC[3;9~``.
  101. """
  102. def build(_seqs, keys):
  103. mods = [mod for base in (9, 10) for mod in _lock_variants(base)] # super / super+shift
  104. aliases = {f"\x1b[127;{mod}u": keys.ControlU for mod in mods}
  105. aliases.update({f"\x1b[3;{mod}~": keys.ControlK for mod in mods})
  106. aliases["\x1b[27;9;127~"] = keys.ControlU
  107. return aliases
  108. return _install(build, overwrite=True)
  109. # Kitty functional keys (Private Use Area codepoints) that have prompt_toolkit equivalents.
  110. # kitty emits these CSI-u encodings even in LEGACY mode, so unmapped they leak as literal text.
  111. _KITTY_FUNCTIONAL_NAMED = {
  112. 57409: ".", 57410: "/", 57411: "*", 57412: "-", 57413: "+", 57414: "ControlM", # KP ops
  113. 57415: "=", 57416: ",",
  114. 57417: "Left", 57418: "Right", 57419: "Up", 57420: "Down", 57421: "PageUp", # KP nav
  115. 57422: "PageDown", 57423: "Home", 57424: "End", 57425: "Insert", 57426: "Delete",
  116. }
  117. # No prompt_toolkit equivalent: locks/PrintScreen/Pause/Menu, F25-F35, KP_BEGIN, media keys and
  118. # bare modifier events — consumed as Ignore instead of leaking literal text.
  119. _KITTY_FUNCTIONAL_IGNORED = (*range(57358, 57364), *range(57388, 57399), 57427, *range(57428, 57455))
  120. def _kitty_functional_map(Keys) -> dict[int, object]:
  121. fm: dict[int, object] = {57399 + d: str(d) for d in range(10)} # KP_0..KP_9
  122. fm.update({cp: getattr(Keys, v) if v[0].isupper() else v for cp, v in _KITTY_FUNCTIONAL_NAMED.items()})
  123. fm.update({57376 + (n - 13): getattr(Keys, f"F{n}") for n in range(13, 25)}) # F13..F24
  124. for code in _KITTY_FUNCTIONAL_IGNORED:
  125. fm.setdefault(code, Keys.Ignore)
  126. return fm
  127. def install_modify_other_keys_aliases() -> int:
  128. """Map modifyOtherKeys-2 / Kitty CSI-u Ctrl/Alt+key sequences to their raw-byte ``Keys``.
  129. Once ``modifyOtherKeys=2`` is pushed (to distinguish Shift+Enter) the terminal re-encodes
  130. EVERY Ctrl combo as ``ESC[27;5;<cp>~``; stock prompt_toolkit maps only Ctrl+Enter, so
  131. Ctrl+A/C/D/... leak as text. Installs Ctrl/Alt/Shift letters, digits, symbols, multi-modifier
  132. combos, lock-bit variants, CSI-u Esc, modified Enter/Tab/Backspace/Space and Kitty functional
  133. keys. ``setdefault`` semantics: existing mappings (incl. the Shift/Ctrl+Enter aliases) win.
  134. (#56684, #86866, #87390).
  135. * **Ctrl+letter** (a–z): ``ESC[27;5;<codepoint>~`` and ``ESC[<codepoint>;5u`` → ``Keys.ControlA`` .. *
  136. **Ctrl+digit** (0–9): same formats → ``Keys.Control0`` .. * **Ctrl+symbol** (``[`` ``\\`` ``]`` ``^``
  137. ``_`` `` `` ``@``): same formats → the same ``Keys`` value the raw control byte maps to. *
  138. **Alt+letter** (a–z, A–Z): ``ESC[27;3;<codepoint>~`` and ``ESC[<codepoint>;3u`` → ``(Keys.Escape,
  139. <letter>)`` — matching how prompt_toolkit handles a bare ``ESC`` followed by a character. *
  140. **Shift+letter** (a–z): → the uppercase character. * **Shift+symbol** (tilde form only): ``ESC[27;2;<cp>~``
  141. → ``chr(cp)`` for printable ASCII — xterm and Ghostty put the produced character in that codepoint (#114242).
  142. * **Multi-modifier letters** (Shift+Alt=4,
  143. Ctrl+Shift=6, Ctrl+Alt=7, Ctrl+Alt+Shift=8): normalized onto the same targets — Ctrl-bearing combos
  144. behave as the Ctrl key (Alt adds an ``Escape`` prefix), matching how dte/kakoune normalize these
  145. protocols. * **Lock-bit variants**: every CSI-u mapping above is also installed with the CapsLock (64)
  146. and NumLock (128) bits ORed into the modifier parameter — kitty/ghostty include them while a lock is on,
  147. and without the variants every key combo dies with the lock enabled (``ESC[99;133u`` instead of
  148. ``ESC[99;5u``, #89651). * **Esc key**: ``ESC[27u`` / ``ESC[27;<mod>u`` (Kitty disambiguate mode reports
  149. Esc this way, #56684) → ``Keys.Escape``. * **Modified Enter/Tab/Backspace/Space**: Alt+Enter → the
  150. Alt+Enter newline tuple; Shift+Tab → ``BackTab``; Ctrl+Tab → plain Tab; Ctrl/Alt+Backspace → ``(Escape,
  151. ControlH)`` (backward-kill-word, matching the Ink TUI and Desktop, #78285); Shift+Backspace → plain
  152. backspace; Shift+Space → a plain space (#86866); Alt+Space → ``(Escape, " ")``. * **Kitty functional
  153. keys** (Private Use Area codepoints): keypad keys → their non-keypad equivalents (KP_ENTER → Enter, KP_4
  154. → '4', KP_LEFT → Left, …); F13–F24 → ``Keys.F13``..``F24``; lock/media/ modifier-event keys →
  155. ``Keys.Ignore`` so they are consumed instead of leaking as literal text. kitty emits these CSI-u forms
  156. even in legacy mode for keys that have no legacy encoding.
  157. """
  158. return _install(_modify_other_keys_aliases, overwrite=False)
  159. def _modify_other_keys_aliases(ANSI_SEQUENCES: dict, Keys) -> dict[str, object]:
  160. # Collected first-writer-wins (matching setdefault order), installed once at the end.
  161. aliases: dict[str, object] = {}
  162. _put = aliases.setdefault
  163. # Kitty CSI-u encodes CapsLock/NumLock state as extra modifier bits (caps=64, num=128) ORed into the
  164. # parameter: with NumLock on, Ctrl+C arrives as ESC[99;133u (5 + 128) instead of ESC[99;5u. Terminals
  165. # that report these bits (kitty, ghostty) break every key combo while a lock is on (#89651) unless the
  166. # lock variants are mapped too. The xterm modifyOtherKeys encoding never carries the lock bits, so only
  167. # the CSI-u form needs them.
  168. def _install_paired(modifier: int, mapping: dict) -> None:
  169. """Both modifyOtherKeys (ESC[27;N;CP~, never for mod 1) and CSI-u (ESC[CP;Nu + lock twins)."""
  170. for codepoint, key_val in mapping.items():
  171. if modifier != 1:
  172. _put(f"\x1b[27;{modifier};{codepoint}~", key_val)
  173. for mod in _lock_variants(modifier):
  174. _put(f"\x1b[{codepoint};{mod}u", key_val)
  175. # Ctrl+<ch>: the extended sequence maps to whatever Keys value the raw control byte
  176. # chr(ord(ch) & 0x1f) already maps to, so existing bindings fire identically. Covers a-z and
  177. # the control-producing symbols @ [ \ ] ^ _ and Space (\x00 -> ControlAt).
  178. letters = range(ord('a'), ord('z') + 1)
  179. ctrl_key_map: dict[int, object] = {
  180. cp: key for cp in (*letters, 64, 91, 92, 93, 94, 95, 32)
  181. if (key := ANSI_SEQUENCES.get(chr(cp & 0x1F))) is not None
  182. }
  183. # Ctrl+digit has no useful raw byte (chr(ord('0') & 0x1F) is ControlP), so map directly.
  184. ctrl_key_map.update({ord('0') + d: getattr(Keys, f"Control{d}") for d in range(10)})
  185. _install_paired(5, ctrl_key_map)
  186. # Letter combos. Alt+a -> (Escape, 'a') like bare Alt. Shift+a -> 'A' (safe on every Latin
  187. # layout). Kitty CSI-u reports the UNSHIFTED codepoint, modifyOtherKeys emitters the shifted
  188. # one — map both. Shift+symbol is mapped only in the tilde form below: the CSI-u codepoint is
  189. # unshifted (ESC[47;2u is Shift+/ on US, '?' — layout-specific), so there leaking beats wrong
  190. # input. Ctrl-bearing combos normalize onto the Ctrl key (Alt adds an Escape prefix),
  191. # Shift+Alt onto (Escape, UPPER) — the same normalization dte/kakoune apply.
  192. for ch in letters:
  193. upper_char = chr(ch - 32)
  194. ctrl_key = ctrl_key_map.get(ch)
  195. _install_paired(3, {ch: (Keys.Escape, chr(ch)), ch - 32: (Keys.Escape, upper_char)})
  196. for cp in (ch, ch - 32):
  197. _install_paired(2, {cp: upper_char})
  198. _install_paired(4, {cp: (Keys.Escape, upper_char)})
  199. if ctrl_key is not None:
  200. _install_paired(6, {cp: ctrl_key})
  201. for modifier in (7, 8): # Ctrl+Alt and Ctrl+Alt+Shift — same normalization
  202. _install_paired(modifier, {cp: (Keys.Escape, ctrl_key)})
  203. # Shift+printable ASCII under modifyOtherKeys (tilde form only, never CSI-u): xterm's own key
  204. # table sends Shift+[ as ESC[27;2;123~ — the codepoint is the PRODUCED character '{', already
  205. # resolved through the user's keymap — and Ghostty follows that spec (#114242, #102683). So
  206. # ESC[27;2;<cp>~ -> chr(cp) is layout-safe on every tilde-form emitter; the
  207. # unshifted-codepoint concern belongs to Kitty CSI-u, which never uses this spelling.
  208. # Existing entries (Shift+Enter \x1b[27;2;13~, Shift+Tab, Shift+Space) win via setdefault.
  209. # xterm/Ghostty only use this encoding for produced codepoints 0x40-0x7E (`IsControlInput`);
  210. # '!' '#' '$' still arrive as plain text, so the 33-63 rows are inert there but harmless.
  211. # Super+<printable> (modifier 9, Super+Shift 10) follows the same produced-codepoint rule:
  212. # Ghostty sends Super+o as ESC[27;9;111~ (#114242). The CLI has no Super bindings, so type
  213. # the character — what the terminal sends without modifyOtherKeys and what the Ink TUI does.
  214. for cp in range(33, 127):
  215. for modifier in (2, 9, 10):
  216. _put(f"\x1b[27;{modifier};{cp}~", chr(cp))
  217. # The Esc KEY under Kitty disambiguate mode: ESC[27u (+ modifiers 1-16 incl. super 9+, and
  218. # lock twins of the modifier-less form, which is how a lone Esc arrives with a lock on).
  219. _put("\x1b[27u", Keys.Escape)
  220. for mod in (mod for m in range(1, 17) for mod in _lock_variants(m)):
  221. _put(f"\x1b[27;{mod}u", Keys.Escape)
  222. # Modified Enter/Tab/Backspace/Space (Shift/Ctrl+Enter are owned by the enter aliases, which run
  223. # first and win). Modifier 1 = unmodified keys kitty CSI-u-encodes on their own when a lock bit
  224. # is set (plain Backspace arrives as ESC[127;129u rather than \x7f).
  225. alt_backspace = (Keys.Escape, Keys.ControlH) # backward-kill-word, matching Ink TUI + Desktop
  226. _install_paired(2, {9: Keys.BackTab, 127: Keys.ControlH, 32: " "})
  227. _install_paired(3, {13: (Keys.Escape, Keys.ControlM), 127: alt_backspace, 32: (Keys.Escape, " ")})
  228. _install_paired(5, {9: Keys.ControlI, 127: alt_backspace}) # Ctrl+Tab degrades to Tab
  229. _install_paired(1, {9: Keys.ControlI, 13: Keys.ControlM, 32: " ", 127: Keys.ControlH})
  230. # Lock twins for the legacy CSI-letter / CSI-tilde forms kitty keeps using under the
  231. # disambiguate push (Down with NumLock on = ESC[1;129B; Alt+Left = ESC[1;131D). Derived from
  232. # whatever the table already maps for the base modifier, stock entries included.
  233. for m in range(1, 17):
  234. legacy = [(f"\x1b[1;{m}{t}" if m > 1 else f"\x1b[{t}", f"\x1b[1;{{mod}}{t}", f"\x1bO{t}") for t in "ABCDFHPQRS"]
  235. legacy += [(f"\x1b[{n};{m}~" if m > 1 else f"\x1b[{n}~", f"\x1b[{n};{{mod}}~", None) for n in range(1, 9)]
  236. for base_seq, twin_fmt, ss3_seq in legacy: # CSI-letter nav/F1-F4, then CSI-tilde nav keys
  237. key = ANSI_SEQUENCES.get(base_seq)
  238. if key is None and m == 1 and ss3_seq:
  239. key = ANSI_SEQUENCES.get(ss3_seq) # plain F1-F4 live as SS3 forms
  240. for mod in _lock_twins(m) if key is not None else ():
  241. _put(twin_fmt.format(mod=mod), key)
  242. keypad_twins = {
  243. 57414: "\x1b[13;{mod}u", # Enter
  244. **{code: "\x1b[1;{mod}" + suffix for code, suffix in
  245. zip((57417, 57418, 57419, 57420, 57423, 57424), "DCABHF")},
  246. **{code: f"\x1b[{number};{{mod}}~" for code, number in
  247. ((57421, 5), (57422, 6), (57425, 2), (57426, 3))},
  248. }
  249. for code, key_val in _kitty_functional_map(Keys).items():
  250. _put(f"\x1b[{code}u", key_val)
  251. for mod in _lock_twins(1): # with a lock on these arrive as ESC[<code>;129u etc.
  252. _put(f"\x1b[{code};{mod}u", key_val)
  253. twin = keypad_twins.get(code)
  254. if isinstance(key_val, str) and not isinstance(key_val, Keys) and len(key_val) == 1:
  255. twin = f"\x1b[{ord(key_val)};{{mod}}u"
  256. # Modified keypad keys inherit existing non-keypad semantics, not new bindings.
  257. # Some twins (Alt+Enter, lock variants) are still in this builder's pending aliases.
  258. for modifier in range(2, 9):
  259. for mod in _lock_variants(modifier):
  260. equivalent = None
  261. if twin is not None:
  262. source = twin.format(mod=mod)
  263. equivalent = ANSI_SEQUENCES.get(source, aliases.get(source))
  264. elif key_val is Keys.Ignore:
  265. equivalent = Keys.Ignore
  266. if equivalent is not None:
  267. _put(f"\x1b[{code};{mod}u", equivalent)
  268. return aliases
  269. # Replies to the startup image probe (``agent.terminal_image.probe_vscode_images``): XTSMGRAPHICS
  270. # ``ESC[?1;<status>;<value>S`` and DA1 ``ESC[?<params>c``. No key sends either. One that lands
  271. # after the probe stopped reading would otherwise be typed into the prompt.
  272. _PROBE_REPLY_RE = re.compile(r"\x1b\[\?[\d;]*[Sc]\Z")
  273. _PROBE_REPLY_PREFIX_RE = re.compile(r"\x1b\[\?[\d;]*\Z")
  274. def _install_probe_reply_filter() -> int:
  275. """Parse a probe reply as one ``Keys.Ignore``, whenever it arrives. ``ANSI_SEQUENCES`` holds
  276. fixed strings only, so this wraps the parser's matcher the way prompt_toolkit special-cases CPR."""
  277. import prompt_toolkit.input.vt100_parser as vt100
  278. from prompt_toolkit.keys import Keys
  279. get_match = vt100.Vt100Parser._get_match
  280. if getattr(get_match, "_hermes_probe_replies", False):
  281. return 0
  282. is_prefix = vt100._IsPrefixOfLongerMatchCache.__missing__
  283. def _get_match(self, prefix):
  284. return Keys.Ignore if _PROBE_REPLY_RE.match(prefix) else get_match(self, prefix)
  285. def _missing(self, prefix):
  286. if _PROBE_REPLY_PREFIX_RE.match(prefix):
  287. self[prefix] = True
  288. return True
  289. return is_prefix(self, prefix)
  290. _get_match._hermes_probe_replies = True
  291. vt100.Vt100Parser._get_match = _get_match
  292. vt100._IsPrefixOfLongerMatchCache.__missing__ = _missing
  293. _clear_vt100_prefix_cache()
  294. return 1
  295. def install_ignored_terminal_sequences() -> int:
  296. """Parse terminal reports nobody typed as ``Keys.Ignore``: focus reports ``ESC[I`` / ``ESC[O``
  297. (Ghostty, iTerm2, some xterms) and the image probe's replies.
  298. Parser-level handling beats post-hoc regex stripping because the bytes never reach the buffer.
  299. ``setdefault`` lets user/downstream registrations win.
  300. """
  301. focus = _install(lambda _seqs, keys: {"\x1b[I": keys.Ignore, "\x1b[O": keys.Ignore}, overwrite=False)
  302. return focus + _install_probe_reply_filter()