Merge pull request #12239 from martinRenou/refactor_display

Refactor display modules

IPython/core/display_functions.py

@@ -0,0 +1,367 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
+
+__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
+#-----------------------------------------------------------------------------
+
+
+# use * to indicate transient is keyword-only
+def publish_display_data(data, metadata=None, source=None, *, 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
+
+    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, **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`
+    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
+
+    raw = kwargs.pop('raw', False)
+    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
+
+    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/display.py

@@ -1,1527 +1,1206 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, b2a_base64, hexlify
+from binascii import b2a_base64, hexlify
 import json
 import mimetypes
 import os
 import struct
-import sys
 import warnings
 from copy import deepcopy
 from os.path import splitext
 from pathlib import Path, PurePath
 
 from IPython.utils.py3compat import cast_unicode
 from IPython.testing.skipdoctest import skip_doctest
+from . import display_functions
+
+
+__all__ = ['display_pretty', 'display_html', 'display_markdown',
+           'display_svg', 'display_png', 'display_jpeg', 'display_latex', 'display_json',
+           'display_javascript', 'display_pdf', 'DisplayObject', 'TextDisplayObject',
+           'Pretty', 'HTML', 'Markdown', 'Math', 'Latex', 'SVG', 'ProgressBar', 'JSON',
+           'GeoJSON', 'Javascript', 'Image', 'set_matplotlib_formats',
+           'set_matplotlib_close',
+           'Video']
+
+_deprecated_names = ["display", "clear_output", "publish_display_data", "update_display", "DisplayHandle"]
+
+__all__ = __all__ + _deprecated_names
+
+
+# ----- warn to import from IPython.display -----
+
+from warnings import warn
+
+
+def __getattr__(name):
+    if name in _deprecated_names:
+        warn(f"Importing {name} from IPython.core.display is deprecated since IPython 7.14, please import from IPython display", DeprecationWarning, stacklevel=2)
+        return getattr(display_functions, name)
+
+    if name in globals().keys():
+        return globals()[name]
+    else:
+        raise AttributeError(f"module {__name__} has no attribute {name}")
 
-__all__ = ['display', 'display_pretty', 'display_html', 'display_markdown',
-'display_svg', 'display_png', 'display_jpeg', 'display_latex', 'display_json',
-'display_javascript', 'display_pdf', 'DisplayObject', 'TextDisplayObject',
-'Pretty', 'HTML', 'Markdown', 'Math', 'Latex', 'SVG', 'ProgressBar', 'JSON',
-'GeoJSON', 'Javascript', 'Image', 'clear_output', 'set_matplotlib_formats',
-'set_matplotlib_close', 'publish_display_data', 'update_display', 'DisplayHandle',
-'Video']
 
 #-----------------------------------------------------------------------------
 # utility functions
 #-----------------------------------------------------------------------------
 
 def _safe_exists(path):
     """Check path, but don't let exceptions raise"""
     try:
         return os.path.exists(path)
     except Exception:
         return False
 
-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
 
 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
     """internal implementation of all display_foo methods
 
     Parameters
     ----------
     mimetype : str
         The mimetype to be published (e.g. 'image/png')
     *objs : object
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     if metadata:
         metadata = {mimetype: metadata}
     if raw:
         # turn list of pngdata into list of { 'image/png': pngdata }
         objs = [ {mimetype: obj} for obj in objs ]
     display(*objs, raw=raw, metadata=metadata, include=[mimetype])
 
 #-----------------------------------------------------------------------------
 # Main functions
 #-----------------------------------------------------------------------------
 
-# use * to indicate transient is keyword-only
-def publish_display_data(data, metadata=None, source=None, *, 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
-
-    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, **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`
-    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
-    
-    raw = kwargs.pop('raw', False)
-    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
-
-    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 display_pretty(*objs, **kwargs):
     """Display the pretty (default) representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/plain', objs, **kwargs)
 
 
 def display_html(*objs, **kwargs):
     """Display the HTML representation of an object.
 
     Note: If raw=False and the object does not have a HTML
     representation, no HTML will be shown.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw HTML data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/html', objs, **kwargs)
 
 
 def display_markdown(*objs, **kwargs):
     """Displays the Markdown representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw markdown data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
 
     _display_mimetype('text/markdown', objs, **kwargs)
 
 
 def display_svg(*objs, **kwargs):
     """Display the SVG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw svg data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/svg+xml', objs, **kwargs)
 
 
 def display_png(*objs, **kwargs):
     """Display the PNG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw png data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/png', objs, **kwargs)
 
 
 def display_jpeg(*objs, **kwargs):
     """Display the JPEG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw JPEG data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/jpeg', objs, **kwargs)
 
 
 def display_latex(*objs, **kwargs):
     """Display the LaTeX representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw latex data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/latex', objs, **kwargs)
 
 
 def display_json(*objs, **kwargs):
     """Display the JSON representation of an object.
 
     Note that not many frontends support displaying JSON.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw json data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/json', objs, **kwargs)
 
 
 def display_javascript(*objs, **kwargs):
     """Display the Javascript representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw javascript data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/javascript', objs, **kwargs)
 
 
 def display_pdf(*objs, **kwargs):
     """Display the PDF representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw javascript data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/pdf', objs, **kwargs)
 
 
 #-----------------------------------------------------------------------------
 # Smart classes
 #-----------------------------------------------------------------------------
 
 
 class DisplayObject(object):
     """An object that wraps data to be displayed."""
 
     _read_flags = 'r'
     _show_mem_addr = False
     metadata = None
 
     def __init__(self, data=None, url=None, filename=None, metadata=None):
         """Create a display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. The MIME type of the data should match the
         subclasses used, so the Png subclass should be used for 'image/png'
         data. If the data is a URL, the data will first be downloaded
         and then displayed. If
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw data or a URL or file to load the data from
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         metadata : dict
             Dict of metadata associated to be the object when displayed
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if data is not None and isinstance(data, str):
             if data.startswith('http') and url is None:
                 url = data
                 filename = None
                 data = None
             elif _safe_exists(data) and filename is None:
                 url = None
                 filename = data
                 data = None
 
         self.url = url
         self.filename = filename
         # because of @data.setter methods in
         # subclasses ensure url and filename are set
         # before assigning to self.data
         self.data = data
 
         if metadata is not None:
             self.metadata = metadata
         elif self.metadata is None:
             self.metadata = {}
 
         self.reload()
         self._check_data()
 
     def __repr__(self):
         if not self._show_mem_addr:
             cls = self.__class__
             r = "<%s.%s object>" % (cls.__module__, cls.__name__)
         else:
             r = super(DisplayObject, self).__repr__()
         return r
 
     def _check_data(self):
         """Override in subclasses if there's something to check."""
         pass
 
     def _data_and_metadata(self):
         """shortcut for returning metadata with shape information, if defined"""
         if self.metadata:
             return self.data, deepcopy(self.metadata)
         else:
             return self.data
 
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.filename is not None:
             with open(self.filename, self._read_flags) as f:
                 self.data = f.read()
         elif self.url is not None:
             # Deferred import
             from urllib.request import urlopen
             response = urlopen(self.url)
             data = response.read()
             # extract encoding from header, if there is one:
             encoding = None
             if 'content-type' in response.headers:
                 for sub in response.headers['content-type'].split(';'):
                     sub = sub.strip()
                     if sub.startswith('charset'):
                         encoding = sub.split('=')[-1].strip()
                         break
             if 'content-encoding' in response.headers:
                 # TODO: do deflate?
                 if 'gzip' in response.headers['content-encoding']:
                     import gzip
                     from io import BytesIO
                     with gzip.open(BytesIO(data), 'rt', encoding=encoding) as fp:
                         encoding = None
                         data = fp.read()
                     
             # decode data, if an encoding was specified
             # We only touch self.data once since
             # subclasses such as SVG have @data.setter methods
             # that transform self.data into ... well svg.
             if encoding:
                 self.data = data.decode(encoding, 'replace')
             else:
                 self.data = data
 
 
 class TextDisplayObject(DisplayObject):
     """Validate that display data is text"""
     def _check_data(self):
         if self.data is not None and not isinstance(self.data, str):
             raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data))
 
 class Pretty(TextDisplayObject):
 
     def _repr_pretty_(self, pp, cycle):
         return pp.text(self.data)
 
 
 class HTML(TextDisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, metadata=None):
         def warn():
             if not data:
                 return False
 
             #
             # Avoid calling lower() on the entire data, because it could be a
             # long string and we're only interested in its beginning and end.
             #
             prefix = data[:10].lower()
             suffix = data[-10:].lower()
             return prefix.startswith("<iframe ") and suffix.endswith("</iframe>")
 
         if warn():
             warnings.warn("Consider using IPython.display.IFrame instead")
         super(HTML, self).__init__(data=data, url=url, filename=filename, metadata=metadata)
 
     def _repr_html_(self):
         return self._data_and_metadata()
 
     def __html__(self):
         """
         This method exists to inform other HTML-using modules (e.g. Markupsafe,
         htmltag, etc) that this object is HTML and does not need things like
         special characters (<>&) escaped.
         """
         return self._repr_html_()
 
 
 class Markdown(TextDisplayObject):
 
     def _repr_markdown_(self):
         return self._data_and_metadata()
 
 
 class Math(TextDisplayObject):
 
     def _repr_latex_(self):
         s = r"$\displaystyle %s$" % self.data.strip('$')
         if self.metadata:
             return s, deepcopy(self.metadata)
         else:
             return s
 
 
 class Latex(TextDisplayObject):
 
     def _repr_latex_(self):
         return self._data_and_metadata()
 
 
 class SVG(DisplayObject):
     """Embed an SVG into the display.
 
     Note if you just want to view a svg image via a URL use `:class:Image` with
     a url=URL keyword argument.
     """
 
     _read_flags = 'rb'
     # wrap data in a property, which extracts the <svg> tag, discarding
     # document headers
     _data = None
 
     @property
     def data(self):
         return self._data
 
     @data.setter
     def data(self, svg):
         if svg is None:
             self._data = None
             return
         # parse into dom object
         from xml.dom import minidom
         x = minidom.parseString(svg)
         # get svg tag (should be 1)
         found_svg = x.getElementsByTagName('svg')
         if found_svg:
             svg = found_svg[0].toxml()
         else:
             # fallback on the input, trust the user
             # but this is probably an error.
             pass
         svg = cast_unicode(svg)
         self._data = svg
-    
+
     def _repr_svg_(self):
         return self._data_and_metadata()
 
 class ProgressBar(DisplayObject):
-    """Progressbar supports displaying a progressbar like element 
+    """Progressbar supports displaying a progressbar like element
     """
     def __init__(self, total):
         """Creates a new progressbar
