Restore shortcuts in documentation, define identifiers

IPython/terminal/shortcuts/auto_match.py

@@ -0,0 +1,90 b''
+import re
+from prompt_toolkit.key_binding import KeyPressEvent
+
+
+def parenthesis(event: KeyPressEvent):
+    """Auto-close parenthesis"""
+    event.current_buffer.insert_text("()")
+    event.current_buffer.cursor_left()
+
+
+def brackets(event: KeyPressEvent):
+    """Auto-close brackets"""
+    event.current_buffer.insert_text("[]")
+    event.current_buffer.cursor_left()
+
+
+def braces(event: KeyPressEvent):
+    """Auto-close braces"""
+    event.current_buffer.insert_text("{}")
+    event.current_buffer.cursor_left()
+
+
+def double_quote(event: KeyPressEvent):
+    """Auto-close double quotes"""
+    event.current_buffer.insert_text('""')
+    event.current_buffer.cursor_left()
+
+
+def single_quote(event: KeyPressEvent):
+    """Auto-close single quotes"""
+    event.current_buffer.insert_text("''")
+    event.current_buffer.cursor_left()
+
+
+def docstring_double_quotes(event: KeyPressEvent):
+    """Auto-close docstring (double quotes)"""
+    event.current_buffer.insert_text('""""')
+    event.current_buffer.cursor_left(3)
+
+
+def docstring_single_quotes(event: KeyPressEvent):
+    """Auto-close docstring (single quotes)"""
+    event.current_buffer.insert_text("''''")
+    event.current_buffer.cursor_left(3)
+
+
+def raw_string_parenthesis(event: KeyPressEvent):
+    """Auto-close parenthesis in raw strings"""
+    matches = re.match(
+        r".*(r|R)[\"'](-*)",
+        event.current_buffer.document.current_line_before_cursor,
+    )
+    dashes = matches.group(2) or ""
+    event.current_buffer.insert_text("()" + dashes)
+    event.current_buffer.cursor_left(len(dashes) + 1)
+
+
+def raw_string_bracket(event: KeyPressEvent):
+    """Auto-close bracker in raw strings"""
+    matches = re.match(
+        r".*(r|R)[\"'](-*)",
+        event.current_buffer.document.current_line_before_cursor,
+    )
+    dashes = matches.group(2) or ""
+    event.current_buffer.insert_text("[]" + dashes)
+    event.current_buffer.cursor_left(len(dashes) + 1)
+
+
+def raw_string_braces(event: KeyPressEvent):
+    """Auto-close braces in raw strings"""
+    matches = re.match(
+        r".*(r|R)[\"'](-*)",
+        event.current_buffer.document.current_line_before_cursor,
+    )
+    dashes = matches.group(2) or ""
+    event.current_buffer.insert_text("{}" + dashes)
+    event.current_buffer.cursor_left(len(dashes) + 1)
+
+
+def skip_over(event: KeyPressEvent):
+    """Skip over automatically added parenthesis.
+
+    (rather than adding another parenthesis)"""
+    event.current_buffer.cursor_right()
+
+
+def delete_pair(event: KeyPressEvent):
+    """Delete auto-closed parenthesis"""
+    event.current_buffer.delete()
+    event.current_buffer.delete_before_cursor()

IPython/terminal/shortcuts/autosuggestions.py

@@ -0,0 +1,39 b''
+import re
+from prompt_toolkit.key_binding import KeyPressEvent
+from prompt_toolkit.key_binding.bindings import named_commands as nc
+
+
+# Needed for to accept autosuggestions in vi insert mode
+def accept_in_vi_insert_mode(event: KeyPressEvent):
+    """Apply autosuggestion if at end of line."""
+    b = event.current_buffer
+    d = b.document
+    after_cursor = d.text[d.cursor_position :]
+    lines = after_cursor.split("\n")
+    end_of_current_line = lines[0].strip()
+    suggestion = b.suggestion
+    if (suggestion is not None) and (suggestion.text) and (end_of_current_line == ""):
+        b.insert_text(suggestion.text)
+    else:
+        nc.end_of_line(event)
+
+
+def accept(event):
+    """Accept suggestion"""
+    b = event.current_buffer
+    suggestion = b.suggestion
+    if suggestion:
+        b.insert_text(suggestion.text)
+    else:
+        nc.forward_char(event)
+
+
+def accept_word(event):
+    """Fill partial suggestion by word"""
+    b = event.current_buffer
+    suggestion = b.suggestion
+    if suggestion:
+        t = re.split(r"(\S+\s+)", suggestion.text)
+        b.insert_text(next((x for x in t if x), ""))
+    else:
+        nc.forward_word(event)

docs/source/_static/theme_overrides.css

@@ -0,0 +1,7 b''
+/*
+ Needed to revert problematic lack of wrapping in sphinx_rtd_theme, see:
+ https://github.com/readthedocs/sphinx_rtd_theme/issues/117
+*/
+.wy-table-responsive table.shortcuts td, .wy-table-responsive table.shortcuts th {
+  white-space: normal!important;
+}

