Backport PR #10207: Fix deactivation of embedded instance.

While deactivation of full instances make some sens, the most common
behavior user expect when creating an instance and using
``kill_embedded`` is deactivation of the current call location.

Implement the expected on by default, add options to get previous
behavior, and add flag for direct exit and no-confirm

Fix  9761

IPython/terminal/embed.py

@@ -1,326 +1,395 b''
 # encoding: utf-8
 """
 An embedded IPython shell.
 """
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import with_statement
 from __future__ import print_function
 
 import sys
 import warnings
 
 from IPython.core import ultratb, compilerop
+from IPython.core import magic_arguments
 from IPython.core.magic import Magics, magics_class, line_magic
 from IPython.core.interactiveshell import DummyMod, InteractiveShell
 from IPython.terminal.interactiveshell import TerminalInteractiveShell
 from IPython.terminal.ipapp import load_default_config
 
 from traitlets import Bool, CBool, Unicode
 from IPython.utils.io import ask_yes_no
 
 class KillEmbeded(Exception):pass
 
 # This is an additional magic that is exposed in embedded shells.
 @magics_class
 class EmbeddedMagics(Magics):
 
     @line_magic
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument('-i', '--instance', action='store_true',
+                              help='Kill instance instead of call location')
+    @magic_arguments.argument('-x', '--exit', action='store_true',
+                              help='Also exit the current session')
+    @magic_arguments.argument('-y', '--yes', action='store_true',
+                              help='Do not ask confirmation')
     def kill_embedded(self, parameter_s=''):
-        """%kill_embedded : deactivate for good the current embedded IPython.
+        """%kill_embedded : deactivate for good the current embedded IPython
 
         This function (after asking for confirmation) sets an internal flag so