-        
+
         Parameters
         ----------
         total : int
             maximum size of the progressbar
         """
         self.total = total
         self._progress = 0
         self.html_width = '60ex'
         self.text_width = 60
         self._display_id = hexlify(os.urandom(8)).decode('ascii')
 
     def __repr__(self):
         fraction = self.progress / self.total
         filled = '=' * int(fraction * self.text_width)
         rest = ' ' * (self.text_width - len(filled))
         return '[{}{}] {}/{}'.format(
             filled, rest,
             self.progress, self.total,
         )
 
     def _repr_html_(self):
         return "<progress style='width:{}' max='{}' value='{}'></progress>".format(
             self.html_width, self.total, self.progress)
 
     def display(self):
         display(self, display_id=self._display_id)
 
     def update(self):
         display(self, display_id=self._display_id, update=True)
 
     @property
     def progress(self):
         return self._progress
 
     @progress.setter
     def progress(self, value):
         self._progress = value
         self.update()
 
     def __iter__(self):
         self.display()
         self._progress = -1 # First iteration is 0
         return self
 
     def __next__(self):
         """Returns current value and increments display by one."""
         self.progress += 1
         if self.progress < self.total:
             return self.progress
         else:
             raise StopIteration()
 
 class JSON(DisplayObject):
     """JSON expects a JSON-able dict or list
 
     not an already-serialized JSON string.
 
     Scalar types (None, number, string) are not allowed, only dict or list containers.
     """
     # wrap data in a property, which warns about passing already-serialized JSON
     _data = None
     def __init__(self, data=None, url=None, filename=None, expanded=False, metadata=None, root='root', **kwargs):
         """Create a JSON display object given raw data.
 
         Parameters
         ----------
         data : dict or list
             JSON data to display. Not an already-serialized JSON string.
             Scalar types (None, number, string) are not allowed, only dict
             or list containers.
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         expanded : boolean
             Metadata to control whether a JSON display component is expanded.
         metadata: dict
             Specify extra metadata to attach to the json display object.
         root : str
-            The name of the root element of the JSON tree 
+            The name of the root element of the JSON tree
         """
         self.metadata = {
             'expanded': expanded,
             'root': root,
         }
         if metadata:
             self.metadata.update(metadata)
         if kwargs:
             self.metadata.update(kwargs)
         super(JSON, self).__init__(data=data, url=url, filename=filename)
 
     def _check_data(self):
         if self.data is not None and not isinstance(self.data, (dict, list)):
             raise TypeError("%s expects JSONable dict or list, not %r" % (self.__class__.__name__, self.data))
 
     @property
     def data(self):
         return self._data
 
     @data.setter
     def data(self, data):
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if isinstance(data, str):
             if self.filename is None and self.url is None:
                 warnings.warn("JSON expects JSONable dict or list, not JSON strings")
             data = json.loads(data)
         self._data = data
 
     def _data_and_metadata(self):
         return self.data, self.metadata
 
     def _repr_json_(self):
         return self._data_and_metadata()
 
 _css_t = """var link = document.createElement("link");
 	link.ref = "stylesheet";
 	link.type = "text/css";
 	link.href = "%s";
 	document.head.appendChild(link);
 """
 
 _lib_t1 = """new Promise(function(resolve, reject) {
 	var script = document.createElement("script");
 	script.onload = resolve;
 	script.onerror = reject;
 	script.src = "%s";
 	document.head.appendChild(script);
 }).then(() => {
 """
 
 _lib_t2 = """
 });"""
 
 class GeoJSON(JSON):
     """GeoJSON expects JSON-able dict
 
     not an already-serialized JSON string.
 
     Scalar types (None, number, string) are not allowed, only dict containers.
     """
-    
+
     def __init__(self, *args, **kwargs):
         """Create a GeoJSON display object given raw data.
 
         Parameters
         ----------
         data : dict or list
             VegaLite data. Not an already-serialized JSON string.
             Scalar types (None, number, string) are not allowed, only dict
             or list containers.
         url_template : string
             Leaflet TileLayer URL template: http://leafletjs.com/reference.html#url-template
         layer_options : dict
             Leaflet TileLayer options: http://leafletjs.com/reference.html#tilelayer-options
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         metadata: dict
             Specify extra metadata to attach to the json display object.
 
         Examples
         --------
 
         The following will display an interactive map of Mars with a point of
         interest on frontend that do support GeoJSON display.
 
             >>> from IPython.display import GeoJSON
 
             >>> GeoJSON(data={
             ...     "type": "Feature",
             ...     "geometry": {
             ...         "type": "Point",
             ...         "coordinates": [-81.327, 296.038]
             ...     }
             ... },
             ... url_template="http://s3-eu-west-1.amazonaws.com/whereonmars.cartodb.net/{basemap_id}/{z}/{x}/{y}.png",
             ... layer_options={
             ...     "basemap_id": "celestia_mars-shaded-16k_global",
             ...     "attribution" : "Celestia/praesepe",
             ...     "minZoom" : 0,
             ...     "maxZoom" : 18,
             ... })
             <IPython.core.display.GeoJSON object>
 
         In the terminal IPython, you will only see the text representation of
         the GeoJSON object.
 
         """
-        
+
         super(GeoJSON, self).__init__(*args, **kwargs)
 
 
     def _ipython_display_(self):
         bundle = {
             'application/geo+json': self.data,
             'text/plain': '<IPython.display.GeoJSON object>'
         }
         metadata = {
             'application/geo+json': self.metadata
         }
         display(bundle, metadata=metadata, raw=True)
 
 class Javascript(TextDisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
         """Create a Javascript display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. If the data is a URL, the data will first be
         downloaded and then displayed.
 
         In the Notebook, the containing element will be available as `element`,
         and jQuery will be available.  Content appended to `element` will be
         visible in the output area.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The Javascript source code or a URL to download it from.
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         lib : list or str
             A sequence of Javascript library URLs to load asynchronously before
             running the source code. The full URLs of the libraries should
             be given. A single Javascript library URL can also be given as a
             string.
         css: : list or str
             A sequence of css files to load before running the source code.
             The full URLs of the css files should be given. A single css URL
             can also be given as a string.
         """
         if isinstance(lib, str):
             lib = [lib]
         elif lib is None:
             lib = []
         if isinstance(css, str):
             css = [css]
         elif css is None:
             css = []
         if not isinstance(lib, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % lib)
         if not isinstance(css, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % css)
         self.lib = lib
         self.css = css
         super(Javascript, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_javascript_(self):
         r = ''
         for c in self.css:
             r += _css_t % c
         for l in self.lib:
             r += _lib_t1 % l
         r += self.data
         r += _lib_t2*len(self.lib)
         return r
 
 # constants for identifying png/jpeg data
 _PNG = b'\x89PNG\r\n\x1a\n'
 _JPEG = b'\xff\xd8'
 
 def _pngxy(data):
     """read the (width, height) from a PNG header"""
     ihdr = data.index(b'IHDR')
     # next 8 bytes are width/height
     return struct.unpack('>ii', data[ihdr+4:ihdr+12])
 
 def _jpegxy(data):
     """read the (width, height) from a JPEG header"""
     # adapted from http://www.64lines.com/jpeg-width-height
 
     idx = 4
     while True:
         block_size = struct.unpack('>H', data[idx:idx+2])[0]
         idx = idx + block_size
         if data[idx:idx+2] == b'\xFF\xC0':
             # found Start of Frame
             iSOF = idx
             break
         else:
             # read another block
             idx += 2
 
     h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
     return w, h
 
 def _gifxy(data):
     """read the (width, height) from a GIF header"""
     return struct.unpack('<HH', data[6:10])
 
 
 class Image(DisplayObject):
 
     _read_flags = 'rb'
     _FMT_JPEG = u'jpeg'
     _FMT_PNG = u'png'
     _FMT_GIF = u'gif'
     _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG, _FMT_GIF]
     _MIMETYPES = {
         _FMT_PNG: 'image/png',
         _FMT_JPEG: 'image/jpeg',
         _FMT_GIF: 'image/gif',
     }
 
     def __init__(self, data=None, url=None, filename=None, format=None,
                  embed=None, width=None, height=None, retina=False,
                  unconfined=False, metadata=None):
         """Create a PNG/JPEG/GIF image object given raw data.
 
         When this object is returned by an input cell or passed to the
         display function, it will result in the image being displayed
         in the frontend.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw image data or a URL or filename to load the data from.
             This always results in embedded image data.
         url : unicode
             A URL to download the data from. If you specify `url=`,
             the image data will not be embedded unless you also specify `embed=True`.
         filename : unicode
             Path to a local file to load the data from.
             Images from a file are always embedded.
         format : unicode
             The format of the image data (png/jpeg/jpg/gif). If a filename or URL is given
             for format will be inferred from the filename extension.
         embed : bool
             Should the image data be embedded using a data URI (True) or be
             loaded using an <img> tag. Set this to True if you want the image
             to be viewable later with no internet connection in the notebook.
 
             Default is `True`, unless the keyword argument `url` is set, then
             default value is `False`.
 
             Note that QtConsole is not able to display images if `embed` is set to `False`
         width : int
             Width in pixels to which to constrain the image in html
         height : int
             Height in pixels to which to constrain the image in html
         retina : bool
             Automatically set the width and height to half of the measured
             width and height.
             This only works for embedded images because it reads the width/height
             from image data.
             For non-embedded images, you can just set the desired display width
             and height directly.
         unconfined: bool
             Set unconfined=True to disable max-width confinement of the image.
         metadata: dict
             Specify extra metadata to attach to the image.
 
         Examples
         --------
         # embedded image data, works in qtconsole and notebook
         # when passed positionally, the first arg can be any of raw image data,
         # a URL, or a filename from which to load image data.
         # The result is always embedding image data for inline images.
         Image('http://www.google.fr/images/srpr/logo3w.png')
         Image('/path/to/image.jpg')
         Image(b'RAW_PNG_DATA...')
 
         # Specifying Image(url=...) does not embed the image data,
         # it only generates `<img>` tag with a link to the source.
         # This will not work in the qtconsole or offline.
         Image(url='http://www.google.fr/images/srpr/logo3w.png')
 
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if filename is not None:
             ext = self._find_ext(filename)
         elif url is not None:
             ext = self._find_ext(url)
         elif data is None:
             raise ValueError("No image data found. Expecting filename, url, or data.")
         elif isinstance(data, str) and (
             data.startswith('http') or _safe_exists(data)
         ):
             ext = self._find_ext(data)
         else:
             ext = None
 
         if format is None:
             if ext is not None:
                 if ext == u'jpg' or ext == u'jpeg':
                     format = self._FMT_JPEG
                 elif ext == u'png':
                     format = self._FMT_PNG
                 elif ext == u'gif':
                     format = self._FMT_GIF
                 else:
                     format = ext.lower()
             elif isinstance(data, bytes):
                 # infer image type from image data header,
                 # only if format has not been specified.
                 if data[:2] == _JPEG:
                     format = self._FMT_JPEG
 
         # failed to detect format, default png
         if format is None:
             format = self._FMT_PNG
 
         if format.lower() == 'jpg':
             # jpg->jpeg
             format = self._FMT_JPEG
 
         self.format = format.lower()
         self.embed = embed if embed is not None else (url is None)
 
         if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
             raise ValueError("Cannot embed the '%s' image format" % (self.format))
         if self.embed:
             self._mimetype = self._MIMETYPES.get(self.format)
 
         self.width = width
         self.height = height
         self.retina = retina
         self.unconfined = unconfined