IPython/terminal/shortcuts/__init__.py

@@ -16,14 +16,29 b' from typing import Callable'
 
 from prompt_toolkit.application.current import get_app
 from prompt_toolkit.enums import DEFAULT_BUFFER, SEARCH_BUFFER
-from prompt_toolkit.filters import (has_focus, has_selection, Condition,
-    vi_insert_mode, emacs_insert_mode, has_completions, vi_mode)
-from prompt_toolkit.key_binding.bindings.completion import display_completions_like_readline
+from prompt_toolkit.filters import (
+    has_focus as has_focus_impl,
+    has_selection,
+    Condition,
+    vi_insert_mode,
+    emacs_insert_mode,
+    has_completions,
+    vi_mode,
+)
+from prompt_toolkit.key_binding.bindings.completion import (
+    display_completions_like_readline,
+)
 from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.key_binding.bindings import named_commands as nc
 from prompt_toolkit.key_binding.vi_state import InputMode, ViState
+from prompt_toolkit.layout.layout import FocusableElement
 
 from IPython.utils.decorators import undoc
+from . import auto_match as match, autosuggestions
+
+
+__all__ = ["create_ipython_shortcuts"]
+
 
 @undoc
 @Condition
@@ -32,80 +47,84 b' def cursor_in_leading_ws():'
     return (not before) or before.isspace()
 
 
-# Needed for to accept autosuggestions in vi insert mode
-def _apply_autosuggest(event):
-    """
-    Apply autosuggestion if at end of line.
-    """
-    b = event.current_buffer
-    d = b.document
-    after_cursor = d.text[d.cursor_position :]
-    lines = after_cursor.split("\n")
-    end_of_current_line = lines[0].strip()
-    suggestion = b.suggestion
-    if (suggestion is not None) and (suggestion.text) and (end_of_current_line == ""):
-        b.insert_text(suggestion.text)
-    else:
-        nc.end_of_line(event)
+def has_focus(value: FocusableElement):
+    """Wrapper around has_focus adding a nice `__name__` to tester function"""
+    tester = has_focus_impl(value).func
+    tester.__name__ = f"is_focused({value})"
+    return Condition(tester)
 
-def create_ipython_shortcuts(shell):
-    """Set up the prompt_toolkit keyboard shortcuts for IPython"""
+
+def create_ipython_shortcuts(shell, for_all_platforms: bool = False):
+    """Set up the prompt_toolkit keyboard shortcuts for IPython."""
+    # Warning: if possible, do NOT define handler functions in the locals
+    # scope of this function, instead define functions in the global
+    # scope, or a separate module, and include a user-friendly docstring
+    # describing the action.
 
     kb = KeyBindings()
     insert_mode = vi_insert_mode | emacs_insert_mode
 
-    if getattr(shell, 'handle_return', None):
+    if getattr(shell, "handle_return", None):
         return_handler = shell.handle_return(shell)
     else:
         return_handler = newline_or_execute_outer(shell)
 
-    kb.add('enter', filter=(has_focus(DEFAULT_BUFFER)
-                            & ~has_selection
-                            & insert_mode
-                        ))(return_handler)
-
-    def reformat_and_execute(event):
-        reformat_text_before_cursor(event.current_buffer, event.current_buffer.document, shell)
-        event.current_buffer.validate_and_handle()
+    kb.add("enter", filter=(has_focus(DEFAULT_BUFFER) & ~has_selection & insert_mode))(
+        return_handler
+    )
 
     @Condition
     def ebivim():
         return shell.emacs_bindings_in_vi_insert_mode
 
-    kb.add(
+    @kb.add(
         "escape",
         "enter",
         filter=(has_focus(DEFAULT_BUFFER) & ~has_selection & insert_mode & ebivim),
-    )(reformat_and_execute)
+    )
+    def reformat_and_execute(event):
+        """Reformat code and execute it"""
+        reformat_text_before_cursor(
+            event.current_buffer, event.current_buffer.document, shell
+        )
+        event.current_buffer.validate_and_handle()
 
     kb.add("c-\\")(quit)
 
-    kb.add('c-p', filter=(vi_insert_mode & has_focus(DEFAULT_BUFFER))
-                )(previous_history_or_previous_completion)
+    kb.add("c-p", filter=(vi_insert_mode & has_focus(DEFAULT_BUFFER)))(
+        previous_history_or_previous_completion
+    )
 
-    kb.add('c-n', filter=(vi_insert_mode & has_focus(DEFAULT_BUFFER))
-                )(next_history_or_next_completion)
+    kb.add("c-n", filter=(vi_insert_mode & has_focus(DEFAULT_BUFFER)))(
+        next_history_or_next_completion
+    )
 
