MISC docs, cleanup and typing (in progress).

IPython/terminal/ipapp.py

@@ -1,343 +1,343
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The :class:`~traitlets.config.application.Application` object for the command
 line :command:`ipython` program.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 import logging
 import os
 import sys
 import warnings
 
 from traitlets.config.loader import Config
 from traitlets.config.application import boolean_flag, catch_config_error
 from IPython.core import release
 from IPython.core import usage
 from IPython.core.completer import IPCompleter
 from IPython.core.crashhandler import CrashHandler
 from IPython.core.formatters import PlainTextFormatter
 from IPython.core.history import HistoryManager
 from IPython.core.application import (
     ProfileDir, BaseIPythonApplication, base_flags, base_aliases
 )
 from IPython.core.magic import MagicsManager
 from IPython.core.magics import (
     ScriptMagics, LoggingMagics
 )
 from IPython.core.shellapp import (
     InteractiveShellApp, shell_flags, shell_aliases
 )
 from IPython.extensions.storemagic import StoreMagics
 from .interactiveshell import TerminalInteractiveShell
 from IPython.paths import get_ipython_dir
 from traitlets import (
     Bool, List, default, observe, Type
 )
 
 #-----------------------------------------------------------------------------
 # Globals, utilities and helpers
 #-----------------------------------------------------------------------------
 
 _examples = """
 ipython --matplotlib       # enable matplotlib integration
 ipython --matplotlib=qt    # enable matplotlib integration with qt4 backend
 
 ipython --log-level=DEBUG  # set logging to DEBUG
 ipython --profile=foo      # start with profile foo
 
 ipython profile create foo # create profile foo w/ default config files
 ipython help profile       # show the help for the profile subcmd
 
 ipython locate             # print the path to the IPython directory
 ipython locate profile foo # print the path to the directory for profile `foo`
 """
 
 #-----------------------------------------------------------------------------
 # Crash handler for this application
 #-----------------------------------------------------------------------------
 
 class IPAppCrashHandler(CrashHandler):
     """sys.excepthook for IPython itself, leaves a detailed report on disk."""
 
     def __init__(self, app):
         contact_name = release.author
         contact_email = release.author_email
         bug_tracker = 'https://github.com/ipython/ipython/issues'
         super(IPAppCrashHandler,self).__init__(
             app, contact_name, contact_email, bug_tracker
         )
 
     def make_report(self,traceback):
         """Return a string containing a crash report."""
 
         sec_sep = self.section_sep
         # Start with parent report
         report = [super(IPAppCrashHandler, self).make_report(traceback)]
         # Add interactive-specific info we may have
         rpt_add = report.append
         try:
             rpt_add(sec_sep+"History of session input:")
             for line in self.app.shell.user_ns['_ih']:
                 rpt_add(line)
             rpt_add('\n*** Last line of input (may not be in above history):\n')
             rpt_add(self.app.shell._last_input_line+'\n')
         except:
             pass
 
         return ''.join(report)
 
 #-----------------------------------------------------------------------------
 # Aliases and Flags
 #-----------------------------------------------------------------------------
 flags = dict(base_flags)
 flags.update(shell_flags)
 frontend_flags = {}
 addflag = lambda *args: frontend_flags.update(boolean_flag(*args))
 addflag('autoedit-syntax', 'TerminalInteractiveShell.autoedit_syntax',
         'Turn on auto editing of files with syntax errors.',
         'Turn off auto editing of files with syntax errors.'
 )
 addflag('simple-prompt', 'TerminalInteractiveShell.simple_prompt',
         "Force simple minimal prompt using `raw_input`",
         "Use a rich interactive prompt with prompt_toolkit",
 )
 
 addflag('banner', 'TerminalIPythonApp.display_banner',
         "Display a banner upon starting IPython.",
         "Don't display a banner upon starting IPython."
 )
 addflag('confirm-exit', 'TerminalInteractiveShell.confirm_exit',
     """Set to confirm when you try to exit IPython with an EOF (Control-D
     in Unix, Control-Z/Enter in Windows). By typing 'exit' or 'quit',
     you can force a direct exit without any confirmation.""",
     "Don't prompt the user when exiting."
 )
 addflag('term-title', 'TerminalInteractiveShell.term_title',
     "Enable auto setting the terminal title.",
     "Disable auto setting the terminal title."
 )
 classic_config = Config()
 classic_config.InteractiveShell.cache_size = 0
 classic_config.PlainTextFormatter.pprint = False
 classic_config.TerminalInteractiveShell.prompts_class='IPython.terminal.prompts.ClassicPrompts'
 classic_config.InteractiveShell.separate_in = ''
 classic_config.InteractiveShell.separate_out = ''
 classic_config.InteractiveShell.separate_out2 = ''
 classic_config.InteractiveShell.colors = 'NoColor'
 classic_config.InteractiveShell.xmode = 'Plain'
 
 frontend_flags['classic']=(
     classic_config,
     "Gives IPython a similar feel to the classic Python prompt."
 )
 # # log doesn't make so much sense this way anymore
 # paa('--log','-l',
 #     action='store_true', dest='InteractiveShell.logstart',
 #     help="Start logging to the default log file (./ipython_log.py).")
 #
 # # quick is harder to implement
 frontend_flags['quick']=(
     {'TerminalIPythonApp' : {'quick' : True}},
     "Enable quick startup with no config files."
 )
 
 frontend_flags['i'] = (
     {'TerminalIPythonApp' : {'force_interact' : True}},
     """If running code from the command line, become interactive afterwards.
     It is often useful to follow this with `--` to treat remaining flags as
     script arguments.
     """
 )
 flags.update(frontend_flags)
 
 aliases = dict(base_aliases)