-        super(Image, self).__init__(data=data, url=url, filename=filename, 
+        super(Image, self).__init__(data=data, url=url, filename=filename,
                 metadata=metadata)
 
         if self.width is None and self.metadata.get('width', {}):
             self.width = metadata['width']
 
         if self.height is None and self.metadata.get('height', {}):
             self.height = metadata['height']
 
         if retina:
             self._retina_shape()
 
 
     def _retina_shape(self):
         """load pixel-doubled width and height from image data"""
         if not self.embed:
             return
         if self.format == self._FMT_PNG:
             w, h = _pngxy(self.data)
         elif self.format == self._FMT_JPEG:
             w, h = _jpegxy(self.data)
         elif self.format == self._FMT_GIF:
             w, h = _gifxy(self.data)
         else:
             # retina only supports png
             return
         self.width = w // 2
         self.height = h // 2
 
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.embed:
             super(Image,self).reload()
             if self.retina:
                 self._retina_shape()
 
     def _repr_html_(self):
         if not self.embed:
             width = height = klass = ''
             if self.width:
                 width = ' width="%d"' % self.width
             if self.height:
                 height = ' height="%d"' % self.height
             if self.unconfined:
                 klass = ' class="unconfined"'
             return u'<img src="{url}"{width}{height}{klass}/>'.format(
                 url=self.url,
                 width=width,
                 height=height,
                 klass=klass,
             )
 
     def _repr_mimebundle_(self, include=None, exclude=None):
         """Return the image as a mimebundle
 
         Any new mimetype support should be implemented here.
         """
         if self.embed:
             mimetype = self._mimetype
             data, metadata = self._data_and_metadata(always_both=True)
             if metadata:
                 metadata = {mimetype: metadata}
             return {mimetype: data}, metadata
         else:
             return {'text/html': self._repr_html_()}
 
     def _data_and_metadata(self, always_both=False):
         """shortcut for returning metadata with shape information, if defined"""
         try:
             b64_data = b2a_base64(self.data).decode('ascii')
         except TypeError:
             raise FileNotFoundError(
                 "No such file or directory: '%s'" % (self.data))
         md = {}
         if self.metadata:
             md.update(self.metadata)
         if self.width:
             md['width'] = self.width
         if self.height:
             md['height'] = self.height
         if self.unconfined:
             md['unconfined'] = self.unconfined
         if md or always_both:
             return b64_data, md
         else:
             return b64_data
 
     def _repr_png_(self):
         if self.embed and self.format == self._FMT_PNG:
             return self._data_and_metadata()
 
     def _repr_jpeg_(self):
         if self.embed and self.format == self._FMT_JPEG:
             return self._data_and_metadata()
 
     def _find_ext(self, s):
         base, ext = splitext(s)
 
         if not ext:
             return base
 
         # `splitext` includes leading period, so we skip it
         return ext[1:].lower()
 
 
 class Video(DisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, embed=False,
                  mimetype=None, width=None, height=None, html_attributes="controls"):
         """Create a video object given raw data or an URL.
 
         When this object is returned by an input cell or passed to the
         display function, it will result in the video being displayed
         in the frontend.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw video data or a URL or filename to load the data from.
             Raw data will require passing `embed=True`.
         url : unicode
             A URL for the video. If you specify `url=`,
             the image data will not be embedded.
         filename : unicode
             Path to a local file containing the video.
             Will be interpreted as a local URL unless `embed=True`.
         embed : bool
             Should the video be embedded using a data URI (True) or be
             loaded using a <video> tag (False).
 
             Since videos are large, embedding them should be avoided, if possible.
             You must confirm embedding as your intention by passing `embed=True`.
 
             Local files can be displayed with URLs without embedding the content, via::
 
                 Video('./video.mp4')
 
         mimetype: unicode
             Specify the mimetype for embedded videos.
             Default will be guessed from file extension, if available.
         width : int
             Width in pixels to which to constrain the video in HTML.
             If not supplied, defaults to the width of the video.
         height : int
             Height in pixels to which to constrain the video in html.
             If not supplied, defaults to the height of the video.
         html_attributes : str
             Attributes for the HTML `<video>` block.
             Default: `"controls"` to get video controls.
             Other examples: `"controls muted"` for muted video with controls,
             `"loop autoplay"` for looping autoplaying video without controls.
 
         Examples
         --------
 
         ::
 
             Video('https://archive.org/download/Sita_Sings_the_Blues/Sita_Sings_the_Blues_small.mp4')
             Video('path/to/video.mp4')
             Video('path/to/video.mp4', embed=True)
             Video('path/to/video.mp4', embed=True, html_attributes="controls muted autoplay")
             Video(b'raw-videodata', embed=True)
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if url is None and isinstance(data, str) and data.startswith(('http:', 'https:')):
             url = data
             data = None
         elif os.path.exists(data):
             filename = data
             data = None
 
         if data and not embed:
             msg = ''.join([
                 "To embed videos, you must pass embed=True ",
                 "(this may make your notebook files huge)\n",
                 "Consider passing Video(url='...')",
             ])
             raise ValueError(msg)
 
         self.mimetype = mimetype
         self.embed = embed
         self.width = width
         self.height = height
         self.html_attributes = html_attributes
         super(Video, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_html_(self):
         width = height = ''
         if self.width:
             width = ' width="%d"' % self.width
         if self.height:
             height = ' height="%d"' % self.height
 
         # External URLs and potentially local files are not embedded into the
         # notebook output.
         if not self.embed:
             url = self.url if self.url is not None else self.filename
             output = """<video src="{0}" {1} {2} {3}>
       Your browser does not support the <code>video</code> element.
     </video>""".format(url, self.html_attributes, width, height)
             return output
 
         # Embedded videos are base64-encoded.
         mimetype = self.mimetype
         if self.filename is not None:
             if not mimetype:
                 mimetype, _ = mimetypes.guess_type(self.filename)
 
             with open(self.filename, 'rb') as f:
                 video = f.read()
         else:
             video = self.data
         if isinstance(video, str):
             # unicode input is already b64-encoded
             b64_video = video
         else:
             b64_video = b2a_base64(video).decode('ascii').rstrip()
 
         output = """<video {0} {1} {2}>
  <source src="data:{3};base64,{4}" type="{3}">
  Your browser does not support the video tag.
  </video>""".format(self.html_attributes, width, height, mimetype, b64_video)
         return output
 
     def reload(self):
         # TODO
         pass
 
 
-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()
-
-
 @skip_doctest
 def set_matplotlib_formats(*formats, **kwargs):
     """Select figure formats for the inline backend. Optionally pass quality for JPEG.
 
     For example, this enables PNG and JPEG output with a JPEG quality of 90%::
 
         In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
 
     To set this in your config files use the following::
 
         c.InlineBackend.figure_formats = {'png', 'jpeg'}
         c.InlineBackend.print_figure_kwargs.update({'quality' : 90})
 
     Parameters
     ----------
     *formats : strs
         One or more figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
     **kwargs :
         Keyword args will be relayed to ``figure.canvas.print_figure``.
     """
     from IPython.core.interactiveshell import InteractiveShell
     from IPython.core.pylabtools import select_figure_formats
     # build kwargs, starting with InlineBackend config
     kw = {}
     from ipykernel.pylab.config import InlineBackend
     cfg = InlineBackend.instance()
     kw.update(cfg.print_figure_kwargs)
     kw.update(**kwargs)
     shell = InteractiveShell.instance()
     select_figure_formats(shell, formats, **kw)
 
 @skip_doctest
 def set_matplotlib_close(close=True):
     """Set whether the inline backend closes all figures automatically or not.
 
     By default, the inline backend used in the IPython Notebook will close all
     matplotlib figures automatically after each cell is run. This means that
     plots in different cells won't interfere. Sometimes, you may want to make
     a plot in one cell and then refine it in later cells. This can be accomplished
     by::
 
         In [1]: set_matplotlib_close(False)
 
     To set this in your config files use the following::
 
         c.InlineBackend.close_figures = False
 
     Parameters
     ----------
     close : bool
         Should all matplotlib figures be automatically closed after each cell is
         run?
     """
     from ipykernel.pylab.config import InlineBackend
     cfg = InlineBackend.instance()
     cfg.close_figures = close

IPython/core/displaypub.py

@@ -1,138 +1,138 b''
 """An interface for publishing rich data to frontends.
 
 There are two components of the display system:
 
 * Display formatters, which take a Python object and compute the
   representation of the object in various formats (text, HTML, SVG, etc.).
 * The display publisher that is used to send the representation data to the
   various frontends.
 
 This module defines the logic display publishing. The display publisher uses
 the ``display_data`` message type that is defined in the IPython messaging
 spec.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 import sys
 
 from traitlets.config.configurable import Configurable
 from traitlets import List
 
 # This used to be defined here - it is imported for backwards compatibility
-from .display import publish_display_data
+from .display_functions import publish_display_data
 
 #-----------------------------------------------------------------------------
 # Main payload class
 #-----------------------------------------------------------------------------
 
 
 class DisplayPublisher(Configurable):
     """A traited class that publishes display data to frontends.
 
     Instances of this class are created by the main IPython object and should
     be accessed there.
     """
 
     def __init__(self, shell=None, *args, **kwargs):
         self.shell = shell
         super().__init__(*args, **kwargs)
 
     def _validate_data(self, data, metadata=None):
         """Validate the display data.
 
         Parameters
         ----------
         data : dict
             The formata data dictionary.
         metadata : dict
             Any metadata for the data.
         """
 
         if not isinstance(data, dict):
             raise TypeError('data must be a dict, got: %r' % data)
         if metadata is not None:
             if not isinstance(metadata, dict):
                 raise TypeError('metadata must be a dict, got: %r' % data)
 
     # use * to indicate transient, update are keyword-only
     def publish(self, data, metadata=None, source=None, *, transient=None, update=False, **kwargs) -> None:
         """Publish data and metadata to all frontends.
 
         See the ``display_data`` message in the messaging documentation for
         more details about this message type.
 
         The following MIME types are currently implemented:
 
         * text/plain
         * text/html
         * text/markdown
         * text/latex
         * application/json
         * application/javascript
         * image/png
         * image/jpeg
         * image/svg+xml
 
         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.  Metadata specific to each mime-type can be specified
             in the metadata dict with the same mime-type keys as
             the data itself.
         source : str, deprecated
             Unused.
         transient: dict, keyword-only
             A dictionary for transient data.
             Data in this dictionary should not be persisted as part of saving this output.
             Examples include 'display_id'.
         update: bool, keyword-only, default: False
             If True, only update existing outputs with the same display_id,
             rather than creating a new output.
         """
 
         handlers = {}
         if self.shell is not None:
             handlers = getattr(self.shell, 'mime_renderers', {})
 
         for mime, handler in handlers.items():
             if mime in data:
                 handler(data[mime], metadata.get(mime, None))
                 return
 
         if 'text/plain' in data:
             print(data['text/plain'])
 
     def clear_output(self, wait=False):
         """Clear the output of the cell receiving output."""
         print('\033[2K\r', end='')
         sys.stdout.flush()
         print('\033[2K\r', end='')
         sys.stderr.flush()
 
 
 class CapturingDisplayPublisher(DisplayPublisher):
     """A DisplayPublisher that stores"""
     outputs = List()
 
     def publish(self, data, metadata=None, source=None, *, transient=None, update=False):
         self.outputs.append({'data':data, 'metadata':metadata,
                              'transient':transient, 'update':update})
 
     def clear_output(self, wait=False):
         super(CapturingDisplayPublisher, self).clear_output(wait)
 
         # empty the list, *do not* reassign a new list
         self.outputs.clear()

IPython/core/magics/display.py

@@ -1,82 +1,82 b''
 """Simple magics for display formats"""
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2012 The IPython Development Team.
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Our own packages
-from IPython.core.display import display, Javascript, Latex, SVG, HTML, Markdown
+from IPython.display import display, Javascript, Latex, SVG, HTML, Markdown
 from IPython.core.magic import  (
     Magics, magics_class, cell_magic
 )
 from IPython.core import magic_arguments
 
 #-----------------------------------------------------------------------------
 # Magic implementation classes
 #-----------------------------------------------------------------------------
 
 
 @magics_class
 class DisplayMagics(Magics):
     """Magics for displaying various output types with literals
 
     Defines javascript/latex/svg/html cell magics for writing
     blocks in those languages, to be rendered in the frontend.
     """
 
     @cell_magic
     def js(self, line, cell):
         """Run the cell block of Javascript code
 
         Alias of `%%javascript`
         """
         self.javascript(line, cell)
 
     @cell_magic
     def javascript(self, line, cell):
         """Run the cell block of Javascript code"""
         display(Javascript(cell))
 
 
     @cell_magic
     def latex(self, line, cell):
         """Render the cell as a block of latex
 
         The subset of latex which is support depends on the implementation in
         the client.  In the Jupyter Notebook, this magic only renders the subset
         of latex defined by MathJax
         [here](https://docs.mathjax.org/en/v2.5-latest/tex.html)."""
         display(Latex(cell))
 
     @cell_magic
     def svg(self, line, cell):
         """Render the cell as an SVG literal"""
         display(SVG(cell))
 
     @magic_arguments.magic_arguments()
     @magic_arguments.argument(
         '--isolated', action='store_true', default=False,
         help="""Annotate the cell as 'isolated'.
 Isolated cells are rendered inside their own <iframe> tag"""
     )
     @cell_magic
     def html(self, line, cell):
         """Render the cell as a block of HTML"""
         args = magic_arguments.parse_argstring(self.html, line)
         html = HTML(cell)
         if args.isolated:
             display(html, metadata={'text/html':{'isolated':True}})
         else:
             display(html)
 
     @cell_magic
     def markdown(self, line, cell):
         """Render the cell as Markdown text block"""
         display(Markdown(cell))

IPython/core/page.py

@@ -1,343 +1,343 b''
 # encoding: utf-8
 """
 Paging capabilities for IPython.core
 
 Notes
 -----
 
 For now this uses IPython hooks, so it can't be in IPython.utils.  If we can get
 rid of that dependency, we could move it there.
 -----
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 import os
 import io
 import re
 import sys
 import tempfile
 import subprocess
 
 from io import UnsupportedOperation
 
 from IPython import get_ipython
-from IPython.core.display import display
+from IPython.display import display
 from IPython.core.error import TryNext
 from IPython.utils.data import chop
 from IPython.utils.process import system
 from IPython.utils.terminal import get_terminal_size
 from IPython.utils import py3compat
 
 
 def display_page(strng, start=0, screen_lines=25):
     """Just display, no paging. screen_lines is ignored."""
     if isinstance(strng, dict):
         data = strng
     else:
         if start:
             strng = u'\n'.join(strng.splitlines()[start:])
         data = { 'text/plain': strng }
     display(data, raw=True)
 
 
 def as_hook(page_func):
     """Wrap a pager func to strip the `self` arg
     
     so it can be called as a hook.
     """
     return lambda self, *args, **kwargs: page_func(*args, **kwargs)
 
 
 esc_re = re.compile(r"(\x1b[^m]+m)")
 
 def page_dumb(strng, start=0, screen_lines=25):
     """Very dumb 'pager' in Python, for when nothing else works.
 
     Only moves forward, same interface as page(), except for pager_cmd and
     mode.
     """
     if isinstance(strng, dict):
         strng = strng.get('text/plain', '')
     out_ln  = strng.splitlines()[start:]
     screens = chop(out_ln,screen_lines-1)
     if len(screens) == 1:
         print(os.linesep.join(screens[0]))
     else:
         last_escape = ""
         for scr in screens[0:-1]:
             hunk = os.linesep.join(scr)
             print(last_escape + hunk)
             if not page_more():
                 return
             esc_list = esc_re.findall(hunk)
             if len(esc_list) > 0:
                 last_escape = esc_list[-1]
         print(last_escape + os.linesep.join(screens[-1]))
 
 def _detect_screen_size(screen_lines_def):
     """Attempt to work out the number of lines on the screen.
 
     This is called by page(). It can raise an error (e.g. when run in the
     test suite), so it's separated out so it can easily be called in a try block.
     """
     TERM = os.environ.get('TERM',None)
     if not((TERM=='xterm' or TERM=='xterm-color') and sys.platform != 'sunos5'):
         # curses causes problems on many terminals other than xterm, and
         # some termios calls lock up on Sun OS5.
         return screen_lines_def
     
     try:
         import termios
         import curses
     except ImportError:
         return screen_lines_def
     
     # There is a bug in curses, where *sometimes* it fails to properly
     # initialize, and then after the endwin() call is made, the
     # terminal is left in an unusable state.  Rather than trying to
     # check every time for this (by requesting and comparing termios
     # flags each time), we just save the initial terminal state and
     # unconditionally reset it every time.  It's cheaper than making
     # the checks.
     try:
         term_flags = termios.tcgetattr(sys.stdout)
     except termios.error as err:
         # can fail on Linux 2.6, pager_page will catch the TypeError
         raise TypeError('termios error: {0}'.format(err))
 
     try:
         scr = curses.initscr()
     except AttributeError:
         # Curses on Solaris may not be complete, so we can't use it there
         return screen_lines_def
     
     screen_lines_real,screen_cols = scr.getmaxyx()
     curses.endwin()
 
     # Restore terminal state in case endwin() didn't.
     termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
     # Now we have what we needed: the screen size in rows/columns
     return screen_lines_real
     #print '***Screen size:',screen_lines_real,'lines x',\
     #screen_cols,'columns.' # dbg
 
 def pager_page(strng, start=0, screen_lines=0, pager_cmd=None):
     """Display a string, piping through a pager after a certain length.
     
     strng can be a mime-bundle dict, supplying multiple representations,
     keyed by mime-type.
 
     The screen_lines parameter specifies the number of *usable* lines of your
     terminal screen (total lines minus lines you need to reserve to show other
     information).
 
     If you set screen_lines to a number <=0, page() will try to auto-determine
     your screen size and will only use up to (screen_size+screen_lines) for
     printing, paging after that. That is, if you want auto-detection but need
     to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
     auto-detection without any lines reserved simply use screen_lines = 0.
 
     If a string won't fit in the allowed lines, it is sent through the
     specified pager command. If none given, look for PAGER in the environment,
     and ultimately default to less.
 
     If no system pager works, the string is sent through a 'dumb pager'
     written in python, very simplistic.
     """
     
     # for compatibility with mime-bundle form:
     if isinstance(strng, dict):
         strng = strng['text/plain']
 
     # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
     TERM = os.environ.get('TERM','dumb')
     if TERM in ['dumb','emacs'] and os.name != 'nt':
         print(strng)
         return
     # chop off the topmost part of the string we don't want to see
     str_lines = strng.splitlines()[start:]
     str_toprint = os.linesep.join(str_lines)
     num_newlines = len(str_lines)
     len_str = len(str_toprint)
 
     # Dumb heuristics to guesstimate number of on-screen lines the string
     # takes.  Very basic, but good enough for docstrings in reasonable
     # terminals. If someone later feels like refining it, it's not hard.
     numlines = max(num_newlines,int(len_str/80)+1)
 
     screen_lines_def = get_terminal_size()[1]
 
     # auto-determine screen size
     if screen_lines <= 0:
         try:
             screen_lines += _detect_screen_size(screen_lines_def)
         except (TypeError, UnsupportedOperation):
             print(str_toprint)
             return
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :
         #print '*** normal print'  # dbg
         print(str_toprint)
     else:
         # Try to open pager and default to internal one if that fails.
         # All failure modes are tagged as 'retval=1', to match the return
         # value of a failed system command.  If any intermediate attempt
         # sets retval to 1, at the end we resort to our own page_dumb() pager.
         pager_cmd = get_pager_cmd(pager_cmd)
         pager_cmd += ' ' + get_pager_start(pager_cmd,start)
         if os.name == 'nt':
             if pager_cmd.startswith('type'):
                 # The default WinXP 'type' command is failing on complex strings.
                 retval = 1
             else:
                 fd, tmpname = tempfile.mkstemp('.txt')
                 try:
                     os.close(fd)
                     with open(tmpname, 'wt') as tmpfile:
                         tmpfile.write(strng)
                         cmd = "%s < %s" % (pager_cmd, tmpname)
                     # tmpfile needs to be closed for windows
                     if os.system(cmd):
                         retval = 1
                     else:
                         retval = None
                 finally:
                     os.remove(tmpname)
         else:
             try:
                 retval = None
                 # Emulate os.popen, but redirect stderr
                 proc = subprocess.Popen(pager_cmd,
                                 shell=True,
                                 stdin=subprocess.PIPE,
                                 stderr=subprocess.DEVNULL
                                 )
                 pager = os._wrap_close(io.TextIOWrapper(proc.stdin), proc)
                 try:
                     pager_encoding = pager.encoding or sys.stdout.encoding
                     pager.write(strng)
                 finally:
                     retval = pager.close()
             except IOError as msg:  # broken pipe when user quits
                 if msg.args == (32, 'Broken pipe'):
                     retval = None
                 else:
                     retval = 1
             except OSError:
                 # Other strange problems, sometimes seen in Win2k/cygwin
                 retval = 1
         if retval is not None:
             page_dumb(strng,screen_lines=screen_lines)
 
 
 def page(data, start=0, screen_lines=0, pager_cmd=None):
     """Display content in a pager, piping through a pager after a certain length.
     
     data can be a mime-bundle dict, supplying multiple representations,
     keyed by mime-type, or text.
     
     Pager is dispatched via the `show_in_pager` IPython hook.
     If no hook is registered, `pager_page` will be used.
     """
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0, start)
 
     # first, try the hook
     ip = get_ipython()
     if ip:
         try:
             ip.hooks.show_in_pager(data, start=start, screen_lines=screen_lines)
             return
         except TryNext:
             pass
     
     # fallback on default pager
     return pager_page(data, start, screen_lines, pager_cmd)
 
 
 def page_file(fname, start=0, pager_cmd=None):
     """Page a file, using an optional pager command and starting line.
     """
 
     pager_cmd = get_pager_cmd(pager_cmd)
     pager_cmd += ' ' + get_pager_start(pager_cmd,start)
 
     try:
         if os.environ['TERM'] in ['emacs','dumb']:
             raise EnvironmentError
         system(pager_cmd + ' ' + fname)
     except:
         try:
             if start > 0:
                 start -= 1
             page(open(fname).read(),start)
         except:
             print('Unable to show file',repr(fname))
 
 
 def get_pager_cmd(pager_cmd=None):
     """Return a pager command.
 
     Makes some attempts at finding an OS-correct one.
     """
     if os.name == 'posix':
         default_pager_cmd = 'less -R'  # -R for color control sequences
     elif os.name in ['nt','dos']:
         default_pager_cmd = 'type'
 
     if pager_cmd is None:
         try:
             pager_cmd = os.environ['PAGER']
         except:
             pager_cmd = default_pager_cmd
     
     if pager_cmd == 'less' and '-r' not in os.environ.get('LESS', '').lower():
         pager_cmd += ' -R'
     
     return pager_cmd
 
 
 def get_pager_start(pager, start):
     """Return the string for paging files with an offset.
 
     This is the '+N' argument which less and more (under Unix) accept.
     """
 
     if pager in ['less','more']:
         if start:
             start_string = '+' + str(start)
         else:
             start_string = ''
     else:
         start_string = ''
     return start_string
 
 
 # (X)emacs on win32 doesn't like to be bypassed with msvcrt.getch()
 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
     import msvcrt
     def page_more():
         """ Smart pausing between pages
 
         @return:    True if need print more lines, False if quit
         """
         sys.stdout.write('---Return to continue, q to quit--- ')
         ans = msvcrt.getwch()
         if ans in ("q", "Q"):
             result = False
         else:
             result = True
         sys.stdout.write("\b"*37 + " "*37 + "\b"*37)
         return result
 else:
     def page_more():
         ans = py3compat.input('---Return to continue, q to quit--- ')
         if ans.lower().startswith('q'):
             return False
         else:
             return True

IPython/core/pylabtools.py

@@ -1,419 +1,419 b''
 # -*- coding: utf-8 -*-
 """Pylab (matplotlib) support utilities."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from io import BytesIO
 
 from IPython.core.display import _pngxy
 from IPython.utils.decorators import flag_calls
 
 # If user specifies a GUI, that dictates the backend, otherwise we read the
 # user's mpl default from the mpl rc structure
 backends = {'tk': 'TkAgg',
             'gtk': 'GTKAgg',
             'gtk3': 'GTK3Agg',
             'wx': 'WXAgg',
             'qt4': 'Qt4Agg',
             'qt5': 'Qt5Agg',
             'qt': 'Qt5Agg',
             'osx': 'MacOSX',
             'nbagg': 'nbAgg',
             'notebook': 'nbAgg',
             'agg': 'agg',
             'svg': 'svg',
             'pdf': 'pdf',
             'ps': 'ps',
             'inline': 'module://ipykernel.pylab.backend_inline',
             'ipympl': 'module://ipympl.backend_nbagg',
             'widget': 'module://ipympl.backend_nbagg',
             }
 
 # We also need a reverse backends2guis mapping that will properly choose which
 # GUI support to activate based on the desired matplotlib backend.  For the
 # most part it's just a reverse of the above dict, but we also need to add a
 # few others that map to the same GUI manually:
 backend2gui = dict(zip(backends.values(), backends.keys()))
 # Our tests expect backend2gui to just return 'qt'
 backend2gui['Qt4Agg'] = 'qt'
 # In the reverse mapping, there are a few extra valid matplotlib backends that
 # map to the same GUI support
 backend2gui['GTK'] = backend2gui['GTKCairo'] = 'gtk'
 backend2gui['GTK3Cairo'] = 'gtk3'
 backend2gui['WX'] = 'wx'
 backend2gui['CocoaAgg'] = 'osx'
 # And some backends that don't need GUI integration
 del backend2gui['nbAgg']
 del backend2gui['agg']
 del backend2gui['svg']
 del backend2gui['pdf']
 del backend2gui['ps']
 del backend2gui['module://ipykernel.pylab.backend_inline']
 
 #-----------------------------------------------------------------------------
 # Matplotlib utilities
 #-----------------------------------------------------------------------------
 
 
 def getfigs(*fig_nums):
     """Get a list of matplotlib figures by figure numbers.
 
     If no arguments are given, all available figures are returned.  If the
     argument list contains references to invalid figures, a warning is printed
     but the function continues pasting further figures.
 
     Parameters
     ----------
     figs : tuple
         A tuple of ints giving the figure numbers of the figures to return.
     """
     from matplotlib._pylab_helpers import Gcf
     if not fig_nums:
         fig_managers = Gcf.get_all_fig_managers()
         return [fm.canvas.figure for fm in fig_managers]
     else:
         figs = []
         for num in fig_nums:
             f = Gcf.figs.get(num)
             if f is None:
                 print('Warning: figure %s not available.' % num)
             else:
                 figs.append(f.canvas.figure)
         return figs
 
 
 def figsize(sizex, sizey):
     """Set the default figure size to be [sizex, sizey].
 
     This is just an easy to remember, convenience wrapper that sets::
 
       matplotlib.rcParams['figure.figsize'] = [sizex, sizey]
     """
     import matplotlib
     matplotlib.rcParams['figure.figsize'] = [sizex, sizey]
 
 
 def print_figure(fig, fmt='png', bbox_inches='tight', **kwargs):
     """Print a figure to an image, and return the resulting file data
     
     Returned data will be bytes unless ``fmt='svg'``,
     in which case it will be unicode.
     
     Any keyword args are passed to fig.canvas.print_figure,
     such as ``quality`` or ``bbox_inches``.
     """
     # When there's an empty figure, we shouldn't return anything, otherwise we
     # get big blank areas in the qt console.
     if not fig.axes and not fig.lines:
         return
 
     dpi = fig.dpi
     if fmt == 'retina':
         dpi = dpi * 2
         fmt = 'png'
     
     # build keyword args
     kw = {
         "format":fmt,
         "facecolor":fig.get_facecolor(),
         "edgecolor":fig.get_edgecolor(),
         "dpi":dpi,
         "bbox_inches":bbox_inches,
     }
     # **kwargs get higher priority
     kw.update(kwargs)
 
     bytes_io = BytesIO()
     if fig.canvas is None:
         from matplotlib.backend_bases import FigureCanvasBase
         FigureCanvasBase(fig)
 
     fig.canvas.print_figure(bytes_io, **kw)
     data = bytes_io.getvalue()
     if fmt == 'svg':
         data = data.decode('utf-8')
     return data
 
 def retina_figure(fig, **kwargs):
     """format a figure as a pixel-doubled (retina) PNG"""
     pngdata = print_figure(fig, fmt='retina', **kwargs)
     # Make sure that retina_figure acts just like print_figure and returns
     # None when the figure is empty.
     if pngdata is None:
         return
     w, h = _pngxy(pngdata)
     metadata = {"width": w//2, "height":h//2}
     return pngdata, metadata
 
 # We need a little factory function here to create the closure where
 # safe_execfile can live.
 def mpl_runner(safe_execfile):
     """Factory to return a matplotlib-enabled runner for %run.
 
     Parameters
     ----------
     safe_execfile : function
       This must be a function with the same interface as the
       :meth:`safe_execfile` method of IPython.
 
     Returns
     -------
     A function suitable for use as the ``runner`` argument of the %run magic
     function.
     """
     
     def mpl_execfile(fname,*where,**kw):
         """matplotlib-aware wrapper around safe_execfile.
 
         Its interface is identical to that of the :func:`execfile` builtin.
 
         This is ultimately a call to execfile(), but wrapped in safeties to
         properly handle interactive rendering."""
 
         import matplotlib
         import matplotlib.pyplot as plt
 
         #print '*** Matplotlib runner ***' # dbg
         # turn off rendering until end of script
         is_interactive = matplotlib.rcParams['interactive']
         matplotlib.interactive(False)
         safe_execfile(fname,*where,**kw)
         matplotlib.interactive(is_interactive)
         # make rendering call now, if the user tried to do it
         if plt.draw_if_interactive.called:
             plt.draw()
             plt.draw_if_interactive.called = False
 
         # re-draw everything that is stale
         try:
             da = plt.draw_all
         except AttributeError:
             pass
         else:
             da()
 
     return mpl_execfile
 
 
 def _reshow_nbagg_figure(fig):
     """reshow an nbagg figure"""
     try:
         reshow = fig.canvas.manager.reshow
     except AttributeError:
         raise NotImplementedError()
     else:
         reshow()
 
 
 def select_figure_formats(shell, formats, **kwargs):
     """Select figure formats for the inline backend.
 
     Parameters
     ==========
     shell : InteractiveShell
         The main IPython instance.
     formats : str or set
         One or a set of figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
     **kwargs : any
         Extra keyword arguments to be passed to fig.canvas.print_figure.
     """
     import matplotlib
     from matplotlib.figure import Figure
 
     svg_formatter = shell.display_formatter.formatters['image/svg+xml']
     png_formatter = shell.display_formatter.formatters['image/png']
     jpg_formatter = shell.display_formatter.formatters['image/jpeg']
     pdf_formatter = shell.display_formatter.formatters['application/pdf']
 
     if isinstance(formats, str):
         formats = {formats}
     # cast in case of list / tuple
     formats = set(formats)
 
     [ f.pop(Figure, None) for f in shell.display_formatter.formatters.values() ]
     mplbackend = matplotlib.get_backend().lower()
     if mplbackend == 'nbagg' or mplbackend == 'module://ipympl.backend_nbagg':
         formatter = shell.display_formatter.ipython_display_formatter
         formatter.for_type(Figure, _reshow_nbagg_figure)
 
     supported = {'png', 'png2x', 'retina', 'jpg', 'jpeg', 'svg', 'pdf'}
     bad = formats.difference(supported)
     if bad:
         bs = "%s" % ','.join([repr(f) for f in bad])
         gs = "%s" % ','.join([repr(f) for f in supported])
         raise ValueError("supported formats are: %s not %s" % (gs, bs))
     
     if 'png' in formats:
         png_formatter.for_type(Figure, lambda fig: print_figure(fig, 'png', **kwargs))
     if 'retina' in formats or 'png2x' in formats:
         png_formatter.for_type(Figure, lambda fig: retina_figure(fig, **kwargs))
     if 'jpg' in formats or 'jpeg' in formats:
         jpg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'jpg', **kwargs))
     if 'svg' in formats:
         svg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'svg', **kwargs))
     if 'pdf' in formats:
         pdf_formatter.for_type(Figure, lambda fig: print_figure(fig, 'pdf', **kwargs))
 
 #-----------------------------------------------------------------------------
 # Code for initializing matplotlib and importing pylab
 #-----------------------------------------------------------------------------
 
 
 def find_gui_and_backend(gui=None, gui_select=None):
     """Given a gui string return the gui and mpl backend.
 
     Parameters
     ----------
     gui : str
         Can be one of ('tk','gtk','wx','qt','qt4','inline','agg').
     gui_select : str
         Can be one of ('tk','gtk','wx','qt','qt4','inline').
         This is any gui already selected by the shell.
 
     Returns
     -------
     A tuple of (gui, backend) where backend is one of ('TkAgg','GTKAgg',
     'WXAgg','Qt4Agg','module://ipykernel.pylab.backend_inline','agg').
     """
 
     import matplotlib
 
     if gui and gui != 'auto':
         # select backend based on requested gui
         backend = backends[gui]
         if gui == 'agg':
             gui = None
     else:
         # We need to read the backend from the original data structure, *not*
         # from mpl.rcParams, since a prior invocation of %matplotlib may have
         # overwritten that.
         # WARNING: this assumes matplotlib 1.1 or newer!!
         backend = matplotlib.rcParamsOrig['backend']
         # In this case, we need to find what the appropriate gui selection call
         # should be for IPython, so we can activate inputhook accordingly
         gui = backend2gui.get(backend, None)
 
         # If we have already had a gui active, we need it and inline are the
         # ones allowed.
         if gui_select and gui != gui_select:
             gui = gui_select
             backend = backends[gui]
 
     return gui, backend
 
 
 def activate_matplotlib(backend):
     """Activate the given backend and set interactive to True."""
 
     import matplotlib
     matplotlib.interactive(True)
     
     # Matplotlib had a bug where even switch_backend could not force
     # the rcParam to update. This needs to be set *before* the module
     # magic of switch_backend().
     matplotlib.rcParams['backend'] = backend
 
     # Due to circular imports, pyplot may be only partially initialised
     # when this function runs.
     # So avoid needing matplotlib attribute-lookup to access pyplot.
     from matplotlib import pyplot as plt
 
     plt.switch_backend(backend)
 
     plt.show._needmain = False
     # We need to detect at runtime whether show() is called by the user.
     # For this, we wrap it into a decorator which adds a 'called' flag.
     plt.draw_if_interactive = flag_calls(plt.draw_if_interactive)
 
 
 def import_pylab(user_ns, import_all=True):
     """Populate the namespace with pylab-related values.
     
     Imports matplotlib, pylab, numpy, and everything from pylab and numpy.
     
     Also imports a few names from IPython (figsize, display, getfigs)
     
     """
 
     # Import numpy as np/pyplot as plt are conventions we're trying to
     # somewhat standardize on.  Making them available to users by default
     # will greatly help this.
     s = ("import numpy\n"
           "import matplotlib\n"
           "from matplotlib import pylab, mlab, pyplot\n"
           "np = numpy\n"
           "plt = pyplot\n"
           )
     exec(s, user_ns)
     
     if import_all:
         s = ("from matplotlib.pylab import *\n"
              "from numpy import *\n")
         exec(s, user_ns)
     
     # IPython symbols to add
     user_ns['figsize'] = figsize