-    kb.add('c-g', filter=(has_focus(DEFAULT_BUFFER) & has_completions)
-                )(dismiss_completion)
+    kb.add("c-g", filter=(has_focus(DEFAULT_BUFFER) & has_completions))(
+        dismiss_completion
+    )
 
-    kb.add('c-c', filter=has_focus(DEFAULT_BUFFER))(reset_buffer)
+    kb.add("c-c", filter=has_focus(DEFAULT_BUFFER))(reset_buffer)
 
-    kb.add('c-c', filter=has_focus(SEARCH_BUFFER))(reset_search_buffer)
+    kb.add("c-c", filter=has_focus(SEARCH_BUFFER))(reset_search_buffer)
 
-    supports_suspend = Condition(lambda: hasattr(signal, 'SIGTSTP'))
-    kb.add('c-z', filter=supports_suspend)(suspend_to_bg)
+    supports_suspend = Condition(lambda: hasattr(signal, "SIGTSTP"))
+    kb.add("c-z", filter=supports_suspend)(suspend_to_bg)
 
     # Ctrl+I == Tab
-    kb.add('tab', filter=(has_focus(DEFAULT_BUFFER)
-                          & ~has_selection
-                          & insert_mode
-                          & cursor_in_leading_ws
-                        ))(indent_buffer)
-    kb.add('c-o', filter=(has_focus(DEFAULT_BUFFER) & emacs_insert_mode)
-           )(newline_autoindent_outer(shell.input_transformer_manager))
+    kb.add(
+        "tab",
+        filter=(
+            has_focus(DEFAULT_BUFFER)
+            & ~has_selection
+            & insert_mode
+            & cursor_in_leading_ws
+        ),
+    )(indent_buffer)
+    kb.add("c-o", filter=(has_focus(DEFAULT_BUFFER) & emacs_insert_mode))(
+        newline_autoindent_outer(shell.input_transformer_manager)
+    )
 
-    kb.add('f2', filter=has_focus(DEFAULT_BUFFER))(open_input_in_editor)
+    kb.add("f2", filter=has_focus(DEFAULT_BUFFER))(open_input_in_editor)
 
     @Condition
     def auto_match():
@@ -146,6 +165,8 b' def create_ipython_shortcuts(shell):'
                 before_cursor = app.current_buffer.document.current_line_before_cursor
                 return bool(m.match(before_cursor))
 
+            _preceding_text.__name__ = f"preceding_text({pattern!r})"
+
         condition = Condition(_preceding_text)
         _preceding_text_cache[pattern] = condition
         return condition
@@ -161,6 +182,8 b' def create_ipython_shortcuts(shell):'
             app = get_app()
             return bool(m.match(app.current_buffer.document.current_line_after_cursor))
 
+        _following_text.__name__ = f"following_text({pattern!r})"
+
         condition = Condition(_following_text)
         _following_text_cache[pattern] = condition
         return condition
@@ -178,151 +201,110 b' def create_ipython_shortcuts(shell):'
         return not ('"' in s or "'" in s)
 
     # auto match
-    @kb.add("(", filter=focused_insert & auto_match & following_text(r"[,)}\]]|$"))
-    def _(event):
-        event.current_buffer.insert_text("()")
-        event.current_buffer.cursor_left()
-
-    @kb.add("[", filter=focused_insert & auto_match & following_text(r"[,)}\]]|$"))
-    def _(event):
-        event.current_buffer.insert_text("[]")
-        event.current_buffer.cursor_left()
-
-    @kb.add("{", filter=focused_insert & auto_match & following_text(r"[,)}\]]|$"))
-    def _(event):
-        event.current_buffer.insert_text("{}")
-        event.current_buffer.cursor_left()
+    auto_match_parens = {"(": match.parenthesis, "[": match.brackets, "{": match.braces}
+    for key, cmd in auto_match_parens.items():
+        kb.add(key, filter=focused_insert & auto_match & following_text(r"[,)}\]]|$"))(
+            cmd
+        )
 
-    @kb.add(
+    kb.add(
         '"',
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(lambda line: all_quotes_paired('"', line))
         & following_text(r"[,)}\]]|$"),
-    )
-    def _(event):
-        event.current_buffer.insert_text('""')
-        event.current_buffer.cursor_left()
+    )(match.double_quote)
 
-    @kb.add(
+    kb.add(
         "'",
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(lambda line: all_quotes_paired("'", line))
         & following_text(r"[,)}\]]|$"),
-    )
-    def _(event):
-        event.current_buffer.insert_text("''")
-        event.current_buffer.cursor_left()
+    )(match.single_quote)
 
-    @kb.add(
+    kb.add(
         '"',
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(r'^.*""$'),
-    )
-    def _(event):
-        event.current_buffer.insert_text('""""')
-        event.current_buffer.cursor_left(3)
+    )(match.docstring_double_quotes)
 