-aliases.update(shell_aliases)
+aliases.update(shell_aliases)  # type: ignore[arg-type]
 
 #-----------------------------------------------------------------------------
 # Main classes and functions
 #-----------------------------------------------------------------------------
 
 
 class LocateIPythonApp(BaseIPythonApplication):
     description = """print the path to the IPython dir"""
     subcommands = dict(
         profile=('IPython.core.profileapp.ProfileLocate',
             "print the path to an IPython profile directory",
         ),
     )
     def start(self):
         if self.subapp is not None:
             return self.subapp.start()
         else:
             print(self.ipython_dir)
 
 
 class TerminalIPythonApp(BaseIPythonApplication, InteractiveShellApp):
     name = u'ipython'
     description = usage.cl_usage
-    crash_handler_class = IPAppCrashHandler
+    crash_handler_class = IPAppCrashHandler  # typing: ignore[assignment]
     examples = _examples
 
     flags = flags
     aliases = aliases
     classes = List()
 
     interactive_shell_class = Type(
         klass=object,   # use default_value otherwise which only allow subclasses.
         default_value=TerminalInteractiveShell,
         help="Class to use to instantiate the TerminalInteractiveShell object. Useful for custom Frontends"
     ).tag(config=True)
 
     @default('classes')
     def _classes_default(self):
         """This has to be in a method, for TerminalIPythonApp to be available."""
         return [
             InteractiveShellApp, # ShellApp comes before TerminalApp, because
             self.__class__,      # it will also affect subclasses (e.g. QtConsole)
             TerminalInteractiveShell,
             HistoryManager,
             MagicsManager,
             ProfileDir,
             PlainTextFormatter,
             IPCompleter,
             ScriptMagics,
             LoggingMagics,
             StoreMagics,
         ]
 
     subcommands = dict(
         profile = ("IPython.core.profileapp.ProfileApp",
             "Create and manage IPython profiles."
         ),
         kernel = ("ipykernel.kernelapp.IPKernelApp",
             "Start a kernel without an attached frontend."
         ),
         locate=('IPython.terminal.ipapp.LocateIPythonApp',
             LocateIPythonApp.description
         ),
         history=('IPython.core.historyapp.HistoryApp',
             "Manage the IPython history database."
         ),
     )
 
 
     # *do* autocreate requested profile, but don't create the config file.
     auto_create=Bool(True)
     # configurables
     quick = Bool(False,
         help="""Start IPython quickly by skipping the loading of config files."""
     ).tag(config=True)
     @observe('quick')
     def _quick_changed(self, change):
         if change['new']:
             self.load_config_file = lambda *a, **kw: None
 
     display_banner = Bool(True,
         help="Whether to display a banner upon starting IPython."
     ).tag(config=True)
 
     # if there is code of files to run from the cmd line, don't interact
     # unless the --i flag (App.force_interact) is true.
     force_interact = Bool(False,
         help="""If a command or file is given via the command-line,
         e.g. 'ipython foo.py', start an interactive shell after executing the
         file or command."""
     ).tag(config=True)
     @observe('force_interact')
     def _force_interact_changed(self, change):
         if change['new']:
             self.interact = True
 
     @observe('file_to_run', 'code_to_run', 'module_to_run')
     def _file_to_run_changed(self, change):
         new = change['new']
         if new:
             self.something_to_run = True
         if new and not self.force_interact:
                 self.interact = False
 
     # internal, not-configurable
     something_to_run=Bool(False)
 
     @catch_config_error
     def initialize(self, argv=None):
         """Do actions after construct, but before starting the app."""
         super(TerminalIPythonApp, self).initialize(argv)
         if self.subapp is not None:
             # don't bother initializing further, starting subapp
             return
         # print self.extra_args
         if self.extra_args and not self.something_to_run:
             self.file_to_run = self.extra_args[0]
         self.init_path()
         # create the shell
         self.init_shell()
         # and draw the banner
         self.init_banner()
         # Now a variety of things that happen after the banner is printed.
         self.init_gui_pylab()
         self.init_extensions()
         self.init_code()
 
     def init_shell(self):
         """initialize the InteractiveShell instance"""
         # Create an InteractiveShell instance.
         # shell.display_banner should always be False for the terminal
         # based app, because we call shell.show_banner() by hand below
         # so the banner shows *before* all extension loading stuff.
         self.shell = self.interactive_shell_class.instance(parent=self,
                         profile_dir=self.profile_dir,
                         ipython_dir=self.ipython_dir, user_ns=self.user_ns)
         self.shell.configurables.append(self)
 
     def init_banner(self):
         """optionally display the banner"""
         if self.display_banner and self.interact:
             self.shell.show_banner()
         # Make sure there is a space below the banner.
         if self.log_level <= logging.INFO: print()
 
     def _pylab_changed(self, name, old, new):
         """Replace --pylab='inline' with --pylab='auto'"""
         if new == 'inline':
             warnings.warn("'inline' not available as pylab backend, "
                       "using 'auto' instead.")
             self.pylab = 'auto'
 
     def start(self):
         if self.subapp is not None:
             return self.subapp.start()
         # perform any prexec steps:
         if self.interact:
             self.log.debug("Starting IPython's mainloop...")
             self.shell.mainloop()
         else:
             self.log.debug("IPython not interactive...")
             self.shell.restore_term_title()
             if not self.shell.last_execution_succeeded:
                 sys.exit(1)
 
 def load_default_config(ipython_dir=None):
     """Load the default config file from the default ipython_dir.
 
     This is useful for embedded shells.
     """
     if ipython_dir is None:
         ipython_dir = get_ipython_dir()
 
     profile_dir = os.path.join(ipython_dir, 'profile_default')
     app = TerminalIPythonApp()
     app.config_file_paths.append(profile_dir)
     app.load_config_file()
     return app.config
 
 launch_new_instance = TerminalIPythonApp.launch_instance
 
 
 if __name__ == '__main__':
     launch_new_instance()