-    from IPython.core.display import display
+    from IPython.display import display
     # Add display and getfigs to the user's namespace
     user_ns['display'] = display
     user_ns['getfigs'] = getfigs
 
 
 def configure_inline_support(shell, backend):
     """Configure an IPython shell object for matplotlib use.
 
     Parameters
     ----------
     shell : InteractiveShell instance
 
     backend : matplotlib backend
     """
     # If using our svg payload backend, register the post-execution
     # function that will pick up the results for display.  This can only be
     # done with access to the real shell object.
 
     # Note: if we can't load the inline backend, then there's no point
     # continuing (such as in terminal-only shells in environments without
     # zeromq available).
     try:
         from ipykernel.pylab.backend_inline import InlineBackend
     except ImportError:
         return
     import matplotlib
 
     cfg = InlineBackend.instance(parent=shell)
     cfg.shell = shell
     if cfg not in shell.configurables:
         shell.configurables.append(cfg)
 
     if backend == backends['inline']:
         from ipykernel.pylab.backend_inline import flush_figures
         shell.events.register('post_execute', flush_figures)
 
         # Save rcParams that will be overwrittern
         shell._saved_rcParams = {}
         for k in cfg.rc:
             shell._saved_rcParams[k] = matplotlib.rcParams[k]
         # load inline_rc
         matplotlib.rcParams.update(cfg.rc)
         new_backend_name = "inline"
     else:
         from ipykernel.pylab.backend_inline import flush_figures
         try:
             shell.events.unregister('post_execute', flush_figures)
         except ValueError:
             pass
         if hasattr(shell, '_saved_rcParams'):
             matplotlib.rcParams.update(shell._saved_rcParams)
             del shell._saved_rcParams
         new_backend_name = "other"
 
     # only enable the formats once -> don't change the enabled formats (which the user may
     # has changed) when getting another "%matplotlib inline" call.
     # See https://github.com/ipython/ipykernel/issues/29
     cur_backend = getattr(configure_inline_support, "current_backend", "unset")
     if new_backend_name != cur_backend:
         # Setup the default figure format
         select_figure_formats(shell, cfg.figure_formats, **cfg.print_figure_kwargs)
         configure_inline_support.current_backend = new_backend_name