-    @kb.add(
+    kb.add(
         "'",
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(r"^.*''$"),
-    )
-    def _(event):
-        event.current_buffer.insert_text("''''")
-        event.current_buffer.cursor_left(3)
+    )(match.docstring_single_quotes)
 
     # raw string
-    @kb.add(
-        "(", filter=focused_insert & auto_match & preceding_text(r".*(r|R)[\"'](-*)$")
-    )
-    def _(event):
-        matches = re.match(
-            r".*(r|R)[\"'](-*)",
-            event.current_buffer.document.current_line_before_cursor,
-        )
-        dashes = matches.group(2) or ""
-        event.current_buffer.insert_text("()" + dashes)
-        event.current_buffer.cursor_left(len(dashes) + 1)
+    auto_match_parens_raw_string = {
+        "(": match.raw_string_parenthesis,
+        "[": match.raw_string_bracket,
+        "{": match.raw_string_braces,
+    }
+    for key, cmd in auto_match_parens_raw_string.items():
+        kb.add(
+            key,
+            filter=focused_insert & auto_match & preceding_text(r".*(r|R)[\"'](-*)$"),
+        )(cmd)
 
-    @kb.add(
-        "[", filter=focused_insert & auto_match & preceding_text(r".*(r|R)[\"'](-*)$")
+    # just move cursor
+    kb.add(")", filter=focused_insert & auto_match & following_text(r"^\)"))(
+        match.skip_over
     )
-    def _(event):
-        matches = re.match(
-            r".*(r|R)[\"'](-*)",
-            event.current_buffer.document.current_line_before_cursor,
-        )
-        dashes = matches.group(2) or ""
-        event.current_buffer.insert_text("[]" + dashes)
-        event.current_buffer.cursor_left(len(dashes) + 1)
-
-    @kb.add(
-        "{", filter=focused_insert & auto_match & preceding_text(r".*(r|R)[\"'](-*)$")
+    kb.add("]", filter=focused_insert & auto_match & following_text(r"^\]"))(
+        match.skip_over
+    )
+    kb.add("}", filter=focused_insert & auto_match & following_text(r"^\}"))(
+        match.skip_over
+    )
+    kb.add('"', filter=focused_insert & auto_match & following_text('^"'))(
+        match.skip_over
+    )
+    kb.add("'", filter=focused_insert & auto_match & following_text("^'"))(
+        match.skip_over
     )
-    def _(event):
-        matches = re.match(
-            r".*(r|R)[\"'](-*)",
-            event.current_buffer.document.current_line_before_cursor,
-        )
-        dashes = matches.group(2) or ""
-        event.current_buffer.insert_text("{}" + dashes)
-        event.current_buffer.cursor_left(len(dashes) + 1)
-
-    # just move cursor
-    @kb.add(")", filter=focused_insert & auto_match & following_text(r"^\)"))
-    @kb.add("]", filter=focused_insert & auto_match & following_text(r"^\]"))
-    @kb.add("}", filter=focused_insert & auto_match & following_text(r"^\}"))
-    @kb.add('"', filter=focused_insert & auto_match & following_text('^"'))
-    @kb.add("'", filter=focused_insert & auto_match & following_text("^'"))
-    def _(event):
-        event.current_buffer.cursor_right()
 
-    @kb.add(
+    kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\($")
         & auto_match
         & following_text(r"^\)"),
-    )
-    @kb.add(
+    )(match.delete_pair)
+    kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\[$")
         & auto_match
         & following_text(r"^\]"),
-    )
-    @kb.add(
+    )(match.delete_pair)
+    kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\{$")
         & auto_match
         & following_text(r"^\}"),
-    )
-    @kb.add(
+    )(match.delete_pair)
+    kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text('.*"$')
         & auto_match
         & following_text('^"'),
-    )
-    @kb.add(
+    )(match.delete_pair)
+    kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*'$")
         & auto_match
         & following_text(r"^'"),
-    )
-    def _(event):
-        event.current_buffer.delete()
-        event.current_buffer.delete_before_cursor()
+    )(match.delete_pair)
 
     if shell.display_completions == "readlinelike":
         kb.add(
@@ -335,37 +317,22 b' def create_ipython_shortcuts(shell):'
             ),
         )(display_completions_like_readline)
 
-    if sys.platform == "win32":
+    if sys.platform == "win32" or for_all_platforms:
         kb.add("c-v", filter=(has_focus(DEFAULT_BUFFER) & ~vi_mode))(win_paste)
 
     focused_insert_vi = has_focus(DEFAULT_BUFFER) & vi_insert_mode
 