IPython/terminal/shortcuts/__init__.py

@@ -1,638 +1,638
 """
 Module to define and register Terminal IPython shortcuts with
 :mod:`prompt_toolkit`
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import warnings
 import signal
 import sys
 import re
 import os
 from typing import Callable, Dict, Union
 
 
 from prompt_toolkit.application.current import get_app
 from prompt_toolkit.enums import DEFAULT_BUFFER, SEARCH_BUFFER
 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, auto_suggest
 
 
 __all__ = ["create_ipython_shortcuts"]
 
 
 try:
     # only added in 3.0.30
     from prompt_toolkit.filters import has_suggestion
 except ImportError:
 
     @undoc
     @Condition
     def has_suggestion():
         buffer = get_app().current_buffer
         return buffer.suggestion is not None and buffer.suggestion.text != ""
 
 
 @undoc
 @Condition
 def cursor_in_leading_ws():
     before = get_app().current_buffer.document.current_line_before_cursor
     return (not before) or before.isspace()
 
 
 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, 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):
         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
     )
 
     @Condition
     def ebivim():
         return shell.emacs_bindings_in_vi_insert_mode
 
     @kb.add(
         "escape",
         "enter",
         filter=(has_focus(DEFAULT_BUFFER) & ~has_selection & insert_mode & ebivim),
     )
     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-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-c", filter=has_focus(DEFAULT_BUFFER))(reset_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)
 
     # 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("f2", filter=has_focus(DEFAULT_BUFFER))(open_input_in_editor)
 
     @Condition
     def auto_match():
         return shell.auto_match
 
     def all_quotes_paired(quote, buf):
         paired = True
         i = 0
         while i < len(buf):
             c = buf[i]
             if c == quote:
                 paired = not paired
             elif c == "\\":
                 i += 1
             i += 1
         return paired
 
     focused_insert = (vi_insert_mode | emacs_insert_mode) & has_focus(DEFAULT_BUFFER)
     _preceding_text_cache: Dict[Union[str, Callable], Condition] = {}
     _following_text_cache: Dict[Union[str, Callable], Condition] = {}
 
     def preceding_text(pattern: Union[str, Callable]):
         if pattern in _preceding_text_cache:
             return _preceding_text_cache[pattern]
 
         if callable(pattern):
-
             def _preceding_text():
                 app = get_app()
                 before_cursor = app.current_buffer.document.current_line_before_cursor
-                return bool(pattern(before_cursor))
+                # mypy can't infer if(callable): https://github.com/python/mypy/issues/3603
+                return bool(pattern(before_cursor))  # type: ignore[operator]
 
         else:
             m = re.compile(pattern)
 
             def _preceding_text():
                 app = get_app()
                 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
 
     def following_text(pattern):
         try:
             return _following_text_cache[pattern]
         except KeyError:
             pass
         m = re.compile(pattern)
 
         def _following_text():
             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
 
     @Condition
     def not_inside_unclosed_string():
         app = get_app()
         s = app.current_buffer.document.text_before_cursor
         # remove escaped quotes
         s = s.replace('\\"', "").replace("\\'", "")
         # remove triple-quoted string literals
         s = re.sub(r"(?:\"\"\"[\s\S]*\"\"\"|'''[\s\S]*''')", "", s)
         # remove single-quoted string literals
         s = re.sub(r"""(?:"[^"]*["\n]|'[^']*['\n])""", "", s)
         return not ('"' in s or "'" in s)
 
     # auto match
     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(
         '"',
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(lambda line: all_quotes_paired('"', line))
         & following_text(r"[,)}\]]|$"),
     )(match.double_quote)
 
     kb.add(
         "'",
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(lambda line: all_quotes_paired("'", line))
         & following_text(r"[,)}\]]|$"),
     )(match.single_quote)
 
     kb.add(
         '"',
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(r'^.*""$'),
     )(match.docstring_double_quotes)
 
     kb.add(
         "'",
         filter=focused_insert
         & auto_match
         & not_inside_unclosed_string
         & preceding_text(r"^.*''$"),
     )(match.docstring_single_quotes)
 
     # raw string
     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)
 
     # just move cursor
     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(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
     )
 
     kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\($")
         & auto_match
         & following_text(r"^\)"),
     )(match.delete_pair)
     kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\[$")
         & auto_match
         & following_text(r"^\]"),
     )(match.delete_pair)
     kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*\{$")
         & auto_match
         & following_text(r"^\}"),
     )(match.delete_pair)
     kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text('.*"$')
         & auto_match
         & following_text('^"'),
     )(match.delete_pair)
     kb.add(
         "backspace",
         filter=focused_insert
         & preceding_text(r".*'$")
         & auto_match
         & following_text(r"^'"),
     )(match.delete_pair)
 
     if shell.display_completions == "readlinelike":
         kb.add(
             "c-i",
             filter=(
                 has_focus(DEFAULT_BUFFER)
                 & ~has_selection
                 & insert_mode
                 & ~cursor_in_leading_ws
             ),
         )(display_completions_like_readline)
 
     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
 
     # autosuggestions
     kb.add("end", filter=has_focus(DEFAULT_BUFFER) & (ebivim | ~vi_insert_mode))(
         auto_suggest.accept_in_vi_insert_mode
     )
     kb.add("c-e", filter=focused_insert_vi & ebivim)(
         auto_suggest.accept_in_vi_insert_mode
     )
     kb.add("c-f", filter=focused_insert_vi)(auto_suggest.accept)
     kb.add("escape", "f", filter=focused_insert_vi & ebivim)(auto_suggest.accept_word)
     kb.add("c-right", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.accept_token
     )
     from functools import partial
 
     kb.add("up", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.swap_autosuggestion_up(shell.auto_suggest)
     )
     kb.add("down", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.swap_autosuggestion_down(shell.auto_suggest)
     )
     kb.add("right", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.accept_character
     )
     kb.add("left", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.accept_and_move_cursor_left
     )
     kb.add("c-down", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.accept_and_keep_cursor
     )
     kb.add("backspace", filter=has_suggestion & has_focus(DEFAULT_BUFFER))(
         auto_suggest.backspace_and_resume_hint
     )
 
     # Simple Control keybindings
     key_cmd_dict = {
         "c-a": nc.beginning_of_line,
         "c-b": nc.backward_char,
         "c-k": nc.kill_line,
         "c-w": nc.backward_kill_word,
         "c-y": nc.yank,
         "c-_": nc.undo,
     }
 
     for key, cmd in key_cmd_dict.items():
         kb.add(key, filter=focused_insert_vi & ebivim)(cmd)
 
     # Alt and Combo Control keybindings
     keys_cmd_dict = {
         # Control Combos
         ("c-x", "c-e"): nc.edit_and_execute,
         ("c-x", "e"): nc.edit_and_execute,
         # Alt
         ("escape", "b"): nc.backward_word,
         ("escape", "c"): nc.capitalize_word,
         ("escape", "d"): nc.kill_word,
         ("escape", "h"): nc.backward_kill_word,
         ("escape", "l"): nc.downcase_word,
         ("escape", "u"): nc.uppercase_word,
         ("escape", "y"): nc.yank_pop,
         ("escape", "."): nc.yank_last_arg,
     }
 
     for keys, cmd in keys_cmd_dict.items():
         kb.add(*keys, filter=focused_insert_vi & ebivim)(cmd)
 
     def get_input_mode(self):
         app = get_app()
         app.ttimeoutlen = shell.ttimeoutlen
         app.timeoutlen = shell.timeoutlen
 
         return self._input_mode
 
     def set_input_mode(self, mode):
         shape = {InputMode.NAVIGATION: 2, InputMode.REPLACE: 4}.get(mode, 6)
         cursor = "\x1b[{} q".format(shape)
 
         sys.stdout.write(cursor)
         sys.stdout.flush()
 
         self._input_mode = mode
 
     if shell.editing_mode == "vi" and shell.modal_cursor:
         ViState._input_mode = InputMode.INSERT  # type: ignore
         ViState.input_mode = property(get_input_mode, set_input_mode)  # type: ignore
 
     return kb
 
 
 def reformat_text_before_cursor(buffer, document, shell):
     text = buffer.delete_before_cursor(len(document.text[: document.cursor_position]))
     try:
         formatted_text = shell.reformat_handler(text)
         buffer.insert_text(formatted_text)
     except Exception as e:
         buffer.insert_text(text)
 
 
 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
         d = b.document
 
         if b.complete_state:
             cc = b.complete_state.current_completion
             if cc:
                 b.apply_completion(cc)
             else:
                 b.cancel_completion()
             return
 
         # If there's only one line, treat it as if the cursor is at the end.
         # See https://github.com/ipython/ipython/issues/10425
         if d.line_count == 1:
             check_text = d.text
         else:
             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 :]
         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 shell.autoindent:
                 b.insert_text("\n" + indent)
             else:
                 b.insert_text("\n")
             return
 
         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)
             else:
                 b.insert_text("\n")
 
     newline_or_execute.__qualname__ = "newline_or_execute"
 
     return newline_or_execute
 
 
 def previous_history_or_previous_completion(event):
     """
     Control-P in vi edit mode on readline is history next, unlike default prompt toolkit.
 
     If completer is open this still select previous completion.
     """
     event.current_buffer.auto_up()
 
 
 def next_history_or_next_completion(event):
     """
     Control-N in vi edit mode on readline is history previous, unlike default prompt toolkit.
 
     If completer is open this still select next completion.
     """
     event.current_buffer.auto_down()
 
 
 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()
     else:
         b.reset()
 
 
 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.
     """
     sigquit = getattr(signal, "SIGQUIT", None)
     if sigquit is not None:
         os.kill(0, signal.SIGQUIT)
     else:
         sys.exit("Quit")
 
 
 def indent_buffer(event):
     """Indent buffer"""
     event.current_buffer.insert_text(" " * 4)
 
 
 @undoc
 def newline_with_copy_margin(event):
     """
     DEPRECATED since IPython 6.0
 
     See :any:`newline_autoindent_outer` for a replacement.
 
     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,
     )
 
     b = event.current_buffer
     cursor_start_pos = b.document.cursor_position_col
     b.newline(copy_margin=True)
     b.cursor_up(count=1)
     cursor_end_pos = b.document.cursor_position_col
     if cursor_start_pos != cursor_end_pos:
         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.
 
     Fancier version of deprecated ``newline_with_copy_margin`` which should
     compute the correct indentation of the inserted line. That is to say, indent
     by 4 extra space after a function definition, class definition, context
     manager... And dedent by 4 space after ``pass``, ``return``, ``raise ...``.
     """
 
     def newline_autoindent(event):
         """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"
         _, indent = inputsplitter.check_complete(text)
         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":
     from IPython.core.error import TryNext
     from IPython.lib.clipboard import (
         ClipboardEmpty,
         win32_clipboard_get,
         tkinter_clipboard_get,
     )
 
     @undoc
     def win_paste(event):
         try:
             text = win32_clipboard_get()
         except TryNext:
             try:
                 text = tkinter_clipboard_get()
             except (TryNext, ClipboardEmpty):
                 return
         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

