Add tests for resolving backend name and gui loop

IPython/core/display_functions.py

@@ -1,391 +1,391 b''
 # -*- coding: utf-8 -*-
 """Top-level display functions for displaying object in different formats."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 from binascii import b2a_hex
 import os
 import sys
 import warnings
 
 __all__ = ['display', 'clear_output', 'publish_display_data', 'update_display', 'DisplayHandle']
 
 #-----------------------------------------------------------------------------
 # utility functions
 #-----------------------------------------------------------------------------
 
 
 def _merge(d1, d2):
     """Like update, but merges sub-dicts instead of clobbering at the top level.
 
     Updates d1 in-place
     """
 
     if not isinstance(d2, dict) or not isinstance(d1, dict):
         return d2
     for key, value in d2.items():
         d1[key] = _merge(d1.get(key), value)
     return d1
 
 
 #-----------------------------------------------------------------------------
 # Main functions
 #-----------------------------------------------------------------------------
 
 class _Sentinel:
     def __repr__(self):
         return "<deprecated>"
 
 
 _sentinel = _Sentinel()
 
 # use * to indicate transient is keyword-only
 def publish_display_data(
     data, metadata=None, source=_sentinel, *, transient=None, **kwargs
 ):
     """Publish data and metadata to all frontends.
 
     See the ``display_data`` message in the messaging documentation for
     more details about this message type.
 
     Keys of data and metadata can be any mime-type.
 
     Parameters
     ----------
     data : dict
         A dictionary having keys that are valid MIME types (like
         'text/plain' or 'image/svg+xml') and values that are the data for
         that MIME type. The data itself must be a JSON'able data
         structure. Minimally all data should have the 'text/plain' data,
         which can be displayed by all frontends. If more than the plain
         text is given, it is up to the frontend to decide which
         representation to use.
     metadata : dict
         A dictionary for metadata related to the data. This can contain
         arbitrary key, value pairs that frontends can use to interpret
         the data. mime-type keys matching those in data can be used
         to specify metadata about particular representations.
     source : str, deprecated
         Unused.
     transient : dict, keyword-only
         A dictionary of transient data, such as display_id.
     """
     from IPython.core.interactiveshell import InteractiveShell
 
     if source is not _sentinel:
         warnings.warn(
             "The `source` parameter emit a  deprecation warning since"
             " IPython 8.0, it had no effects for a long time and will "
             " be removed in future versions.",
             DeprecationWarning,
             stacklevel=2,
         )
     display_pub = InteractiveShell.instance().display_pub
 
     # only pass transient if supplied,
     # to avoid errors with older ipykernel.
     # TODO: We could check for ipykernel version and provide a detailed upgrade message.
     if transient:
         kwargs['transient'] = transient
 
     display_pub.publish(
         data=data,
         metadata=metadata,
         **kwargs
     )
 
 
 def _new_id():
     """Generate a new random text id with urandom"""
     return b2a_hex(os.urandom(16)).decode('ascii')
 
 
 def display(
     *objs,
     include=None,
     exclude=None,
     metadata=None,
     transient=None,
     display_id=None,
     raw=False,
     clear=False,
-    **kwargs
+    **kwargs,
 ):
     """Display a Python object in all frontends.
 
     By default all representations will be computed and sent to the frontends.
     Frontends can decide which representation is used and how.
 
     In terminal IPython this will be similar to using :func:`print`, for use in richer
     frontends see Jupyter notebook examples with rich display logic.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display.
     raw : bool, optional
         Are the objects to be displayed already mimetype-keyed dicts of raw display data,
         or Python objects that need to be formatted before display? [default: False]
     include : list, tuple or set, optional
         A list of format type strings (MIME types) to include in the
         format data dict. If this is set *only* the format types included
         in this list will be computed.
     exclude : list, tuple or set, optional
         A list of format type strings (MIME types) to exclude in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     metadata : dict, optional
         A dictionary of metadata to associate with the output.
         mime-type keys in this dictionary will be associated with the individual
         representation formats, if they exist.
     transient : dict, optional
         A dictionary of transient data to associate with the output.
         Data in this dict should not be persisted to files (e.g. notebooks).
     display_id : str, bool optional
         Set an id for the display.
         This id can be used for updating this display area later via update_display.
         If given as `True`, generate a new `display_id`
     clear : bool, optional
         Should the output area be cleared before displaying anything? If True,
         this will wait for additional output before clearing. [default: False]
     **kwargs : additional keyword-args, optional
         Additional keyword-arguments are passed through to the display publisher.
 
     Returns
     -------
     handle: DisplayHandle
         Returns a handle on updatable displays for use with :func:`update_display`,
         if `display_id` is given. Returns :any:`None` if no `display_id` is given
         (default).
 
     Examples
     --------
     >>> class Json(object):
     ...     def __init__(self, json):
     ...         self.json = json
     ...     def _repr_pretty_(self, pp, cycle):
     ...         import json
     ...         pp.text(json.dumps(self.json, indent=2))
     ...     def __repr__(self):
     ...         return str(self.json)
     ...
 
     >>> d = Json({1:2, 3: {4:5}})
 
     >>> print(d)
     {1: 2, 3: {4: 5}}
 
     >>> display(d)
     {
       "1": 2,
       "3": {
         "4": 5
       }
     }
 
     >>> def int_formatter(integer, pp, cycle):
     ...     pp.text('I'*integer)
 
     >>> plain = get_ipython().display_formatter.formatters['text/plain']
     >>> plain.for_type(int, int_formatter)
     <function _repr_pprint at 0x...>
     >>> display(7-5)
     II
 
     >>> del plain.type_printers[int]
     >>> display(7-5)
     2
 
     See Also
     --------
     :func:`update_display`
 
     Notes
     -----
     In Python, objects can declare their textual representation using the
     `__repr__` method. IPython expands on this idea and allows objects to declare
     other, rich representations including:
 
       - HTML
       - JSON
       - PNG
       - JPEG
       - SVG
       - LaTeX
 
     A single object can declare some or all of these representations; all are
     handled by IPython's display system.
 
     The main idea of the first approach is that you have to implement special
     display methods when you define your class, one for each representation you
     want to use. Here is a list of the names of the special methods and the
     values they must return:
 
       - `_repr_html_`: return raw HTML as a string, or a tuple (see below).
       - `_repr_json_`: return a JSONable dict, or a tuple (see below).
       - `_repr_jpeg_`: return raw JPEG data, or a tuple (see below).
       - `_repr_png_`: return raw PNG data, or a tuple (see below).
       - `_repr_svg_`: return raw SVG data as a string, or a tuple (see below).
       - `_repr_latex_`: return LaTeX commands in a string surrounded by "$",
                         or a tuple (see below).
       - `_repr_mimebundle_`: return a full mimebundle containing the mapping
                              from all mimetypes to data.
                              Use this for any mime-type not listed above.
 
     The above functions may also return the object's metadata alonside the
     data.  If the metadata is available, the functions will return a tuple
     containing the data and metadata, in that order.  If there is no metadata
     available, then the functions will return the data only.
 
     When you are directly writing your own classes, you can adapt them for
     display in IPython by following the above approach. But in practice, you
     often need to work with existing classes that you can't easily modify.
 
     You can refer to the documentation on integrating with the display system in
     order to register custom formatters for already existing types
     (:ref:`integrating_rich_display`).
 
     .. versionadded:: 5.4 display available without import
     .. versionadded:: 6.1 display available without import
 
     Since IPython 5.4 and 6.1 :func:`display` is automatically made available to
     the user without import. If you are using display in a document that might
     be used in a pure python context or with older version of IPython, use the
     following import at the top of your file::
 
         from IPython.display import display
 
     """
     from IPython.core.interactiveshell import InteractiveShell
 
     if not InteractiveShell.initialized():
         # Directly print objects.
         print(*objs)
         return
 
     if transient is None:
         transient = {}
     if metadata is None:
         metadata={}
     if display_id:
         if display_id is True:
             display_id = _new_id()
         transient['display_id'] = display_id
     if kwargs.get('update') and 'display_id' not in transient:
         raise TypeError('display_id required for update_display')
     if transient:
         kwargs['transient'] = transient
 
     if not objs and display_id:
         # if given no objects, but still a request for a display_id,
         # we assume the user wants to insert an empty output that
         # can be updated later
         objs = [{}]
         raw = True
 
     if not raw:
         format = InteractiveShell.instance().display_formatter.format
 
     if clear:
         clear_output(wait=True)
 
     for obj in objs:
         if raw:
             publish_display_data(data=obj, metadata=metadata, **kwargs)
         else:
             format_dict, md_dict = format(obj, include=include, exclude=exclude)
             if not format_dict:
                 # nothing to display (e.g. _ipython_display_ took over)
                 continue
             if metadata:
                 # kwarg-specified metadata gets precedence
                 _merge(md_dict, metadata)
             publish_display_data(data=format_dict, metadata=md_dict, **kwargs)
     if display_id:
         return DisplayHandle(display_id)
 
 
 # use * for keyword-only display_id arg
 def update_display(obj, *, display_id, **kwargs):
     """Update an existing display by id
 
     Parameters
     ----------
     obj
         The object with which to update the display
     display_id : keyword-only
         The id of the display to update
 
     See Also
     --------
     :func:`display`
     """
     kwargs['update'] = True
     display(obj, display_id=display_id, **kwargs)
 
 
 class DisplayHandle(object):
     """A handle on an updatable display
 
     Call `.update(obj)` to display a new object.
 
     Call `.display(obj`) to add a new instance of this display,
     and update existing instances.
 
     See Also
     --------
 
         :func:`display`, :func:`update_display`
 
     """
 
     def __init__(self, display_id=None):
         if display_id is None:
             display_id = _new_id()
         self.display_id = display_id
 
     def __repr__(self):
         return "<%s display_id=%s>" % (self.__class__.__name__, self.display_id)
 
     def display(self, obj, **kwargs):
         """Make a new display with my id, updating existing instances.
 
         Parameters
         ----------
         obj
             object to display
         **kwargs
             additional keyword arguments passed to display
         """
         display(obj, display_id=self.display_id, **kwargs)
 
     def update(self, obj, **kwargs):
         """Update existing displays with my id
 
         Parameters
         ----------
         obj
             object to display
         **kwargs
             additional keyword arguments passed to update_display
         """
         update_display(obj, display_id=self.display_id, **kwargs)
 
 
 def clear_output(wait=False):
     """Clear the output of the current cell receiving output.
 
     Parameters
     ----------
     wait : bool [default: false]
         Wait to clear the output until new output is available to replace it."""
     from IPython.core.interactiveshell import InteractiveShell
     if InteractiveShell.initialized():
         InteractiveShell.instance().display_pub.clear_output(wait)
     else:
         print('\033[2K\r', end='')
         sys.stdout.flush()
         print('\033[2K\r', end='')
         sys.stderr.flush()

IPython/core/tests/test_pylabtools.py

@@ -1,270 +1,354 b''
 """Tests for pylab tools module.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 from binascii import a2b_base64
 from io import BytesIO
 
 import pytest
 
 matplotlib = pytest.importorskip("matplotlib")
 matplotlib.use('Agg')
 from matplotlib.figure import Figure
 
 from matplotlib import pyplot as plt
 from matplotlib_inline import backend_inline
 import numpy as np
 
 from IPython.core.getipython import get_ipython
 from IPython.core.interactiveshell import InteractiveShell
 from IPython.core.display import _PNG, _JPEG
 from .. import pylabtools as pt
 
 from IPython.testing import decorators as dec
 
 
 def test_figure_to_svg():
     # simple empty-figure test
     fig = plt.figure()
     assert pt.print_figure(fig, "svg") is None
 
     plt.close('all')
 
     # simple check for at least svg-looking output
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
     svg = pt.print_figure(fig, "svg")[:100].lower()
     assert "doctype svg" in svg
 
 
 def _check_pil_jpeg_bytes():
     """Skip if PIL can't write JPEGs to BytesIO objects"""
     # PIL's JPEG plugin can't write to BytesIO objects
     # Pillow fixes this
     from PIL import Image
     buf = BytesIO()
     img = Image.new("RGB", (4,4))
     try:
         img.save(buf, 'jpeg')
     except Exception as e:
         ename = e.__class__.__name__
         raise pytest.skip("PIL can't write JPEG to BytesIO: %s: %s" % (ename, e)) from e
 
 @dec.skip_without("PIL.Image")
 def test_figure_to_jpeg():
     _check_pil_jpeg_bytes()
     # simple check for at least jpeg-looking output
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
     jpeg = pt.print_figure(fig, 'jpeg', pil_kwargs={'optimize': 50})[:100].lower()
     assert jpeg.startswith(_JPEG)
 
 def test_retina_figure():
     # simple empty-figure test
     fig = plt.figure()
     assert pt.retina_figure(fig) == None
     plt.close('all')
 
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
     png, md = pt.retina_figure(fig)
     assert png.startswith(_PNG)
     assert "width" in md
     assert "height" in md
 
 
 _fmt_mime_map = {
     'png': 'image/png',
     'jpeg': 'image/jpeg',
     'pdf': 'application/pdf',
     'retina': 'image/png',
     'svg': 'image/svg+xml',
 }
 
 def test_select_figure_formats_str():
     ip = get_ipython()
     for fmt, active_mime in _fmt_mime_map.items():
         pt.select_figure_formats(ip, fmt)
         for mime, f in ip.display_formatter.formatters.items():
             if mime == active_mime:
                 assert Figure in f
             else:
                 assert Figure not in f
 
 def test_select_figure_formats_kwargs():
     ip = get_ipython()
     kwargs = dict(bbox_inches="tight")
     pt.select_figure_formats(ip, "png", **kwargs)
     formatter = ip.display_formatter.formatters["image/png"]
     f = formatter.lookup_by_type(Figure)
     cell = f.keywords
     expected = kwargs
     expected["base64"] = True
     expected["fmt"] = "png"
     assert cell == expected
 
     # check that the formatter doesn't raise
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
     formatter.enabled = True
     png = formatter(fig)
     assert isinstance(png, str)
     png_bytes = a2b_base64(png)
     assert png_bytes.startswith(_PNG)
 
 def test_select_figure_formats_set():
     ip = get_ipython()
     for fmts in [
         {'png', 'svg'},
         ['png'],
         ('jpeg', 'pdf', 'retina'),
         {'svg'},
     ]:
         active_mimes = {_fmt_mime_map[fmt] for fmt in fmts}
         pt.select_figure_formats(ip, fmts)
         for mime, f in ip.display_formatter.formatters.items():
             if mime in active_mimes:
                 assert Figure in f
             else:
                 assert Figure not in f
 
 def test_select_figure_formats_bad():
     ip = get_ipython()
     with pytest.raises(ValueError):
         pt.select_figure_formats(ip, 'foo')
     with pytest.raises(ValueError):
         pt.select_figure_formats(ip, {'png', 'foo'})
     with pytest.raises(ValueError):
         pt.select_figure_formats(ip, ['retina', 'pdf', 'bar', 'bad'])
 
 def test_import_pylab():
     ns = {}
     pt.import_pylab(ns, import_all=False)
     assert "plt" in ns
     assert ns["np"] == np
 
 
 class TestPylabSwitch(object):
     class Shell(InteractiveShell):
         def init_history(self):
             """Sets up the command history, and starts regular autosaves."""
             self.config.HistoryManager.hist_file = ":memory:"
             super().init_history()
 
         def enable_gui(self, gui):
             pass
 
     def setup(self):
         import matplotlib
         def act_mpl(backend):
             matplotlib.rcParams['backend'] = backend
 
         # Save rcParams since they get modified
         self._saved_rcParams = matplotlib.rcParams
         self._saved_rcParamsOrig = matplotlib.rcParamsOrig
         matplotlib.rcParams = dict(backend="QtAgg")
         matplotlib.rcParamsOrig = dict(backend="QtAgg")
 
         # Mock out functions
         self._save_am = pt.activate_matplotlib
         pt.activate_matplotlib = act_mpl
         self._save_ip = pt.import_pylab
         pt.import_pylab = lambda *a,**kw:None
         self._save_cis = backend_inline.configure_inline_support
         backend_inline.configure_inline_support = lambda *a, **kw: None
 
     def teardown(self):
         pt.activate_matplotlib = self._save_am
         pt.import_pylab = self._save_ip
         backend_inline.configure_inline_support = self._save_cis
         import matplotlib
         matplotlib.rcParams = self._saved_rcParams
         matplotlib.rcParamsOrig = self._saved_rcParamsOrig
 
     def test_qt(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib(None)
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
         gui, backend = s.enable_matplotlib("inline")
         assert gui is None
         assert s.pylab_gui_select == "qt"
 
         gui, backend = s.enable_matplotlib("qt")
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
         gui, backend = s.enable_matplotlib("inline")
         assert gui is None
         assert s.pylab_gui_select == "qt"
 
         gui, backend = s.enable_matplotlib()
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
     def test_inline(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib("inline")
         assert gui is None
         assert s.pylab_gui_select == None
 
         gui, backend = s.enable_matplotlib("inline")
         assert gui is None
         assert s.pylab_gui_select == None
 
         gui, backend = s.enable_matplotlib("qt")
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
     def test_inline_twice(self):
         "Using '%matplotlib inline' twice should not reset formatters"
 
         ip = self.Shell()
         gui, backend = ip.enable_matplotlib("inline")
         assert gui is None
 
         fmts =  {'png'}
         active_mimes = {_fmt_mime_map[fmt] for fmt in fmts}
         pt.select_figure_formats(ip, fmts)
 
         gui, backend = ip.enable_matplotlib("inline")
         assert gui is None
 
         for mime, f in ip.display_formatter.formatters.items():
             if mime in active_mimes:
                 assert Figure in f
             else:
                 assert Figure not in f
 
     def test_qt_gtk(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib("qt")
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
         gui, backend = s.enable_matplotlib("gtk3")
         assert gui == "qt"
         assert s.pylab_gui_select == "qt"
 
 
 def test_no_gui_backends():
     for k in ['agg', 'svg', 'pdf', 'ps']:
         assert k not in pt.backend2gui
 
 
 def test_figure_no_canvas():
     fig = Figure()
     fig.canvas = None
     pt.print_figure(fig)
+
+
[e-mail](
+    "name, expected_gui, expected_backend",
+    [
+        # name is gui
+        ("gtk3", "gtk3", "gtk3agg"),
+        ("gtk4", "gtk4", "gtk4agg"),
+        ("headless", "headless", "agg"),
+        ("osx", "osx", "macosx"),
+        ("qt", "qt", "qtagg"),
+        ("qt5", "qt5", "qt5agg"),
+        ("qt6", "qt6", "qt6agg"),
+        ("tk", "tk", "tkagg"),
+        ("wx", "wx", "wxagg"),
+        # name is backend
+        ("agg", None, "agg"),
+        ("cairo", None, "cairo"),
+        ("pdf", None, "pdf"),
+        ("ps", None, "ps"),
+        ("svg", None, "svg"),
+        ("template", None, "template"),
+        ("gtk3agg", "gtk3", "gtk3agg"),
+        ("gtk3cairo", "gtk3", "gtk3cairo"),
+        ("gtk4agg", "gtk4", "gtk4agg"),
+        ("gtk4cairo", "gtk4", "gtk4cairo"),
+        ("macosx", "osx", "macosx"),
+        ("nbagg", "nbagg", "nbagg"),
+        ("notebook", "nbagg", "notebook"),
+        ("qtagg", "qt", "qtagg"),
+        ("qtcairo", "qt", "qtcairo"),
+        ("qt5agg", "qt5", "qt5agg"),
+        ("qt5cairo", "qt5", "qt5cairo"),
+        ("qt6agg", "qt", "qt6agg"),
+        ("qt6cairo", "qt", "qt6cairo"),
+        ("tkagg", "tk", "tkagg"),
+        ("tkcairo", "tk", "tkcairo"),
+        ("webagg", "webagg", "webagg"),
+        ("wxagg", "wx", "wxagg"),
+        ("wxcairo", "wx", "wxcairo"),
+    ],
+)
+def test_backend_builtin(name, expected_gui, expected_backend):
+    # Test correct identification of Matplotlib built-in backends without importing and using them,
+    # otherwise we would need to ensure all the complex dependencies such as windowing toolkits are
+    # installed.
+
+    mpl_manages_backends = pt._matplotlib_manages_backends()
+    if not mpl_manages_backends:
+        # Backends not supported before _matplotlib_manages_backends or supported
+        # but with different expected_gui or expected_backend.
+        if (
+            name.endswith("agg")
+            or name.endswith("cairo")
+            or name in ("headless", "macosx", "pdf", "ps", "svg", "template")
+        ):
+            pytest.skip()
+        elif name == "qt6":
+            expected_backend = "qtagg"
+        elif name == "notebook":
+            expected_backend, expected_gui = expected_gui, expected_backend
+
+    gui, backend = pt.find_gui_and_backend(name)
+    if not mpl_manages_backends:
+        gui = gui.lower() if gui else None
+        backend = backend.lower() if backend else None
+    assert gui == expected_gui
+    assert backend == expected_backend
+
+
+def test_backend_entry_point():
+    gui, backend = pt.find_gui_and_backend("inline")
+    assert gui is None
+    expected_backend = (
+        "inline"
+        if pt._matplotlib_manages_backends()
+        else "module://matplotlib_inline.backend_inline"
+    )
+    assert backend == expected_backend
+
+
+def test_backend_unknown():
+    with pytest.raises(RuntimeError if pt._matplotlib_manages_backends() else KeyError):
+        pt.find_gui_and_backend("name-does-not-exist")

IPython/terminal/embed.py

@@ -1,426 +1,426 b''
 # encoding: utf-8
 """
 An embedded IPython shell.
 """
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 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
 
 from typing import Set
 
 class KillEmbedded(Exception):pass
 
 # kept for backward compatibility as IPython 6 was released with
 # the typo. See https://github.com/ipython/ipython/pull/10706
 KillEmbeded = KillEmbedded
 
 # 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
 
         This function (after asking for confirmation) sets an internal flag so
         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
 
         """
 
         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.KillEmbedded` 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 _Sentinel:
     def __init__(self, repr):
         assert isinstance(repr, str)
         self.repr = repr
 
     def __repr__(self):
         return repr
 
 
 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[str] = set()
 
     def _disable_init_location(self):
         """Disable the current Instance creation location"""
         InteractiveShellEmbed._inactive_locations.add(self._init_location_id)
 
     @property
     def embedded_active(self):
         return (self._call_location_id not in InteractiveShellEmbed._inactive_locations)\
             and (self._init_location_id not in InteractiveShellEmbed._inactive_locations)
 
     @embedded_active.setter
     def embedded_active(self, value):
         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)
 
     def __init__(self, **kw):
         assert (
             "user_global_ns" not in kw
         ), "Key word argument `user_global_ns` has been replaced by `user_module` since IPython 4.0."
         # temporary fix for https://github.com/ipython/ipython/issues/14164
         cls = type(self)
         if cls._instance is None:
             for subclass in cls._walk_mro():
                 subclass._instance = self
             cls._instance = self
 
         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)
 
         # 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 :mod:`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,
         compile_flags=None,
-        **kw
+        **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, 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 KillEmbedded('Embedded IPython raising error, as user requested.')
 
     def mainloop(
         self,
         local_ns=None,
         module=None,
         stack_depth=0,
         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.
 
         """
         
         # 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(*, header="", compile_flags=None, **kwargs):
     """Call this to embed IPython at the current point in your program.
 
     The first invocation of this will create a :class:`terminal.embed.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()
 
     Parameters
     ----------
 
     header : str
         Optional header string to print at startup.
     compile_flags
         Passed to the `compile_flags` parameter of :py:meth:`terminal.embed.InteractiveShellEmbed.mainloop()`,
         which is called when the :class:`terminal.embed.InteractiveShellEmbed` instance is called.
     **kwargs : various, optional
         Any other kwargs will be passed to the :class:`terminal.embed.InteractiveShellEmbed` constructor.
         Full customization can be done by passing a traitlets :class:`Config` in as the
         `config` argument (see :ref:`configure_start_ipython` and :ref:`terminal_options`).
     """
     config = kwargs.get('config')
     if config is None:
         config = load_default_config()
         config.InteractiveShellEmbed = config.TerminalInteractiveShell
         kwargs['config'] = config
     using = kwargs.get('using', 'sync')
     if using :
         kwargs['config'].update({'TerminalInteractiveShell':{'loop_runner':using, 'colors':'NoColor', 'autoawait': using!='sync'}})
     #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(_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