-    @kb.add("end", filter=has_focus(DEFAULT_BUFFER) & (ebivim | ~vi_insert_mode))
-    def _(event):
-        _apply_autosuggest(event)
-
-    @kb.add("c-e", filter=focused_insert_vi & ebivim)
-    def _(event):
-        _apply_autosuggest(event)
-
-    @kb.add("c-f", filter=focused_insert_vi)
-    def _(event):
-        b = event.current_buffer
-        suggestion = b.suggestion
-        if suggestion:
-            b.insert_text(suggestion.text)
-        else:
-            nc.forward_char(event)
-
-    @kb.add("escape", "f", filter=focused_insert_vi & ebivim)
-    def _(event):
-        b = event.current_buffer
-        suggestion = b.suggestion
-        if suggestion:
-            t = re.split(r"(\S+\s+)", suggestion.text)
-            b.insert_text(next((x for x in t if x), ""))
-        else:
-            nc.forward_word(event)
+    # autosuggestions
+    kb.add("end", filter=has_focus(DEFAULT_BUFFER) & (ebivim | ~vi_insert_mode))(
+        autosuggestions.accept_in_vi_insert_mode
+    )
+    kb.add("c-e", filter=focused_insert_vi & ebivim)(
+        autosuggestions.accept_in_vi_insert_mode
+    )
+    kb.add("c-f", filter=focused_insert_vi)(autosuggestions.accept)
+    kb.add("escape", "f", filter=focused_insert_vi & ebivim)(
+        autosuggestions.accept_word
+    )
 
     # Simple Control keybindings
     key_cmd_dict = {
@@ -423,7 +390,7 b' def create_ipython_shortcuts(shell):'
 
 
 def reformat_text_before_cursor(buffer, document, shell):
-    text = buffer.delete_before_cursor(len(document.text[:document.cursor_position]))
+    text = buffer.delete_before_cursor(len(document.text[: document.cursor_position]))
     try:
         formatted_text = shell.reformat_handler(text)
         buffer.insert_text(formatted_text)
@@ -432,7 +399,6 b' def reformat_text_before_cursor(buffer, document, shell):'
 
 
 def newline_or_execute_outer(shell):
-
     def newline_or_execute(event):
         """When the user presses return, insert a newline or execute the code."""
         b = event.current_buffer
@@ -451,34 +417,38 b' def newline_or_execute_outer(shell):'
         if d.line_count == 1:
             check_text = d.text
         else:
-            check_text = d.text[:d.cursor_position]
+            check_text = d.text[: d.cursor_position]
         status, indent = shell.check_complete(check_text)
-       
+
         # if all we have after the cursor is whitespace: reformat current text
         # before cursor
-        after_cursor = d.text[d.cursor_position:]
+        after_cursor = d.text[d.cursor_position :]
         reformatted = False
         if not after_cursor.strip():
             reformat_text_before_cursor(b, d, shell)
             reformatted = True
-        if not (d.on_last_line or
-                d.cursor_position_row >= d.line_count - d.empty_line_count_at_the_end()
-                ):
+        if not (
+            d.on_last_line
+            or d.cursor_position_row >= d.line_count - d.empty_line_count_at_the_end()
+        ):
             if shell.autoindent:
-                b.insert_text('\n' + indent)
+                b.insert_text("\n" + indent)
             else:
-                b.insert_text('\n')
+                b.insert_text("\n")
             return
 
-        if (status != 'incomplete') and b.accept_handler:
+        if (status != "incomplete") and b.accept_handler:
             if not reformatted:
                 reformat_text_before_cursor(b, d, shell)
             b.validate_and_handle()
         else:
             if shell.autoindent:
-                b.insert_text('\n' + indent)
+                b.insert_text("\n" + indent)
             else:
-                b.insert_text('\n')
+                b.insert_text("\n")
+
+    newline_or_execute.__qualname__ = "newline_or_execute"
+
     return newline_or_execute
 
 
@@ -501,12 +471,14 b' def next_history_or_next_completion(event):'
 
 
 def dismiss_completion(event):
+    """Dismiss completion"""
     b = event.current_buffer
     if b.complete_state:
         b.cancel_completion()
 
 
 def reset_buffer(event):
+    """Reset buffer"""
     b = event.current_buffer
     if b.complete_state:
         b.cancel_completion()
@@ -515,16 +487,22 b' def reset_buffer(event):'
 
 
 def reset_search_buffer(event):
+    """Reset search buffer"""
     if event.current_buffer.document.text:
         event.current_buffer.reset()
     else:
         event.app.layout.focus(DEFAULT_BUFFER)
 
+
 def suspend_to_bg(event):
+    """Suspend to background"""
     event.app.suspend_to_background()
 
+
 def quit(event):
     """
+    Quit application with ``SIGQUIT`` if supported or ``sys.exit`` otherwise.
+
     On platforms that support SIGQUIT, send SIGQUIT to the current process.
     On other platforms, just exit the process with a message.
     """
@@ -534,8 +512,11 b' def quit(event):'
     else:
         sys.exit("Quit")
 
+
 def indent_buffer(event):
-    event.current_buffer.insert_text(' ' * 4)
+    """Indent buffer"""
+    event.current_buffer.insert_text(" " * 4)
+
 
 @undoc
 def newline_with_copy_margin(event):
@@ -547,9 +528,12 b' def newline_with_copy_margin(event):'
     Preserve margin and cursor position when using
     Control-O to insert a newline in EMACS mode
     """
-    warnings.warn("`newline_with_copy_margin(event)` is deprecated since IPython 6.0. "
-      "see `newline_autoindent_outer(shell)(event)` for a replacement.",
-                  DeprecationWarning, stacklevel=2)
+    warnings.warn(
+        "`newline_with_copy_margin(event)` is deprecated since IPython 6.0. "
+        "see `newline_autoindent_outer(shell)(event)` for a replacement.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
 
     b = event.current_buffer
     cursor_start_pos = b.document.cursor_position_col
@@ -560,6 +544,7 b' def newline_with_copy_margin(event):'
         pos_diff = cursor_start_pos - cursor_end_pos
         b.cursor_right(count=pos_diff)
 
+
 def newline_autoindent_outer(inputsplitter) -> Callable[..., None]:
     """
     Return a function suitable for inserting a indented newline after the cursor.
@@ -571,28 +556,33 b' def newline_autoindent_outer(inputsplitter) -> Callable[..., None]:'
     """
 
     def newline_autoindent(event):
-        """insert a newline after the cursor indented appropriately."""
+        """Insert a newline after the cursor indented appropriately."""
         b = event.current_buffer
         d = b.document
 
         if b.complete_state:
             b.cancel_completion()
-        text = d.text[:d.cursor_position] + '\n'
+        text = d.text[: d.cursor_position] + "\n"
         _, indent = inputsplitter.check_complete(text)
-        b.insert_text('\n' + (' ' * (indent or 0)), move_cursor=False)
+        b.insert_text("\n" + (" " * (indent or 0)), move_cursor=False)
+
+    newline_autoindent.__qualname__ = "newline_autoindent"
 
     return newline_autoindent
 
 
 def open_input_in_editor(event):
+    """Open code from input in external editor"""
     event.app.current_buffer.open_in_editor()
 
 
-if sys.platform == 'win32':
+if sys.platform == "win32":
     from IPython.core.error import TryNext
-    from IPython.lib.clipboard import (ClipboardEmpty,
-                                       win32_clipboard_get,
-                                       tkinter_clipboard_get)
+    from IPython.lib.clipboard import (
+        ClipboardEmpty,
+        win32_clipboard_get,
+        tkinter_clipboard_get,
+    )
 
     @undoc
     def win_paste(event):
@@ -606,3 +596,10 b" if sys.platform == 'win32':"
         except ClipboardEmpty:
             return
         event.current_buffer.insert_text(text.replace("\t", " " * 4))
+
+else:
+
+    @undoc
+    def win_paste(event):
+        """Stub used when auto-generating shortcuts for documentation"""
+        pass

docs/autogen_shortcuts.py

@@ -1,45 +1,98 b''
+from dataclasses import dataclass
+from inspect import getsource
 from pathlib import Path
+from typing import cast, Callable, List, Union
+from html import escape as html_escape
+import re
+
+from prompt_toolkit.keys import KEY_ALIASES
+from prompt_toolkit.key_binding import KeyBindingsBase
+from prompt_toolkit.filters import Filter, Condition
+from prompt_toolkit.shortcuts import PromptSession
 
 from IPython.terminal.shortcuts import create_ipython_shortcuts
 
-def name(c):
-    s = c.__class__.__name__
-    if s == '_Invert':
-        return '(Not: %s)' % name(c.filter)
-    if s in log_filters.keys():
-        return '(%s: %s)' % (log_filters[s], ', '.join(name(x) for x in c.filters))
-    return log_filters[s] if s in log_filters.keys() else s
 
+@dataclass
+class Shortcut:
+    #: a sequence of keys (each element on the list corresponds to pressing one or more keys)
+    keys_sequence: list[str]
+    filter: str
 
-def sentencize(s):
-    """Extract first sentence
-    """
-    s = s.replace('\n', ' ').strip().split('.')
-    s = s[0] if len(s) else s
-    try:
-        return " ".join(s.split())
-    except AttributeError:
-        return s
 
+@dataclass
+class Handler:
+    description: str
+    identifier: str
 
-def most_common(lst, n=3):
-    """Most common elements occurring more then `n` times
-    """
-    from collections import Counter
 
-    c = Counter(lst)
-    return [k for (k, v) in c.items() if k and v > n]
+@dataclass
+class Binding:
+    handler: Handler
+    shortcut: Shortcut
 
 
-def multi_filter_str(flt):
-    """Yield readable conditional filter
-    """
-    assert hasattr(flt, 'filters'), 'Conditional filter required'
-    yield name(flt)
+class _NestedFilter(Filter):
+    """Protocol reflecting non-public prompt_toolkit's `_AndList` and `_OrList`."""
+
+    filters: List[Filter]
+
+
+class _Invert(Filter):
+    """Protocol reflecting non-public prompt_toolkit's `_Invert`."""
+
+    filter: Filter
+
+
+conjunctions_labels = {"_AndList": "and", "_OrList": "or"}
 
+ATOMIC_CLASSES = {"Never", "Always", "Condition"}
+
+
+def format_filter(
+    filter_: Union[Filter, _NestedFilter, Condition, _Invert],
+    is_top_level=True,
+    skip=None,
+) -> str:
+    """Create easily readable description of the filter."""
+    s = filter_.__class__.__name__
+    if s == "Condition":
+        func = cast(Condition, filter_).func
+        name = func.__name__
+        if name == "<lambda>":
+            source = getsource(func)
+            return source.split("=")[0].strip()
+        return func.__name__
+    elif s == "_Invert":
+        operand = cast(_Invert, filter_).filter
+        if operand.__class__.__name__ in ATOMIC_CLASSES:
+            return f"not {format_filter(operand, is_top_level=False)}"
+        return f"not ({format_filter(operand, is_top_level=False)})"
+    elif s in conjunctions_labels:
+        filters = cast(_NestedFilter, filter_).filters
+        conjunction = conjunctions_labels[s]
+        glue = f" {conjunction} "
+        result = glue.join(format_filter(x, is_top_level=False) for x in filters)
+        if len(filters) > 1 and not is_top_level:
+            result = f"({result})"
+        return result
+    elif s in ["Never", "Always"]:
+        return s.lower()
+    else:
+        raise ValueError(f"Unknown filter type: {filter_}")
+
+
+def sentencize(s) -> str:
+    """Extract first sentence"""
+    s = re.split(r"\.\W", s.replace("\n", " ").strip())
+    s = s[0] if len(s) else ""
+    if not s.endswith("."):
+        s += "."
+    try:
+        return " ".join(s.split())
+    except AttributeError:
+        return s
 
-log_filters = {'_AndList': 'And', '_OrList': 'Or'}
-log_invert =  {'_Invert'}
 
 class _DummyTerminal:
     """Used as a buffer to get prompt_toolkit bindings
@@ -50,47 +103,118 b' class _DummyTerminal:'
     editing_mode = "emacs"
 
 
-ipy_bindings = create_ipython_shortcuts(_DummyTerminal()).bindings
-
-dummy_docs = []  # ignore bindings without proper documentation
-
-common_docs = most_common([kb.handler.__doc__ for kb in ipy_bindings])
-if common_docs:
-    dummy_docs.extend(common_docs)
+def create_identifier(handler: Callable):
+    parts = handler.__module__.split(".")
+    name = handler.__name__
+    package = parts[0]
+    if len(parts) > 1:
+        final_module = parts[-1]
+        return f"{package}:{final_module}.{name}"
+    else:
+        return f"{package}:{name}"
+
+
+def bindings_from_prompt_toolkit(prompt_bindings: KeyBindingsBase) -> List[Binding]:
+    """Collect bindings to a simple format that does not depend on prompt-toolkit internals"""
+    bindings: List[Binding] = []
+
+    for kb in prompt_bindings.bindings:
+        bindings.append(
+            Binding(
+                handler=Handler(
+                    description=kb.handler.__doc__ or "",
+                    identifier=create_identifier(kb.handler),
+                ),
+                shortcut=Shortcut(
+                    keys_sequence=[
+                        str(k.value) if hasattr(k, "value") else k for k in kb.keys
+                    ],
+                    filter=format_filter(kb.filter, skip={"has_focus_filter"}),
+                ),
+            )
+        )
+    return bindings
+
+
+INDISTINGUISHABLE_KEYS = {**KEY_ALIASES, **{v: k for k, v in KEY_ALIASES.items()}}
+
+
+def format_prompt_keys(keys: str, add_alternatives=True) -> str:
+    """Format prompt toolkit key with modifier into an RST representation."""
+
+    def to_rst(key):
+        escaped = key.replace("\\", "\\\\")
+        return f":kbd:`{escaped}`"
+
+    keys_to_press: list[str]
+
+    prefixes = {
+        "c-s-": [to_rst("ctrl"), to_rst("shift")],
+        "s-c-": [to_rst("ctrl"), to_rst("shift")],
+        "c-": [to_rst("ctrl")],
+        "s-": [to_rst("shift")],
+    }
+
+    for prefix, modifiers in prefixes.items():
+        if keys.startswith(prefix):
+            remainder = keys[len(prefix) :]
+            keys_to_press = [*modifiers, to_rst(remainder)]
+            break
+    else:
+        keys_to_press = [to_rst(keys)]
 
-dummy_docs = list(set(dummy_docs))
+    result = " + ".join(keys_to_press)
 
-single_filter = {}
-multi_filter =  {}
-for kb in ipy_bindings:
-    doc = kb.handler.__doc__
-    if not doc or doc in dummy_docs:
-        continue
+    if keys in INDISTINGUISHABLE_KEYS and add_alternatives:
+        alternative = INDISTINGUISHABLE_KEYS[keys]
 
-    shortcut = ' '.join([k if isinstance(k, str) else k.name for k in kb.keys])
-    shortcut += shortcut.endswith('\\') and '\\' or ''
-    if hasattr(kb.filter, 'filters'):
-        flt = ' '.join(multi_filter_str(kb.filter))
-        multi_filter[(shortcut, flt)] = sentencize(doc)
-    else:
-        single_filter[(shortcut, name(kb.filter))] = sentencize(doc)
+        result = (
+            result
+            + " (or "
+            + format_prompt_keys(alternative, add_alternatives=False)
+            + ")"
+        )
 
+    return result
 
 if __name__ == '__main__':
     here = Path(__file__).parent
     dest = here / "source" / "config" / "shortcuts"
 
-    def sort_key(item):
-        k, v = item
-        shortcut, flt = k
-        return (str(shortcut), str(flt))
-
-    for filters, output_filename in [
-        (single_filter, "single_filtered"),
-        (multi_filter, "multi_filtered"),
-    ]:
-        with (dest / "{}.csv".format(output_filename)).open(
-            "w", encoding="utf-8"
-        ) as csv:
-            for (shortcut, flt), v in sorted(filters.items(), key=sort_key):
-                csv.write(":kbd:`{}`\t{}\t{}\n".format(shortcut, flt, v))
+    ipy_bindings = create_ipython_shortcuts(_DummyTerminal(), for_all_platforms=True)
+
+    session = PromptSession(key_bindings=ipy_bindings)
+    prompt_bindings = session.app.key_bindings
+
+    assert prompt_bindings
+    # Ensure that we collected the default shortcuts
+    assert len(prompt_bindings.bindings) > len(ipy_bindings.bindings)
+
+    bindings = bindings_from_prompt_toolkit(prompt_bindings)
+
+    def sort_key(binding: Binding):
+        return binding.handler.identifier, binding.shortcut.filter
+
+    filters = []
+    with (dest / "table.tsv").open("w", encoding="utf-8") as csv:
+        for binding in sorted(bindings, key=sort_key):
+            sequence = ", ".join(
+                [format_prompt_keys(keys) for keys in binding.shortcut.keys_sequence]
+            )
+            if binding.shortcut.filter == "always":
+                condition_label = "-"
+            else:
+                # we cannot fit all the columns as the filters got too complex over time
+                condition_label = "ⓘ"
+
+            csv.write(
+                "\t".join(
+                    [
+                        sequence,
+                        sentencize(binding.handler.description)
+                        + f" :raw-html:`<br>` `{binding.handler.identifier}`",
+                        f':raw-html:`<span title="{html_escape(binding.shortcut.filter)}" style="cursor: help">{condition_label}</span>`',
+                    ]
+                )
+                + "\n"
+            )

docs/source/conf.py

@@ -211,7 +211,6 b" default_role = 'literal'"
 # given in html_static_path.
 # html_style = 'default.css'
 
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
@@ -327,6 +326,10 b' texinfo_documents = ['
 modindex_common_prefix = ['IPython.']
 
 
+def setup(app):
+    app.add_css_file("theme_overrides.css")
+
+
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx

docs/source/config/shortcuts/index.rst

@@ -4,28 +4,23 b' IPython shortcuts'
 
 Available shortcuts in an IPython terminal.
 
-.. warning::
+.. note::
 
-  This list is automatically generated, and may not hold all available
-  shortcuts. In particular, it may depend on the version of ``prompt_toolkit``
-  installed during the generation of this page.
+  This list is automatically generated. Key bindings defined in ``prompt_toolkit`` may differ
+  between installations depending on the ``prompt_toolkit`` version.
 
 
-Single Filtered shortcuts
-=========================
-
-.. csv-table::
-    :header: Shortcut,Filter,Description
-    :widths: 30, 30, 100
-    :delim: tab
-    :file: single_filtered.csv
+* Comma-separated keys, e.g. :kbd:`Esc`, :kbd:`f`, indicate a sequence which can be activated by pressing the listed keys in succession.
+* Plus-separated keys, e.g. :kbd:`Esc` + :kbd:`f` indicate a combination which requires pressing all keys simultaneously.
+* Hover over the ⓘ icon in the filter column to see when the shortcut is active.g
 
+.. role:: raw-html(raw)
+   :format: html
 
-Multi Filtered shortcuts
-========================
 
 .. csv-table::
-    :header: Shortcut,Filter,Description
-    :widths: 30, 30, 100
+    :header: Shortcut,Description and identifier,Filter
     :delim: tab
-    :file: multi_filtered.csv
+    :class: shortcuts
+    :file: table.tsv
+    :widths: 20 75 5