IPython/core/tests/test_display.py

@@ -1,460 +1,460 b''
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import json
 import os
 import warnings
 
 from unittest import mock
 
 import nose.tools as nt
 
-from IPython.core import display
+from IPython import display
 from IPython.core.getipython import get_ipython
 from IPython.utils.io import capture_output
 from IPython.utils.tempdir import NamedFileInTemporaryDirectory
 from IPython import paths as ipath
 from IPython.testing.tools import AssertNotPrints
 
 import IPython.testing.decorators as dec
 
 def test_image_size():
     """Simple test for display.Image(args, width=x,height=y)"""
     thisurl = 'http://www.google.fr/images/srpr/logo3w.png'
     img = display.Image(url=thisurl, width=200, height=200)
     nt.assert_equal(u'<img src="%s" width="200" height="200"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl, metadata={'width':200, 'height':200})
     nt.assert_equal(u'<img src="%s" width="200" height="200"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl, width=200)
     nt.assert_equal(u'<img src="%s" width="200"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl)
     nt.assert_equal(u'<img src="%s"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl, unconfined=True)
     nt.assert_equal(u'<img src="%s" class="unconfined"/>' % (thisurl), img._repr_html_())
 
 
 def test_image_mimes():
     fmt = get_ipython().display_formatter.format
     for format in display.Image._ACCEPTABLE_EMBEDDINGS:
         mime = display.Image._MIMETYPES[format]
         img = display.Image(b'garbage', format=format)
         data, metadata = fmt(img)
         nt.assert_equal(sorted(data), sorted([mime, 'text/plain']))
 
 
 def test_geojson():
 
     gj = display.GeoJSON(data={
             "type": "Feature",
             "geometry": {
                 "type": "Point",
                 "coordinates": [-81.327, 296.038]
             },
             "properties": {
                 "name": "Inca City"
             }
         },
         url_template="http://s3-eu-west-1.amazonaws.com/whereonmars.cartodb.net/{basemap_id}/{z}/{x}/{y}.png",
         layer_options={
             "basemap_id": "celestia_mars-shaded-16k_global",
             "attribution": "Celestia/praesepe",
             "minZoom": 0,
             "maxZoom": 18,
         })
     nt.assert_equal(u'<IPython.core.display.GeoJSON object>', str(gj))
 
 def test_retina_png():
     here = os.path.dirname(__file__)
     img = display.Image(os.path.join(here, "2x2.png"), retina=True)
     nt.assert_equal(img.height, 1)
     nt.assert_equal(img.width, 1)
     data, md = img._repr_png_()
     nt.assert_equal(md['width'], 1)
     nt.assert_equal(md['height'], 1)
 
 def test_embed_svg_url():
     import gzip
     from io import BytesIO
     svg_data = b'<svg><circle x="0" y="0" r="1"/></svg>'
     url = 'http://test.com/circle.svg'
     
     gzip_svg = BytesIO()
     with gzip.open(gzip_svg, 'wb') as fp:
         fp.write(svg_data)
     gzip_svg = gzip_svg.getvalue()
     
     def mocked_urlopen(*args, **kwargs):
         class MockResponse:
             def __init__(self, svg):
                 self._svg_data = svg
                 self.headers = {'content-type': 'image/svg+xml'}
 
             def read(self):
                 return self._svg_data
 
         if args[0] == url:
             return MockResponse(svg_data)
         elif args[0] == url + 'z':          
             ret= MockResponse(gzip_svg)
             ret.headers['content-encoding']= 'gzip'
             return ret
         return MockResponse(None)
 
     with mock.patch('urllib.request.urlopen', side_effect=mocked_urlopen):
         svg = display.SVG(url=url)
         nt.assert_true(svg._repr_svg_().startswith('<svg'))
         svg = display.SVG(url=url + 'z')
         nt.assert_true(svg._repr_svg_().startswith('<svg'))
 
     # do it for real: 6.1kB of data
     url = "https://upload.wikimedia.org/wikipedia/commons/3/30/Vector-based_example.svg"
     svg = display.SVG(url=url)
     nt.assert_true(svg._repr_svg_().startswith('<svg'))
     
 def test_retina_jpeg():
     here = os.path.dirname(__file__)
     img = display.Image(os.path.join(here, "2x2.jpg"), retina=True)
     nt.assert_equal(img.height, 1)
     nt.assert_equal(img.width, 1)
     data, md = img._repr_jpeg_()
     nt.assert_equal(md['width'], 1)
     nt.assert_equal(md['height'], 1)
 
 def test_base64image():
     display.Image("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEUAAACnej3aAAAAAWJLR0QAiAUdSAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB94BCRQnOqNu0b4AAAAKSURBVAjXY2AAAAACAAHiIbwzAAAAAElFTkSuQmCC")
 
 def test_image_filename_defaults():
     '''test format constraint, and validity of jpeg and png'''
     tpath = ipath.get_ipython_package_dir()
     nt.assert_raises(ValueError, display.Image, filename=os.path.join(tpath, 'testing/tests/badformat.zip'),
                      embed=True)
     nt.assert_raises(ValueError, display.Image)
     nt.assert_raises(ValueError, display.Image, data='this is not an image', format='badformat', embed=True)
     # check boths paths to allow packages to test at build and install time
     imgfile = os.path.join(tpath, 'core/tests/2x2.png')
     img = display.Image(filename=imgfile)
     nt.assert_equal('png', img.format)
     nt.assert_is_not_none(img._repr_png_())
     img = display.Image(filename=os.path.join(tpath, 'testing/tests/logo.jpg'), embed=False)
     nt.assert_equal('jpeg', img.format)
     nt.assert_is_none(img._repr_jpeg_())
 
 def _get_inline_config():
     from ipykernel.pylab.config import InlineBackend
     return InlineBackend.instance()
 
 @dec.skip_without('matplotlib')
 def test_set_matplotlib_close():
     cfg = _get_inline_config()
     cfg.close_figures = False
     display.set_matplotlib_close()
     assert cfg.close_figures
     display.set_matplotlib_close(False)
     assert not cfg.close_figures
 
 _fmt_mime_map = {
     'png': 'image/png',
     'jpeg': 'image/jpeg',
     'pdf': 'application/pdf',
     'retina': 'image/png',
     'svg': 'image/svg+xml',
 }
 
 @dec.skip_without('matplotlib')
 def test_set_matplotlib_formats():
     from matplotlib.figure import Figure
     formatters = get_ipython().display_formatter.formatters
     for formats in [
         ('png',),
         ('pdf', 'svg'),
         ('jpeg', 'retina', 'png'),
         (),
     ]:
         active_mimes = {_fmt_mime_map[fmt] for fmt in formats}
         display.set_matplotlib_formats(*formats)
         for mime, f in formatters.items():
             if mime in active_mimes:
                 nt.assert_in(Figure, f)
             else:
                 nt.assert_not_in(Figure, f)
 
 @dec.skip_without('matplotlib')
 def test_set_matplotlib_formats_kwargs():
     from matplotlib.figure import Figure
     ip = get_ipython()
     cfg = _get_inline_config()
     cfg.print_figure_kwargs.update(dict(foo='bar'))
     kwargs = dict(quality=10)
     display.set_matplotlib_formats('png', **kwargs)
     formatter = ip.display_formatter.formatters['image/png']
     f = formatter.lookup_by_type(Figure)
     cell = f.__closure__[0].cell_contents
     expected = kwargs
     expected.update(cfg.print_figure_kwargs)
     nt.assert_equal(cell, expected)
 
 def test_display_available():
     """
     Test that display is available without import
 
     We don't really care if it's in builtin or anything else, but it should
     always be available.
     """
     ip = get_ipython()
     with AssertNotPrints('NameError'):
         ip.run_cell('display')
     try:
         ip.run_cell('del display')
     except NameError:
         pass # it's ok, it might be in builtins
     # even if deleted it should be back
     with AssertNotPrints('NameError'):
         ip.run_cell('display')
 
 def test_textdisplayobj_pretty_repr():
      p = display.Pretty("This is a simple test")
      nt.assert_equal(repr(p), '<IPython.core.display.Pretty object>')
      nt.assert_equal(p.data, 'This is a simple test')
 
      p._show_mem_addr = True
      nt.assert_equal(repr(p), object.__repr__(p))
 
 def test_displayobject_repr():
     h = display.HTML('<br />')
     nt.assert_equal(repr(h), '<IPython.core.display.HTML object>')
     h._show_mem_addr = True
     nt.assert_equal(repr(h), object.__repr__(h))
     h._show_mem_addr = False
     nt.assert_equal(repr(h), '<IPython.core.display.HTML object>')
 
     j = display.Javascript('')
     nt.assert_equal(repr(j), '<IPython.core.display.Javascript object>')
     j._show_mem_addr = True
     nt.assert_equal(repr(j), object.__repr__(j))
     j._show_mem_addr = False
     nt.assert_equal(repr(j), '<IPython.core.display.Javascript object>')
 
 @mock.patch('warnings.warn')
 def test_encourage_iframe_over_html(m_warn):
     display.HTML()
     m_warn.assert_not_called()
 
     display.HTML('<br />')
     m_warn.assert_not_called()
 
     display.HTML('<html><p>Lots of content here</p><iframe src="http://a.com"></iframe>')
     m_warn.assert_not_called()
 
     display.HTML('<iframe src="http://a.com"></iframe>')
     m_warn.assert_called_with('Consider using IPython.display.IFrame instead')
 
     m_warn.reset_mock()
     display.HTML('<IFRAME SRC="http://a.com"></IFRAME>')
     m_warn.assert_called_with('Consider using IPython.display.IFrame instead')
 
 def test_progress():
     p = display.ProgressBar(10)
     nt.assert_in('0/10',repr(p))
     p.html_width = '100%'
     p.progress = 5
     nt.assert_equal(p._repr_html_(), "<progress style='width:100%' max='10' value='5'></progress>")
 
 def test_progress_iter():
     with capture_output(display=False) as captured:
         for i in display.ProgressBar(5):
             out = captured.stdout
             nt.assert_in('{0}/5'.format(i), out)
     out = captured.stdout
     nt.assert_in('5/5', out)
 
 def test_json():
     d = {'a': 5}
     lis = [d]
     metadata = [
         {'expanded': False, 'root': 'root'},
         {'expanded': True,  'root': 'root'},
         {'expanded': False, 'root': 'custom'},
         {'expanded': True,  'root': 'custom'},
     ]
     json_objs = [
         display.JSON(d),
         display.JSON(d, expanded=True),
         display.JSON(d, root='custom'),
         display.JSON(d, expanded=True, root='custom'),
     ]
     for j, md in zip(json_objs, metadata):
         nt.assert_equal(j._repr_json_(), (d, md))
 
     with warnings.catch_warnings(record=True) as w:
         warnings.simplefilter("always")
         j = display.JSON(json.dumps(d))
         nt.assert_equal(len(w), 1)
         nt.assert_equal(j._repr_json_(), (d, metadata[0]))
 
     json_objs = [
         display.JSON(lis),
         display.JSON(lis, expanded=True),
         display.JSON(lis, root='custom'),
         display.JSON(lis, expanded=True, root='custom'),
     ]
     for j, md in zip(json_objs, metadata):
         nt.assert_equal(j._repr_json_(), (lis, md))
 
     with warnings.catch_warnings(record=True) as w:
         warnings.simplefilter("always")
         j = display.JSON(json.dumps(lis))
         nt.assert_equal(len(w), 1)
         nt.assert_equal(j._repr_json_(), (lis, metadata[0]))
 
 def test_video_embedding():
     """use a tempfile, with dummy-data, to ensure that video embedding doesn't crash"""
     v = display.Video("http://ignored")
     assert not v.embed
     html = v._repr_html_()
     nt.assert_not_in('src="data:', html)
     nt.assert_in('src="http://ignored"', html)
 
     with nt.assert_raises(ValueError):
         v = display.Video(b'abc')
 
     with NamedFileInTemporaryDirectory('test.mp4') as f:
         f.write(b'abc')
         f.close()
 
         v = display.Video(f.name)
         assert not v.embed
         html = v._repr_html_()
         nt.assert_not_in('src="data:', html)
 
         v = display.Video(f.name, embed=True)
         html = v._repr_html_()
         nt.assert_in('src="data:video/mp4;base64,YWJj"',html)
 
         v = display.Video(f.name, embed=True, mimetype='video/other')
         html = v._repr_html_()
         nt.assert_in('src="data:video/other;base64,YWJj"',html)
 
         v = display.Video(b'abc', embed=True, mimetype='video/mp4')
         html = v._repr_html_()
         nt.assert_in('src="data:video/mp4;base64,YWJj"',html)
 
         v = display.Video(u'YWJj', embed=True, mimetype='video/xyz')
         html = v._repr_html_()
         nt.assert_in('src="data:video/xyz;base64,YWJj"',html)
 
 def test_html_metadata():
     s = "<h1>Test</h1>"
     h = display.HTML(s, metadata={"isolated": True})
     nt.assert_equal(h._repr_html_(), (s, {"isolated": True}))
 
 def test_display_id():
     ip = get_ipython()
     with mock.patch.object(ip.display_pub, 'publish') as pub:
         handle = display.display('x')
         nt.assert_is(handle, None)
         handle = display.display('y', display_id='secret')
         nt.assert_is_instance(handle, display.DisplayHandle)
         handle2 = display.display('z', display_id=True)
         nt.assert_is_instance(handle2, display.DisplayHandle)
     nt.assert_not_equal(handle.display_id, handle2.display_id)
 
     nt.assert_equal(pub.call_count, 3)
     args, kwargs = pub.call_args_list[0]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('x')
         },
         'metadata': {},
     })
     args, kwargs = pub.call_args_list[1]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('y')
         },
         'metadata': {},
         'transient': {
             'display_id': handle.display_id,
         },
     })
     args, kwargs = pub.call_args_list[2]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('z')
         },
         'metadata': {},
         'transient': {
             'display_id': handle2.display_id,
         },
     })
 
 
 def test_update_display():
     ip = get_ipython()
     with mock.patch.object(ip.display_pub, 'publish') as pub:
         with nt.assert_raises(TypeError):
             display.update_display('x')
         display.update_display('x', display_id='1')
         display.update_display('y', display_id='2')
     args, kwargs = pub.call_args_list[0]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('x')
         },
         'metadata': {},
         'transient': {
             'display_id': '1',
         },
         'update': True,
     })
     args, kwargs = pub.call_args_list[1]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('y')
         },
         'metadata': {},
         'transient': {
             'display_id': '2',
         },
         'update': True,
     })
 
 
 def test_display_handle():
     ip = get_ipython()
     handle = display.DisplayHandle()
     nt.assert_is_instance(handle.display_id, str)
     handle = display.DisplayHandle('my-id')
     nt.assert_equal(handle.display_id, 'my-id')
     with mock.patch.object(ip.display_pub, 'publish') as pub:
         handle.display('x')
         handle.update('y')
 
     args, kwargs = pub.call_args_list[0]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('x')
         },
         'metadata': {},
         'transient': {
             'display_id': handle.display_id,
         }
     })
     args, kwargs = pub.call_args_list[1]
     nt.assert_equal(args, ())
     nt.assert_equal(kwargs, {
         'data': {
             'text/plain': repr('y')
         },
         'metadata': {},
         'transient': {
             'display_id': handle.display_id,
         },
         'update': True,
     })
 

