cleanup FX and manual checklist

Author: Carreau

docs/pages/advanced_topics/kitty_keyboard_protocol.rst

@@ -57,16 +57,20 @@ Input
 ``src/prompt_toolkit/input/kitty_keyboard.py`` owns the ``CSI u``
 decoder. Covered:
 
-- Functional keys from the Kitty spec: :kbd:`enter`, :kbd:`tab`,
-  :kbd:`escape`, :kbd:`backspace`, :kbd:`f1`–:kbd:`f12`. Mapped to the
-  nearest existing ``Keys`` value with Shift / Ctrl / Ctrl-Shift
-  promotion where an enum exists. Arrow keys and the navigation block
-  (:kbd:`home` / :kbd:`end` / :kbd:`pageup` / :kbd:`pagedown` /
-  :kbd:`insert` / :kbd:`delete`) are **not** handled here — under
-  flag 1 the Kitty spec keeps them in their legacy
-  ``CSI <n> ~`` / ``CSI <letter>`` / ``SS3 <letter>`` encoding even
-  when modified, so they continue to travel through
-  ``ANSI_SEQUENCES`` (which already has the full modifier matrix).
+- The four functional keys whose single-byte legacy encoding collides
+  with a ``Ctrl+letter``: :kbd:`enter` (=``\r``=:kbd:`c-m`),
+  :kbd:`tab` (=``\t``=:kbd:`c-i`), :kbd:`escape`
+  (=``\x1b``=:kbd:`c-[`), :kbd:`backspace` (=``\x7f``/:kbd:`c-h`).
+  These are the only keys flag 1 actually re-encodes as ``CSI u``.
+  Mapped to the nearest existing ``Keys`` value with Shift / Ctrl /
+  Ctrl-Shift promotion where an enum exists. Arrow keys, the
+  navigation block (:kbd:`home` / :kbd:`end` / :kbd:`pageup` /
+  :kbd:`pagedown` / :kbd:`insert` / :kbd:`delete`), and
+  :kbd:`f1`–:kbd:`f12` are **not** handled here — under flag 1 the
+  Kitty spec keeps them in their legacy ``CSI <n> ~`` /
+  ``CSI <letter>`` / ``SS3 <letter>`` encoding even when modified, so
+  they continue to travel through ``ANSI_SEQUENCES`` (which already
+  has the full modifier matrix).
 - Printable Unicode keys with Ctrl (mapped to ``Keys.ControlX``) and
   Ctrl+Shift digits (mapped to ``Keys.ControlShift1`` …).
 - Alt as a meta prefix: emitted as ``(Keys.Escape, base_key)`` to match

examples/prompts/kitty-key-checklist.py

@@ -12,9 +12,17 @@
 The bottom toolbar lists every such gesture. Press one and its row
 turns green. On terminals without the protocol, rows stay grey —
 that's the expected fallback, not a bug. Press plain Enter to exit.