-        that an embedded IPython will never activate again.  This is useful to
-        permanently disable a shell that is being called inside a loop: once
-        you've figured out what you needed from it, you may then kill it and
-        the program will then continue to run without the interactive shell
-        interfering again.
+        that an embedded IPython will never activate again for the given call
+        location. This is useful to permanently disable a shell that is being
+        called inside a loop: once you've figured out what you needed from it,
+        you may then kill it and the program will then continue to run without
+        the interactive shell interfering again.
+
+
+        Kill Instance Option
+        --------------------
+
+        If for some reasons you need to kill the location where the instance is
+        created and not called, for example if you create a single instance in
+        one place and debug in many locations, you can use the ``--instance``
+        option to kill this specific instance. Like for the ``call location``
+        killing an "instance" should work even if it is recreated within a
+        loop.
+
+        .. note::
+
+            This was the default behavior before IPython 5.2
+
         """
 
-        kill = ask_yes_no("Are you sure you want to kill this embedded instance? [y/N] ",'n')
-        if kill:
-            self.shell.embedded_active = False
-            print ("This embedded IPython will not reactivate anymore "
-                   "once you exit.")
+        args = magic_arguments.parse_argstring(self.kill_embedded, parameter_s)
+        print(args)
+        if args.instance:
+            # let no ask
+            if not args.yes:
+                kill = ask_yes_no(
+                    "Are you sure you want to kill this embedded instance? [y/N] ", 'n')
+            else:
+                kill = True
+            if kill:
+                self.shell._disable_init_location()
+                print("This embedded IPython instance will not reactivate anymore "
+                      "once you exit.")
+        else:
+            if not args.yes:
+                kill = ask_yes_no(
+                    "Are you sure you want to kill this embedded call_location? [y/N] ", 'n')
+            else:
+                kill = True
+            if kill:
+                self.shell.embedded_active = False
+                print("This embedded IPython  call location will not reactivate anymore "
+                      "once you exit.")
+
+        if args.exit:
+            # Ask-exit does not really ask, it just set internals flags to exit
+            # on next loop.
+            self.shell.ask_exit()
 
 
     @line_magic
     def exit_raise(self, parameter_s=''):
         """%exit_raise Make the current embedded kernel exit and raise and exception.
 
         This function sets an internal flag so that an embedded IPython will
         raise a `IPython.terminal.embed.KillEmbeded` Exception on exit, and then exit the current I. This is
         useful to permanently exit a loop that create IPython embed instance.
         """
 
         self.shell.should_raise = True
         self.shell.ask_exit()
 
 
 
 class InteractiveShellEmbed(TerminalInteractiveShell):
 
     dummy_mode = Bool(False)
     exit_msg = Unicode('')
     embedded = CBool(True)
     should_raise = CBool(False)
     # Like the base class display_banner is not configurable, but here it
     # is True by default.
     display_banner = CBool(True)
     exit_msg = Unicode()
 
     # When embedding, by default we don't change the terminal title
     term_title = Bool(False,
         help="Automatically set the terminal title"
     ).tag(config=True)
 
     _inactive_locations = set()
 
     @property
     def embedded_active(self):
-        return self._call_location_id not in InteractiveShellEmbed._inactive_locations
+        return (self._call_location_id not in InteractiveShellEmbed._inactive_locations)\
+            and (self._init_location_id not in InteractiveShellEmbed._inactive_locations)
+
+    def _disable_init_location(self):
+        """Disable the current Instance creation location"""
+        InteractiveShellEmbed._inactive_locations.add(self._init_location_id)
 
     @embedded_active.setter
     def embedded_active(self, value):
-        if value :
-            if self._call_location_id in InteractiveShellEmbed._inactive_locations:
-                InteractiveShellEmbed._inactive_locations.remove(self._call_location_id)
+        if value:
+            InteractiveShellEmbed._inactive_locations.discard(
+                self._call_location_id)
+            InteractiveShellEmbed._inactive_locations.discard(
+                self._init_location_id)
         else:
-            InteractiveShellEmbed._inactive_locations.add(self._call_location_id)
+            InteractiveShellEmbed._inactive_locations.add(
+                self._call_location_id)
 
     def __init__(self, **kw):
-        
-    
         if kw.get('user_global_ns', None) is not None:
-            raise DeprecationWarning("Key word argument `user_global_ns` has been replaced by `user_module` since IPython 4.0.")
+            raise DeprecationWarning(
+                "Key word argument `user_global_ns` has been replaced by `user_module` since IPython 4.0.")
 
-        self._call_location_id =  kw.pop('_call_location_id', None)
+        clid = kw.pop('_init_location_id', None)
+        if not clid:
+            frame = sys._getframe(1)
+            clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
+        self._init_location_id = clid
 
         super(InteractiveShellEmbed,self).__init__(**kw)
 
-        if not self._call_location_id:
-            frame = sys._getframe(1)
-            self._call_location_id = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
         # don't use the ipython crash handler so that user exceptions aren't
         # trapped
         sys.excepthook = ultratb.FormattedTB(color_scheme=self.colors,
                                              mode=self.xmode,
                                              call_pdb=self.pdb)
 
     def init_sys_modules(self):
+        """
+        Explicitly overwrite :any:`IPython.core.interactiveshell` to do nothing.
+        """
         pass
 
     def init_magics(self):
         super(InteractiveShellEmbed, self).init_magics()
         self.register_magics(EmbeddedMagics)
 
     def __call__(self, header='', local_ns=None, module=None, dummy=None,
-                 stack_depth=1, global_ns=None, compile_flags=None):
+                 stack_depth=1, global_ns=None, compile_flags=None, **kw):
         """Activate the interactive interpreter.
 
         __call__(self,header='',local_ns=None,module=None,dummy=None) -> Start
         the interpreter shell with the given local and global namespaces, and
         optionally print a header string at startup.
 
         The shell can be globally activated/deactivated using the
         dummy_mode attribute. This allows you to turn off a shell used
         for debugging globally.
 
         However, *each* time you call the shell you can override the current
         state of dummy_mode with the optional keyword parameter 'dummy'. For
         example, if you set dummy mode on with IPShell.dummy_mode = True, you
         can still have a specific call work by making it as IPShell(dummy=False).
         """
 
+        # we are called, set the underlying interactiveshell not to exit.
+        self.keep_running = True
+
         # If the user has turned it off, go away
+        clid = kw.pop('_call_location_id', None)
+        if not clid:
+            frame = sys._getframe(1)
+            clid = '%s:%s' % (frame.f_code.co_filename, frame.f_lineno)
+        self._call_location_id = clid
+
         if not self.embedded_active:
             return
 
         # Normal exits from interactive mode set this flag, so the shell can't
         # re-enter (it checks this variable at the start of interactive mode).
         self.exit_now = False
 
         # Allow the dummy parameter to override the global __dummy_mode
         if dummy or (dummy != 0 and self.dummy_mode):
             return
 
         # self.banner is auto computed
         if header:
             self.old_banner2 = self.banner2
             self.banner2 = self.banner2 + '\n' + header + '\n'
         else:
             self.old_banner2 = ''
 
         if self.display_banner:
             self.show_banner()
 
         # Call the embedding code with a stack depth of 1 so it can skip over
         # our call and get the original caller's namespaces.
         self.mainloop(local_ns, module, stack_depth=stack_depth,
                       global_ns=global_ns, compile_flags=compile_flags)
 
         self.banner2 = self.old_banner2
 
         if self.exit_msg is not None:
             print(self.exit_msg)
 
         if self.should_raise:
             raise KillEmbeded('Embedded IPython raising error, as user requested.')
 
 
     def mainloop(self, local_ns=None, module=None, stack_depth=0,
                  display_banner=None, global_ns=None, compile_flags=None):
         """Embeds IPython into a running python program.
 
         Parameters
         ----------
 
         local_ns, module
           Working local namespace (a dict) and module (a module or similar
           object). If given as None, they are automatically taken from the scope
           where the shell was called, so that program variables become visible.
 
         stack_depth : int
           How many levels in the stack to go to looking for namespaces (when
           local_ns or module is None). This allows an intermediate caller to
           make sure that this function gets the namespace from the intended
           level in the stack. By default (0) it will get its locals and globals
           from the immediate caller.
 
         compile_flags
           A bit field identifying the __future__ features
           that are enabled, as passed to the builtin :func:`compile` function.
           If given as None, they are automatically taken from the scope where
           the shell was called.
 
         """
         
         if (global_ns is not None) and (module is None):
             raise DeprecationWarning("'global_ns' keyword argument is deprecated, and has been removed in IPython 5.0 use `module` keyword argument instead.")
 
         if (display_banner is not None):
             warnings.warn("The display_banner parameter is deprecated since IPython 4.0", DeprecationWarning)
 
         # Get locals and globals from caller
         if ((local_ns is None or module is None or compile_flags is None)
             and self.default_user_namespaces):
             call_frame = sys._getframe(stack_depth).f_back
 
             if local_ns is None:
                 local_ns = call_frame.f_locals
             if module is None:
                 global_ns = call_frame.f_globals
                 try:
                     module = sys.modules[global_ns['__name__']]
                 except KeyError:
                     warnings.warn("Failed to get module %s" % \
                         global_ns.get('__name__', 'unknown module')
                     )
                     module = DummyMod()
                     module.__dict__ = global_ns
             if compile_flags is None:
                 compile_flags = (call_frame.f_code.co_flags &
                                  compilerop.PyCF_MASK)
         
         # Save original namespace and module so we can restore them after 
         # embedding; otherwise the shell doesn't shut down correctly.
         orig_user_module = self.user_module
         orig_user_ns = self.user_ns
         orig_compile_flags = self.compile.flags
         
         # Update namespaces and fire up interpreter
         
         # The global one is easy, we can just throw it in
         if module is not None:
             self.user_module = module
 
         # But the user/local one is tricky: ipython needs it to store internal
         # data, but we also need the locals. We'll throw our hidden variables
         # like _ih and get_ipython() into the local namespace, but delete them
         # later.
         if local_ns is not None:
             reentrant_local_ns = {k: v for (k, v) in local_ns.items() if k not in self.user_ns_hidden.keys()}
             self.user_ns = reentrant_local_ns
             self.init_user_ns()
 
         # Compiler flags
         if compile_flags is not None:
             self.compile.flags = compile_flags
 
         # make sure the tab-completer has the correct frame information, so it
         # actually completes using the frame's locals/globals
         self.set_completer_frame()
 
         with self.builtin_trap, self.display_trap:
             self.interact()
         
         # now, purge out the local namespace of IPython's hidden variables.
         if local_ns is not None:
             local_ns.update({k: v for (k, v) in self.user_ns.items() if k not in self.user_ns_hidden.keys()})
 
         
         # Restore original namespace so shell can shut down when we exit.
         self.user_module = orig_user_module
         self.user_ns = orig_user_ns
         self.compile.flags = orig_compile_flags
 
 
 def embed(**kwargs):
     """Call this to embed IPython at the current point in your program.
 
     The first invocation of this will create an :class:`InteractiveShellEmbed`
     instance and then call it.  Consecutive calls just call the already
     created instance.
 
     If you don't want the kernel to initialize the namespace
     from the scope of the surrounding function,
     and/or you want to load full IPython configuration,
     you probably want `IPython.start_ipython()` instead.
 
     Here is a simple example::
 
         from IPython import embed
         a = 10
         b = 20
         embed(header='First time')
         c = 30
         d = 40
         embed()
 
     Full customization can be done by passing a :class:`Config` in as the
     config argument.
     """
     config = kwargs.get('config')
     header = kwargs.pop('header', u'')
     compile_flags = kwargs.pop('compile_flags', None)
     if config is None:
         config = load_default_config()
         config.InteractiveShellEmbed = config.TerminalInteractiveShell
         kwargs['config'] = config
     #save ps1/ps2 if defined
     ps1 = None
     ps2 = None
     try:
         ps1 = sys.ps1
         ps2 = sys.ps2
     except AttributeError:
         pass
     #save previous instance
     saved_shell_instance = InteractiveShell._instance
     if saved_shell_instance is not None:
         cls = type(saved_shell_instance)
         cls.clear_instance()
     frame = sys._getframe(1)
-    shell = InteractiveShellEmbed.instance(_call_location_id='%s:%s' % (frame.f_code.co_filename, frame.f_lineno), **kwargs)
-    shell(header=header, stack_depth=2, compile_flags=compile_flags)
+    shell = InteractiveShellEmbed.instance(_init_location_id='%s:%s' % (
+        frame.f_code.co_filename, frame.f_lineno), **kwargs)
+    shell(header=header, stack_depth=2, compile_flags=compile_flags,
+          _call_location_id='%s:%s' % (frame.f_code.co_filename, frame.f_lineno))
     InteractiveShellEmbed.clear_instance()
     #restore previous instance
     if saved_shell_instance is not None:
         cls = type(saved_shell_instance)
         cls.clear_instance()
         for subclass in cls._walk_mro():
             subclass._instance = saved_shell_instance
     if ps1 is not None:
         sys.ps1 = ps1
         sys.ps2 = ps2

docs/source/whatsnew/version5.rst

@@ -1,230 +1,247 b''
 ============
  5.x Series
 ============
 
 
 IPython 5.2
 ===========
 
 Remarkable changes and fixes:
 
 * restore IPython's debugger to raise on quit. :ghpull:`10009`
 * The configuration value ``c.TerminalInteractiveShell.highlighting_style`` can
   now directly take a class argument for custom color style. :ghpull:`9848`
 * Correctly handle matplotlib figures dpi :ghpull:`9868`
 * Deprecate ``-e`` flag for the ``%notebook`` magic that had no effects.
   :ghpull:`9872`
 * You can now press F2 while typing at a terminal prompt to edit the contents
   in your favourite terminal editor. Set the :envvar:`EDITOR` environment
   variable to pick which editor is used. :ghpull:`9929`
 * sdists will now only be ``.tar.gz`` as per upstream PyPI requirements.
   :ghpull:`9925`
 * :any:`IPython.core.debugger` have gained a ``set_trace()`` method for
   convenience. :ghpull:`9947`
 * The 'smart command mode' added to the debugger in 5.0 was removed, as more
   people preferred the previous behaviour. Therefore, debugger commands such as
   ``c`` will act as debugger commands even when ``c`` is defined as a variable.
   :ghpull:`10050`
 * Fixes OS X event loop issues at startup, :ghpull:`10150`
 * Deprecate the ``%autoindent`` magic. :ghpull:`10176`
 * Emit a :any:`DeprecationWarning` when setting the deprecated
   ``limit_to_all`` option of the completer. :ghpull:`10198`
 
 
+Changes of behavior to :any:`InteractiveShellEmbed`.
+
+:any:`InteractiveShellEmbed` interactive behavior have changed a bit in between
+5.1 and 5.2. By default ``%kill_embedded`` magic will prevent further invocation
+of the current ``call location`` instead of preventing further invocation of
+the current instance creation location. For most use case this will not change
+much for you, though previous behavior was confusing and less consistent with
+previous IPython versions.
+
+You can now deactivate instances by using ``%kill_embedded --instance`` flag,
+(or ``-i`` in short). The ``%kill_embedded`` magic also gained a
+``--yes``/``-y`` option which skip confirmation step, and  ``-x``/``--exit``
+which also exit the current embedded call without asking for confirmation.
+
+See :ghpull:`10207`.
+
+
 
 IPython 5.1
 ===========
 
 * Broken ``%timeit`` on Python2 due to the use of ``__qualname__``. :ghpull:`9804`
 * Restore ``%gui qt`` to create and return a ``QApplication`` if necessary. :ghpull:`9789`
 * Don't set terminal title by default. :ghpull:`9801`
 * Preserve indentation when inserting newlines with ``Ctrl-O``. :ghpull:`9770`
 * Restore completion in debugger. :ghpull:`9785`
 * Deprecate ``IPython.core.debugger.Tracer()`` in favor of simpler, newer, APIs. :ghpull:`9731`
 * Restore ``NoOpContext`` context manager removed by mistake, and add `DeprecationWarning`. :ghpull:`9765`
 * Add option allowing ``Prompt_toolkit`` to use 24bits colors. :ghpull:`9736`
 * Fix for closing interactive matplotlib windows on OS X. :ghpull:`9854`
 * An embedded interactive shell instance can be used more than once. :ghpull:`9843`
 * More robust check for whether IPython is in a terminal. :ghpull:`9833`
 * Better pretty-printing of dicts on PyPy. :ghpull:`9827`
 * Some coloured output now looks better on dark background command prompts in Windows.
   :ghpull:`9838`
 * Improved tab completion of paths on Windows . :ghpull:`9826`
 * Fix tkinter event loop integration on Python 2 with ``future`` installed. :ghpull:`9824`
 * Restore ``Ctrl-\`` as a shortcut to quit IPython.
 * Make ``get_ipython()`` accessible when modules are imported by startup files. :ghpull:`9818`
 * Add support for running directories containing a ``__main__.py`` file with the
   ``ipython`` command. :ghpull:`9813`
 
 
 True Color feature
 ------------------
 
 ``prompt_toolkit`` uses pygments styles for syntax highlighting. By default, the
 colors specified in the style are approximated using a standard 256-color
 palette. ``prompt_toolkit`` also supports 24bit, a.k.a. "true", a.k.a. 16-million
 color escape sequences which enable compatible terminals to display the exact
 colors specified instead of an approximation. This true_color option exposes
 that capability in prompt_toolkit to the IPython shell.
 
 Here is a good source for the current state of true color support in various
 terminal emulators and software projects: https://gist.github.com/XVilka/8346728
 
 
 
 IPython 5.0
 ===========
 
 Released July 7, 2016
 
 New terminal interface
 ----------------------
 
 IPython 5 features a major upgrade to the terminal interface, bringing live
 syntax highlighting as you type, proper multiline editing and multiline paste,
 and tab completions that don't clutter up your history.
 
 .. image:: ../_images/ptshell_features.png
     :alt: New terminal interface features
     :align: center
     :target: ../_images/ptshell_features.png
 
 These features are provided by the Python library `prompt_toolkit
 <http://python-prompt-toolkit.readthedocs.io/en/stable/>`__, which replaces
 ``readline`` throughout our terminal interface.
 
 Relying on this pure-Python, cross platform module also makes it simpler to
 install IPython. We have removed dependencies on ``pyreadline`` for Windows and
 ``gnureadline`` for Mac.
 
 Backwards incompatible changes
 ------------------------------
 
 - The ``%install_ext`` magic function, deprecated since 4.0, has now been deleted.
   You can distribute and install extensions as packages on PyPI.
 - Callbacks registered while an event is being handled will now only be called
   for subsequent events; previously they could be called for the current event.
   Similarly, callbacks removed while handling an event *will* always get that
   event. See :ghissue:`9447` and :ghpull:`9453`.
 - Integration with pydb has been removed since pydb development has been stopped
   since 2012, and pydb is not installable from PyPI.
 - The ``autoedit_syntax`` option has apparently been broken for many years.
   It has been removed.
 
 New terminal interface
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The overhaul of the terminal interface will probably cause a range of minor
 issues for existing users.
 This is inevitable for such a significant change, and we've done our best to
 minimise these issues.
 Some changes that we're aware of, with suggestions on how to handle them:
 
 IPython no longer uses readline configuration (``~/.inputrc``). We hope that
 the functionality you want (e.g. vi input mode) will be available by configuring
 IPython directly (see :doc:`/config/options/terminal`).
 If something's missing, please file an issue.
 
 The ``PromptManager`` class has been removed, and the prompt machinery simplified.
 See :ref:`custom_prompts` to customise prompts with the new machinery.
 
 :mod:`IPython.core.debugger` now provides a plainer interface.
 :mod:`IPython.terminal.debugger` contains the terminal debugger using
 prompt_toolkit.
 
 There are new options to configure the colours used in syntax highlighting.
 We have tried to integrate them with our classic  ``--colors`` option and
 ``%colors`` magic, but there's a mismatch in possibilities, so some configurations
 may produce unexpected results. See :ref:`termcolour` for more information.
 
 The new interface is not compatible with Emacs 'inferior-shell' feature. To
 continue using this, add the ``--simple-prompt`` flag to the command Emacs
 runs. This flag disables most IPython features, relying on Emacs to provide
 things like tab completion.
 
 Provisional Changes
 -------------------
 
 Provisional changes are experimental functionality that may, or may not, make
 it into a future version of IPython, and which API may change without warnings.
 Activating these features and using these API are at your own risk, and may have
 security implication for your system, especially if used with the Jupyter notebook,
 
 When running via the Jupyter notebook interfaces, or other compatible client,
 you can enable rich documentation experimental functionality:
 
 When the ``docrepr`` package is installed setting the boolean flag
 ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various
 object through sphinx before displaying them (see the ``docrepr`` package
 documentation for more information.
 
 You need to also enable the IPython pager display rich HTML representation
 using the ``InteractiveShell.enable_html_pager`` boolean configuration option.
 As usual you can set these configuration options globally in your configuration
 files, alternatively you can turn them on dynamically using the following
 snippet:
 
 .. code-block:: python
 
     ip = get_ipython()
     ip.sphinxify_docstring = True
     ip.enable_html_pager = True
 
 
 You can test the effect of various combinations of the above configuration in
 the Jupyter notebook, with things example like :
 
 .. code-block:: ipython
 
     import numpy as np
     np.histogram?
 
 
 This is part of an effort to make Documentation in Python richer and provide in
 the long term if possible dynamic examples that can contain math, images,
 widgets... As stated above this is nightly experimental feature with a lot of
 (fun) problem to solve. We would be happy to get your feedback and expertise on
 it.
 
 
 
 Deprecated Features
 -------------------
 
 Some deprecated features are listed in this section. Don't forget to enable
 ``DeprecationWarning`` as an error if you are using IPython in a Continuous
 Integration setup or in your testing in general:
 
 .. code-block:: python
 
     import warnings
     warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*')
 
 
 - ``hooks.fix_error_editor`` seems unused and is pending deprecation.
 - `IPython/core/excolors.py:ExceptionColors` is  deprecated.
 - `IPython.core.InteractiveShell:write()` is deprecated; use `sys.stdout` instead.
 - `IPython.core.InteractiveShell:write_err()` is deprecated; use `sys.stderr` instead.
 - The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has no effect.
 - The `global_ns` keyword argument of IPython Embed was deprecated, and has no effect. Use `module` keyword argument instead.
 
 
 Known Issues:
 -------------
 
 - ``<Esc>`` Key does not dismiss the completer and does not clear the current
   buffer. This is an on purpose modification due to current technical
   limitation. Cf :ghpull:`9572`. Escape the control character which is used
   for other shortcut, and there is no practical way to distinguish. Use Ctr-G
   or Ctrl-C as an alternative.
 
 - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf
   :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to
   distinguish these key sequences from a normal new line return.
 
 - ``PageUp`` and ``pageDown`` do not move through completion menu.
 
 - Color styles might not adapt to terminal emulator themes. This will need new
   version of Pygments to be released, and can be mitigated with custom themes.