IPython/display.py

@@ -1,16 +1,44 b''
 """Public API for display tools in IPython.
 """
 
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 #       Copyright (C) 2012 The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # Imports
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 
-from IPython.core.display import *
+from IPython.core.display_functions import *
+from IPython.core.display import (
+    display_pretty,
+    display_html,
+    display_markdown,
+    display_svg,
+    display_png,
+    display_jpeg,
+    display_latex,
+    display_json,
+    display_javascript,
+    display_pdf,
+    DisplayObject,
+    TextDisplayObject,
+    Pretty,
+    HTML,
+    Markdown,
+    Math,
+    Latex,
+    SVG,
+    ProgressBar,
+    JSON,
+    GeoJSON,
+    Javascript,
+    Image,
+    set_matplotlib_formats,
+    set_matplotlib_close,
+    Video,
+)
 from IPython.lib.display import *

IPython/testing/iptest.py

@@ -1,457 +1,458 b''
 # -*- coding: utf-8 -*-
 """IPython Test Suite Runner.
 
 This module provides a main entry point to a user script to test IPython
 itself from the command line. There are two ways of running this script:
 
 1. With the syntax `iptest all`.  This runs our entire test suite by
    calling this script (with different arguments) recursively.  This
    causes modules and package to be tested in different processes, using nose
    or trial where appropriate.
 2. With the regular nose syntax, like `iptest IPython -- -vvs`. In this form
    the script simply calls nose, but with special command line flags and
    plugins loaded. Options after `--` are passed to nose.
 
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 import glob
 from io import BytesIO
 import os
 import os.path as path
 import sys
 from threading import Thread, Lock, Event
 import warnings
 
 import nose.plugins.builtin
 from nose.plugins.xunit import Xunit
 from nose import SkipTest
 from nose.core import TestProgram
 from nose.plugins import Plugin
 from nose.util import safe_str
 
 from IPython import version_info
 from IPython.utils.py3compat import decode
 from IPython.utils.importstring import import_item
 from IPython.testing.plugin.ipdoctest import IPythonDoctest
 from IPython.external.decorators import KnownFailure, knownfailureif
 
 pjoin = path.join
 
 
 # Enable printing all warnings raise by IPython's modules
 warnings.filterwarnings('ignore', message='.*Matplotlib is building the font cache.*', category=UserWarning, module='.*')
 warnings.filterwarnings('error', message='.*', category=ResourceWarning, module='.*')
 warnings.filterwarnings('error', message=".*{'config': True}.*", category=DeprecationWarning, module='IPy.*')
 warnings.filterwarnings('default', message='.*', category=Warning, module='IPy.*')
 
 warnings.filterwarnings('error', message='.*apply_wrapper.*', category=DeprecationWarning, module='.*')
 warnings.filterwarnings('error', message='.*make_label_dec', category=DeprecationWarning, module='.*')
 warnings.filterwarnings('error', message='.*decorated_dummy.*', category=DeprecationWarning, module='.*')
 warnings.filterwarnings('error', message='.*skip_file_no_x11.*', category=DeprecationWarning, module='.*')
 warnings.filterwarnings('error', message='.*onlyif_any_cmd_exists.*', category=DeprecationWarning, module='.*')
 
 warnings.filterwarnings('error', message='.*disable_gui.*', category=DeprecationWarning, module='.*')
 
 warnings.filterwarnings('error', message='.*ExceptionColors global is deprecated.*', category=DeprecationWarning, module='.*')
+warnings.filterwarnings('error', message='.*IPython.core.display.*', category=DeprecationWarning, module='.*')
 
 # Jedi older versions
 warnings.filterwarnings(
     'error', message='.*elementwise != comparison failed and.*', category=FutureWarning, module='.*')
 
 if version_info < (6,):
     # nose.tools renames all things from `camelCase` to `snake_case` which raise an
     # warning with the runner they also import from standard import library. (as of Dec 2015)
     # Ignore, let's revisit that in a couple of years for IPython 6.
     warnings.filterwarnings(
         'ignore', message='.*Please use assertEqual instead', category=Warning, module='IPython.*')
 
 if version_info < (8,):
     warnings.filterwarnings('ignore', message='.*Completer.complete.*',
                             category=PendingDeprecationWarning, module='.*')
 else:
     warnings.warn(
         'Completer.complete was pending deprecation and should be changed to Deprecated', FutureWarning)
 
 
 
 # ------------------------------------------------------------------------------
 # Monkeypatch Xunit to count known failures as skipped.
 # ------------------------------------------------------------------------------
 def monkeypatch_xunit():
     try:
         dec.knownfailureif(True)(lambda: None)()
     except Exception as e:
         KnownFailureTest = type(e)
 
     def addError(self, test, err, capt=None):
         if issubclass(err[0], KnownFailureTest):
             err = (SkipTest,) + err[1:]
         return self.orig_addError(test, err, capt)
 
     Xunit.orig_addError = Xunit.addError
     Xunit.addError = addError
 
 #-----------------------------------------------------------------------------
 # Check which dependencies are installed and greater than minimum version.
 #-----------------------------------------------------------------------------
 def extract_version(mod):
     return mod.__version__
 
 def test_for(item, min_version=None, callback=extract_version):
     """Test to see if item is importable, and optionally check against a minimum
     version.
 
     If min_version is given, the default behavior is to check against the
     `__version__` attribute of the item, but specifying `callback` allows you to
     extract the value you are interested in. e.g::
 
         In [1]: import sys
 
         In [2]: from IPython.testing.iptest import test_for
 
         In [3]: test_for('sys', (2,6), callback=lambda sys: sys.version_info)
         Out[3]: True
 
     """
     try:
         check = import_item(item)
     except (ImportError, RuntimeError):
         # GTK reports Runtime error if it can't be initialized even if it's
         # importable.
         return False
     else:
         if min_version:
             if callback:
                 # extra processing step to get version to compare
                 check = callback(check)
 
             return check >= min_version
         else:
             return True
 
 # Global dict where we can store information on what we have and what we don't
 # have available at test run time
 have = {'matplotlib': test_for('matplotlib'),
         'pygments': test_for('pygments'),
         }
 
 #-----------------------------------------------------------------------------
 # Test suite definitions
 #-----------------------------------------------------------------------------
 
 test_group_names = ['core',
                     'extensions', 'lib', 'terminal', 'testing', 'utils',
                    ]
 
 class TestSection(object):
     def __init__(self, name, includes):
         self.name = name
         self.includes = includes
         self.excludes = []
         self.dependencies = []
         self.enabled = True
     
     def exclude(self, module):
         if not module.startswith('IPython'):
             module = self.includes[0] + "." + module
         self.excludes.append(module.replace('.', os.sep))
     
     def requires(self, *packages):
         self.dependencies.extend(packages)
     
     @property
     def will_run(self):
         return self.enabled and all(have[p] for p in self.dependencies)
 
 # Name -> (include, exclude, dependencies_met)
 test_sections = {n:TestSection(n, ['IPython.%s' % n]) for n in test_group_names}
 
 
 # Exclusions and dependencies
 # ---------------------------
 
 # core:
 sec = test_sections['core']
 if not have['matplotlib']:
     sec.exclude('pylabtools'),
     sec.exclude('tests.test_pylabtools')
 
 # lib:
 sec = test_sections['lib']
 sec.exclude('kernel')
 if not have['pygments']:
     sec.exclude('tests.test_lexers')
 # We do this unconditionally, so that the test suite doesn't import
 # gtk, changing the default encoding and masking some unicode bugs.
 sec.exclude('inputhookgtk')
 # We also do this unconditionally, because wx can interfere with Unix signals.
 # There are currently no tests for it anyway.
 sec.exclude('inputhookwx')
 # Testing inputhook will need a lot of thought, to figure out
 # how to have tests that don't lock up with the gui event
 # loops in the picture
 sec.exclude('inputhook')
 
 # testing:
 sec = test_sections['testing']
 # These have to be skipped on win32 because they use echo, rm, cd, etc.
 # See ticket https://github.com/ipython/ipython/issues/87
 if sys.platform == 'win32':
     sec.exclude('plugin.test_exampleip')
     sec.exclude('plugin.dtexample')
 
 # don't run jupyter_console tests found via shim
 test_sections['terminal'].exclude('console')
 
 # extensions:
 sec = test_sections['extensions']
 # This is deprecated in favour of rpy2
 sec.exclude('rmagic')
 # autoreload does some strange stuff, so move it to its own test section
 sec.exclude('autoreload')
 sec.exclude('tests.test_autoreload')
 test_sections['autoreload'] = TestSection('autoreload',
         ['IPython.extensions.autoreload', 'IPython.extensions.tests.test_autoreload'])
 test_group_names.append('autoreload')
 
 
 #-----------------------------------------------------------------------------
 # Functions and classes
 #-----------------------------------------------------------------------------
 
 def check_exclusions_exist():
     from IPython.paths import get_ipython_package_dir
     from warnings import warn
     parent = os.path.dirname(get_ipython_package_dir())
     for sec in test_sections:
         for pattern in sec.exclusions:
             fullpath = pjoin(parent, pattern)
             if not os.path.exists(fullpath) and not glob.glob(fullpath + '.*'):
                 warn("Excluding nonexistent file: %r" % pattern)
 
 
 class ExclusionPlugin(Plugin):
     """A nose plugin to effect our exclusions of files and directories.
     """
     name = 'exclusions'
     score = 3000  # Should come before any other plugins
     
     def __init__(self, exclude_patterns=None):
         """
         Parameters
         ----------
 
         exclude_patterns : sequence of strings, optional
           Filenames containing these patterns (as raw strings, not as regular
           expressions) are excluded from the tests.
         """
         self.exclude_patterns = exclude_patterns or []
         super(ExclusionPlugin, self).__init__()
 
     def options(self, parser, env=os.environ):
         Plugin.options(self, parser, env)
     
     def configure(self, options, config):
         Plugin.configure(self, options, config)
         # Override nose trying to disable plugin.
         self.enabled = True
         
     def wantFile(self, filename):
         """Return whether the given filename should be scanned for tests.
         """
         if any(pat in filename for pat in self.exclude_patterns):
             return False
         return None
 
     def wantDirectory(self, directory):
         """Return whether the given directory should be scanned for tests.
         """
         if any(pat in directory for pat in self.exclude_patterns):
             return False
         return None
 
 
 class StreamCapturer(Thread):
     daemon = True  # Don't hang if main thread crashes
     started = False
     def __init__(self, echo=False):
         super(StreamCapturer, self).__init__()
         self.echo = echo
         self.streams = []
         self.buffer = BytesIO()
         self.readfd, self.writefd = os.pipe()
         self.buffer_lock = Lock()
         self.stop = Event()
 
     def run(self):
         self.started = True
 
         while not self.stop.is_set():
             chunk = os.read(self.readfd, 1024)
 
             with self.buffer_lock:
                 self.buffer.write(chunk)
             if self.echo:
                 sys.stdout.write(decode(chunk))
 
         os.close(self.readfd)
         os.close(self.writefd)
 
     def reset_buffer(self):
         with self.buffer_lock:
             self.buffer.truncate(0)
             self.buffer.seek(0)
 
     def get_buffer(self):
         with self.buffer_lock:
             return self.buffer.getvalue()
 
     def ensure_started(self):
         if not self.started:
             self.start()
 
     def halt(self):
         """Safely stop the thread."""
         if not self.started:
             return
 
         self.stop.set()
         os.write(self.writefd, b'\0')  # Ensure we're not locked in a read()
         self.join()
 
 class SubprocessStreamCapturePlugin(Plugin):
     name='subprocstreams'
     def __init__(self):
         Plugin.__init__(self)
         self.stream_capturer = StreamCapturer()
         self.destination = os.environ.get('IPTEST_SUBPROC_STREAMS', 'capture')
         # This is ugly, but distant parts of the test machinery need to be able
         # to redirect streams, so we make the object globally accessible.
         nose.iptest_stdstreams_fileno = self.get_write_fileno
 
     def get_write_fileno(self):
         if self.destination == 'capture':
             self.stream_capturer.ensure_started()
             return self.stream_capturer.writefd
         elif self.destination == 'discard':
             return os.open(os.devnull, os.O_WRONLY)
         else:
             return sys.__stdout__.fileno()
     
     def configure(self, options, config):
         Plugin.configure(self, options, config)
         # Override nose trying to disable plugin.
         if self.destination == 'capture':
             self.enabled = True
     
     def startTest(self, test):
         # Reset log capture
         self.stream_capturer.reset_buffer()
     
     def formatFailure(self, test, err):
         # Show output
         ec, ev, tb = err
         captured = self.stream_capturer.get_buffer().decode('utf-8', 'replace')
         if captured.strip():
             ev = safe_str(ev)
             out = [ev, '>> begin captured subprocess output <<',
                     captured,
                     '>> end captured subprocess output <<']
             return ec, '\n'.join(out), tb
 
         return err
     
     formatError = formatFailure
     
     def finalize(self, result):
         self.stream_capturer.halt()
 
 
 def run_iptest():
     """Run the IPython test suite using nose.
 
     This function is called when this script is **not** called with the form
     `iptest all`.  It simply calls nose with appropriate command line flags
     and accepts all of the standard nose arguments.
     """
     # Apply our monkeypatch to Xunit
     if '--with-xunit' in sys.argv and not hasattr(Xunit, 'orig_addError'):
         monkeypatch_xunit()
 
     arg1 = sys.argv[1]
     if arg1.startswith('IPython/'):
         if arg1.endswith('.py'):
             arg1 = arg1[:-3]
         sys.argv[1] = arg1.replace('/', '.')
     
     arg1 = sys.argv[1]
     if arg1 in test_sections:
         section = test_sections[arg1]
         sys.argv[1:2] = section.includes
     elif arg1.startswith('IPython.') and arg1[8:] in test_sections:
         section = test_sections[arg1[8:]]
         sys.argv[1:2] = section.includes
     else:
         section = TestSection(arg1, includes=[arg1])
         
 
     argv = sys.argv + [ '--detailed-errors',  # extra info in tracebacks
                         # We add --exe because of setuptools' imbecility (it
                         # blindly does chmod +x on ALL files).  Nose does the
                         # right thing and it tries to avoid executables,
                         # setuptools unfortunately forces our hand here.  This
                         # has been discussed on the distutils list and the
                         # setuptools devs refuse to fix this problem!
                         '--exe',
                         ]
     if '-a' not in argv and '-A' not in argv:
         argv = argv + ['-a', '!crash']
 
     if nose.__version__ >= '0.11':
         # I don't fully understand why we need this one, but depending on what
         # directory the test suite is run from, if we don't give it, 0 tests
         # get run.  Specifically, if the test suite is run from the source dir
         # with an argument (like 'iptest.py IPython.core', 0 tests are run,
         # even if the same call done in this directory works fine).  It appears
         # that if the requested package is in the current dir, nose bails early
         # by default.  Since it's otherwise harmless, leave it in by default
         # for nose >= 0.11, though unfortunately nose 0.10 doesn't support it.
         argv.append('--traverse-namespace')
 
     plugins = [ ExclusionPlugin(section.excludes), KnownFailure(),
                SubprocessStreamCapturePlugin() ]
     
     # we still have some vestigial doctests in core
     if (section.name.startswith(('core', 'IPython.core', 'IPython.utils'))):
         plugins.append(IPythonDoctest())
         argv.extend([
             '--with-ipdoctest',
             '--ipdoctest-tests',
             '--ipdoctest-extension=txt',
         ])
 
     
     # Use working directory set by parent process (see iptestcontroller)
     if 'IPTEST_WORKING_DIR' in os.environ:
         os.chdir(os.environ['IPTEST_WORKING_DIR'])
     
     # We need a global ipython running in this process, but the special
     # in-process group spawns its own IPython kernels, so for *that* group we
     # must avoid also opening the global one (otherwise there's a conflict of
     # singletons).  Ultimately the solution to this problem is to refactor our
     # assumptions about what needs to be a singleton and what doesn't (app
     # objects should, individual shells shouldn't).  But for now, this
     # workaround allows the test suite for the inprocess module to complete.
     if 'kernel.inprocess' not in section.name:
         from IPython.testing import globalipapp
         globalipapp.start_ipython()
 
     # Now nose can run
     TestProgram(argv=argv, addplugins=plugins)
 
 if __name__ == '__main__':
     run_iptest()