IPython/terminal/shortcuts/auto_suggest.py

@@ -1,287 +1,308
 import re
 import tokenize
 from io import StringIO
-from typing import Callable, List, Optional, Union
+from typing import Callable, List, Optional, Union, Generator, Tuple
 
 from prompt_toolkit.buffer import Buffer
 from prompt_toolkit.key_binding import KeyPressEvent
 from prompt_toolkit.key_binding.bindings import named_commands as nc
 from prompt_toolkit.auto_suggest import AutoSuggestFromHistory, Suggestion
 from prompt_toolkit.document import Document
 from prompt_toolkit.history import History
 from prompt_toolkit.shortcuts import PromptSession
 
 from IPython.utils.tokenutil import generate_tokens
 
 
 def _get_query(document: Document):
     return document.text.rsplit("\n", 1)[-1]
 
 
 class NavigableAutoSuggestFromHistory(AutoSuggestFromHistory):
-    """ """
+    """
+    A subclass of AutoSuggestFromHistory that allow navigation to next/previous
+    suggestion from history. To do so it remembers the current position, but it
+    state need to carefully be cleared on the right events.
+    """
 
     def __init__(
         self,
     ):
         self.skip_lines = 0
         self._connected_apps = []
 
     def reset_history_position(self, _: Buffer):
         self.skip_lines = 0
 
     def disconnect(self):
         for pt_app in self._connected_apps:
             text_insert_event = pt_app.default_buffer.on_text_insert
             text_insert_event.remove_handler(self.reset_history_position)
 
     def connect(self, pt_app: PromptSession):
         self._connected_apps.append(pt_app)
         # note: `on_text_changed` could be used for a bit different behaviour
         # on character deletion (i.e. reseting history position on backspace)
         pt_app.default_buffer.on_text_insert.add_handler(self.reset_history_position)
 
     def get_suggestion(
         self, buffer: Buffer, document: Document
     ) -> Optional[Suggestion]:
         text = _get_query(document)
 
         if text.strip():
             for suggestion, _ in self._find_next_match(
                 text, self.skip_lines, buffer.history
             ):
                 return Suggestion(suggestion)
 
         return None
 
     def _find_match(
         self, text: str, skip_lines: float, history: History, previous: bool
-    ):
+    ) -> Generator[Tuple[str, float], None, None]:
+        """
+        text: str
+
+        skip_lines: float
+            float is used as the base value is +inf
+
+        Yields
+        ------
+        Tuple with:
+        str:
+            current suggestion.
+        float:
+            will actually yield only ints, which is passed back via skip_lines,
+            which may be a +inf (float)
+
+
+        """
         line_number = -1
         for string in reversed(list(history.get_strings())):
             for line in reversed(string.splitlines()):
                 line_number += 1
                 if not previous and line_number < skip_lines:
                     continue
                 # do not return empty suggestions as these
                 # close the auto-suggestion overlay (and are useless)
                 if line.startswith(text) and len(line) > len(text):
                     yield line[len(text) :], line_number
                 if previous and line_number >= skip_lines:
                     return
 
     def _find_next_match(self, text: str, skip_lines: float, history: History):
         return self._find_match(text, skip_lines, history, previous=False)
 
     def _find_previous_match(self, text: str, skip_lines: float, history: History):
         return reversed(
             list(self._find_match(text, skip_lines, history, previous=True))
         )
 
     def up(self, query: str, other_than: str, history: History):
         for suggestion, line_number in self._find_next_match(
             query, self.skip_lines, history
         ):
             # if user has history ['very.a', 'very', 'very.b'] and typed 'very'
             # we want to switch from 'very.b' to 'very.a' because a) if the
             # suggestion equals current text, prompt-toolkit aborts suggesting
             # b) user likely would not be interested in 'very' anyways (they
             # already typed it).
             if query + suggestion != other_than:
                 self.skip_lines = line_number
                 break
         else:
             # no matches found, cycle back to beginning
             self.skip_lines = 0
 
     def down(self, query: str, other_than: str, history: History):
         for suggestion, line_number in self._find_previous_match(
             query, self.skip_lines, history
         ):
             if query + suggestion != other_than:
                 self.skip_lines = line_number
                 break
         else:
             # no matches found, cycle to end
             for suggestion, line_number in self._find_previous_match(
                 query, float("Inf"), history
             ):
                 if query + suggestion != other_than:
                     self.skip_lines = line_number
                     break
 
 
 # Needed for to accept autosuggestions in vi insert mode
 def accept_in_vi_insert_mode(event: KeyPressEvent):
     """Apply autosuggestion if at end of line."""
     buffer = event.current_buffer
     d = buffer.document
     after_cursor = d.text[d.cursor_position :]
     lines = after_cursor.split("\n")
     end_of_current_line = lines[0].strip()
     suggestion = buffer.suggestion
     if (suggestion is not None) and (suggestion.text) and (end_of_current_line == ""):
         buffer.insert_text(suggestion.text)
     else:
         nc.end_of_line(event)
 
 
 def accept(event: KeyPressEvent):
     """Accept autosuggestion"""
     buffer = event.current_buffer
     suggestion = buffer.suggestion
     if suggestion:
         buffer.insert_text(suggestion.text)
     else:
         nc.forward_char(event)
 
 
 def accept_word(event: KeyPressEvent):
     """Fill partial autosuggestion by word"""
     buffer = event.current_buffer
     suggestion = buffer.suggestion
     if suggestion:
         t = re.split(r"(\S+\s+)", suggestion.text)
         buffer.insert_text(next((x for x in t if x), ""))
     else:
         nc.forward_word(event)
 
 
 def accept_character(event: KeyPressEvent):
     """Fill partial autosuggestion by character"""
     b = event.current_buffer
     suggestion = b.suggestion
     if suggestion and suggestion.text:
         b.insert_text(suggestion.text[0])
 
 
 def accept_and_keep_cursor(event: KeyPressEvent):
     """Accept autosuggestion and keep cursor in place"""
     buffer = event.current_buffer
     old_position = buffer.cursor_position
     suggestion = buffer.suggestion
     if suggestion:
         buffer.insert_text(suggestion.text)
         buffer.cursor_position = old_position
 
 
 def accept_and_move_cursor_left(event: KeyPressEvent):
     """Accept autosuggestion and move cursor left in place"""
     accept_and_keep_cursor(event)
     nc.backward_char(event)
 
 
 def backspace_and_resume_hint(event: KeyPressEvent):
     """Resume autosuggestions after deleting last character"""
     current_buffer = event.current_buffer
 
     def resume_hinting(buffer: Buffer):
         if buffer.auto_suggest:
             suggestion = buffer.auto_suggest.get_suggestion(buffer, buffer.document)
             if suggestion:
                 buffer.suggestion = suggestion
         current_buffer.on_text_changed.remove_handler(resume_hinting)
 
     current_buffer.on_text_changed.add_handler(resume_hinting)
     nc.backward_delete_char(event)
 
 
 def accept_token(event: KeyPressEvent):
     """Fill partial autosuggestion by token"""
     b = event.current_buffer
     suggestion = b.suggestion
 
     if suggestion:
         prefix = _get_query(b.document)
         text = prefix + suggestion.text
 
         tokens: List[Optional[str]] = [None, None, None]
         substrings = [""]
         i = 0
 
         for token in generate_tokens(StringIO(text).readline):
             if token.type == tokenize.NEWLINE:
                 index = len(text)
             else:
                 index = text.index(token[1], len(substrings[-1]))
             substrings.append(text[:index])
             tokenized_so_far = substrings[-1]
             if tokenized_so_far.startswith(prefix):
                 if i == 0 and len(tokenized_so_far) > len(prefix):
                     tokens[0] = tokenized_so_far[len(prefix) :]
                     substrings.append(tokenized_so_far)
                     i += 1
                 tokens[i] = token[1]
                 if i == 2:
                     break
                 i += 1
 
         if tokens[0]:
             to_insert: str
             insert_text = substrings[-2]
             if tokens[1] and len(tokens[1]) == 1:
                 insert_text = substrings[-1]
             to_insert = insert_text[len(prefix) :]
             b.insert_text(to_insert)
             return
 
     nc.forward_word(event)
 
 
 Provider = Union[AutoSuggestFromHistory, NavigableAutoSuggestFromHistory, None]
 
 
 def _swap_autosuggestion(
     buffer: Buffer,
     provider: NavigableAutoSuggestFromHistory,
     direction_method: Callable,
 ):
     """
     We skip most recent history entry (in either direction) if it equals the
     current autosuggestion because if user cycles when auto-suggestion is shown
     they most likely want something else than what was suggested (othewrise
     they would have accepted the suggestion).
     """
     suggestion = buffer.suggestion
     if not suggestion:
         return
 
     query = _get_query(buffer.document)
     current = query + suggestion.text
 
     direction_method(query=query, other_than=current, history=buffer.history)
 
     new_suggestion = provider.get_suggestion(buffer, buffer.document)
     buffer.suggestion = new_suggestion
 
 
 def swap_autosuggestion_up(provider: Provider):
     def swap_autosuggestion_up(event: KeyPressEvent):
         """Get next autosuggestion from history."""
         if not isinstance(provider, NavigableAutoSuggestFromHistory):
             return
 
         return _swap_autosuggestion(
             buffer=event.current_buffer, provider=provider, direction_method=provider.up
         )
 
     swap_autosuggestion_up.__name__ = "swap_autosuggestion_up"
     return swap_autosuggestion_up
 
 
 def swap_autosuggestion_down(
     provider: Union[AutoSuggestFromHistory, NavigableAutoSuggestFromHistory, None]
 ):
     def swap_autosuggestion_down(event: KeyPressEvent):
         """Get previous autosuggestion from history."""
         if not isinstance(provider, NavigableAutoSuggestFromHistory):
             return
 
         return _swap_autosuggestion(
             buffer=event.current_buffer,
             provider=provider,
             direction_method=provider.down,
         )
 
     swap_autosuggestion_down.__name__ = "swap_autosuggestion_down"
     return swap_autosuggestion_down