+
+Pass ``--no-kitty`` to suppress the protocol push so you can verify
+that, without it, the gestures are indistinguishable from their legacy
+equivalents and the rows stay grey — useful for reproducing how the
+prompt behaves on a terminal that doesn't implement the protocol,
+from inside one that does.
 """
 
-from prompt_toolkit import prompt
+import argparse
+
+from prompt_toolkit import PromptSession
 from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.styles import Style
 
@@ -33,10 +41,28 @@
 
 
 def main():
+    parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
+    parser.add_argument(
+        "--no-kitty",
+        action="store_true",
+        help=(
+            "Don't push the Kitty keyboard protocol. Modified keys then "
+            "arrive as their legacy single-byte equivalents and the bindings "
+            "in this example never fire — useful to verify the non-Kitty "
+            "fallback from a Kitty-capable terminal."
+        ),
+    )
+    args = parser.parse_args()
+
     pressed: set[str] = set()
 
     def toolbar():
-        lines = [("", "Kitty-only gestures — press each to turn it green:\n")]
+        header = (
+            "Kitty protocol DISABLED (--no-kitty) — rows stay grey:\n"
+            if args.no_kitty
+            else "Kitty-only gestures — press each to turn it green:\n"
+        )
+        lines = [("", header)]
         for binding, label in KITTY_KEYS:
             if binding in pressed:
                 lines.append(("class:done", f"  [x] {label}\n"))
@@ -70,14 +96,32 @@ def handler(event):
         }
     )
 
-    prompt(
+    session = PromptSession(
         "> ",
         bottom_toolbar=toolbar,
         key_bindings=bindings,
         style=style,
         refresh_interval=0.5,
     )
 
+    if args.no_kitty:
+        # Short-circuit the renderer's one-shot push/query block by
+        # flipping its "already pushed" flag so the conditional at the
+        # top of Renderer.render() skips both the push and the probe.
+        # We hook `Application.on_reset` rather than setting the flag
+        # directly — `Application.run()` calls `renderer.reset()`
+        # first, which would clear a pre-set flag; `on_reset` fires
+        # *after* that reset and before the first render, which is the
+        # window we need. Reaching into the private attribute is fine
+        # for a demo; there is no public "disable kitty" knob on
+        # Application/Renderer today.
+        def _suppress_kitty(_app):
+            session.app.renderer._kitty_keyboard_pushed = True
+
+        session.app.on_reset += _suppress_kitty
+
+    session.prompt()
+
 
 if __name__ == "__main__":
     main()

src/prompt_toolkit/input/kitty_keyboard.py

@@ -61,32 +61,27 @@
 _IGNORED_MODS = _CAPSLOCK | _NUMLOCK
 
 
-# Functional-key codes from the Kitty spec, mapped to the nearest
-# existing prompt_toolkit `Keys` value. Only keys likely to appear under
-# `disambiguate` (flag 1) are included.
+# Functional-key codes from the Kitty spec that can reach this decoder
+# under flag 1 ("disambiguate escape codes"), mapped to the nearest
+# existing prompt_toolkit `Keys` value. Everything else listed in the
+# spec's functional-key table keeps its legacy encoding under flag 1
+# and travels through `ANSI_SEQUENCES` instead:
+#
+# - Arrow keys and the navigation block (Home / End / PageUp /
+#   PageDown / Insert / Delete): legacy `CSI <letter>` / `CSI <n>~`.
+# - F1-F12: legacy `SS3 <letter>` (F1-F4) / `CSI <n>~` (F5-F12).
+# - CapsLock / ScrollLock / NumLock / PrintScreen / Pause / Menu: no
+#   legacy encoding and no matching `Keys` enum, so out of scope here.
+#
+# What remains are the four keys whose single-byte legacy encoding
+# collides with a Ctrl+letter (Enter=\r=C-m, Tab=\t=C-i, Esc=\x1b=C-[,
+# Backspace=\x7f/C-h) — those are the only gestures flag 1 actually
+# re-encodes as `CSI u`.
 _FUNCTIONAL: dict[int, Keys] = {
     13: Keys.ControlM,  # Enter
     9: Keys.ControlI,  # Tab
     27: Keys.Escape,
     127: Keys.ControlH,  # Backspace
-    # 57358 = CapsLock,
-    # 57359 = ScrollLock,
-    # 57360 = NumLock,
-    # 57361 = PrintScreen,
-    # 57362 = Pause,
-    # 57363 = Menu — no corresponding `Keys` enum, so left out of the table.
-    57364: Keys.F1,
-    57365: Keys.F2,
-    57366: Keys.F3,
-    57367: Keys.F4,
-    57368: Keys.F5,
-    57369: Keys.F6,
-    57370: Keys.F7,
-    57371: Keys.F8,
-    57372: Keys.F9,
-    57373: Keys.F10,
-    57374: Keys.F11,
-    57375: Keys.F12,
 }
 
 
@@ -214,16 +209,11 @@ def _apply_modifiers(base: Keys, ctrl: bool, shift: bool) -> Keys:
     Promote a plain functional `Keys` value to its richer Ctrl / Shift /
     Ctrl-Shift variant when prompt_toolkit has an enum for it.
 
-    `base` is one of the unmodified functional keys from `_FUNCTIONAL`
-    (Enter, Tab, Escape, arrows, navigation block, F1–F12). `ctrl` and
-    `shift` are booleans decoded from the modifier mask; the Alt bit is
-    handled one level up in `decode_csi_u`, so it is intentionally not a
+    `base` is one of the four unmodified functional keys from
+    `_FUNCTIONAL` — Enter, Tab, Escape, Backspace. `ctrl` and `shift`
+    are booleans decoded from the modifier mask; the Alt bit is handled
+    one level up in `decode_csi_u`, so it is intentionally not a
     parameter here.
-
-    When no matching richer enum exists (e.g. plain Shift-Enter,
-    Shift-Fn, Shift-Backspace), the base key is returned unchanged. The
-    caller should treat those as "modifier silently folded away" rather
-    than "decode failure".
     """
     if base is Keys.ControlM:  # Enter
         if ctrl and shift:
@@ -261,14 +251,4 @@ def _apply_modifiers(base: Keys, ctrl: bool, shift: bool) -> Keys:
             return Keys.ShiftBackspace
         return Keys.ControlH
 
-    # F1..F24 — Ctrl+ is a distinct enum; Shift+ is mapped to FN+12 in
-    # prompt_toolkit's existing convention (F1 → F13 etc.), but we don't
-    # emulate that here; Shift+Fn just returns Fn for now.
-    if base.value.startswith("f") and base.value[1:].isdigit():
-        if ctrl:
-            ctrl_key: Keys | None = getattr(Keys, "Control" + base.name, None)
-            if ctrl_key is not None:
-                return ctrl_key
-        return base
-
     return base

tests/test_kitty_keyboard.py

@@ -42,24 +42,22 @@
         ("\x1b[127;5u", Keys.ControlBackspace),
         ("\x1b[127;6u", Keys.ControlShiftBackspace),
         # NOTE: arrow keys, navigation block (Insert / Delete / Home /
-        # End / PageUp / PageDown), and F1–F4 intentionally do *not*
+        # End / PageUp / PageDown), and F1–F12 intentionally do *not*
         # appear here. Under flag 1 (disambiguate) — the only flag
         # prompt_toolkit pushes — the Kitty spec keeps these keys in
         # their legacy `CSI <n> ~` / `CSI <letter>` / `SS3 <letter>`
         # encoding even when modified. They travel through
         # `ANSI_SEQUENCES` (see `test_parser_routes_legacy_modified_arrow`
-        # below), not through the CSI u decoder. Codepoints 57348–57363
-        # are only ever emitted under flag 8 (report-all-as-escape);
-        # adding them back belongs with any flag-8 work, not here.
+        # below), not through the CSI u decoder. Their functional
+        # codepoints (57345–57375) would only appear under flag 8
+        # (report-all-as-escape); adding handling for them belongs
+        # with any flag-8 work, not here.
         # Ctrl + letter.
         ("\x1b[97;5u", Keys.ControlA),
         ("\x1b[111;5u", Keys.ControlO),
         ("\x1b[122;5u", Keys.ControlZ),
         # Ctrl + digit.
         ("\x1b[49;5u", Keys.Control1),
-        # F-keys.
-        ("\x1b[57364u", Keys.F1),
-        ("\x1b[57364;5u", Keys.ControlF1),
         # Ctrl + Shift + digit.
         ("\x1b[49;6u", Keys.ControlShift1),
     ],