remove python 2.x specific urllib2's functions

IPython/core/display.py

@@ -1,1135 +1,1133 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.
 
 
 try:
     from base64 import encodebytes as base64_encode
 except ImportError:
     from base64 import encodestring as base64_encode
 
 from binascii import b2a_hex
 import json
 import mimetypes
 import os
 import struct
 import sys
 import warnings
 
 from IPython.utils.py3compat import cast_bytes_py2, cast_unicode
 from IPython.testing.skipdoctest import skip_doctest
 
 __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', 'JSON', 'Javascript',
 'Image', 'clear_output', 'set_matplotlib_formats', 'set_matplotlib_close',
 'publish_display_data', 'update_display', 'DisplayHandle']
 
 #-----------------------------------------------------------------------------
 # 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 : tuple of objects
         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.
 
     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. 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.
 
     Parameters
     ----------
     objs : tuple of objects
         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 or tuple, 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 or tuple, 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, 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, if display_id is given.
         Returns None if no display_id is given (default).
     """
     raw = kwargs.pop('raw', False)
     if transient is None:
         transient = {}
     if display_id:
         if display_id == 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
 
     from IPython.core.interactiveshell import InteractiveShell
 
     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
     """
     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.
     """
 
     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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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 : tuple of objects
         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
 
     def __init__(self, data=None, url=None, filename=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.
         """
         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.data = data
         self.url = url
         self.filename = filename
 
         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 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:
             try:
-                try:
-                    from urllib.request import urlopen  # Py3
-                except ImportError:
-                    from urllib2 import urlopen
+                # Deferred import
+                from urllib.request import urlopen
                 response = urlopen(self.url)
                 self.data = response.read()
                 # extract encoding from header, if there is one:
                 encoding = None
                 for sub in response.headers['content-type'].split(';'):
                     sub = sub.strip()
                     if sub.startswith('charset'):
                         encoding = sub.split('=')[-1].strip()
                         break
                 # decode data, if an encoding was specified
                 if encoding:
                     self.data = self.data.decode(encoding, 'replace')
             except:
                 self.data = None
 
 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):
         return self.data
 
 
 class HTML(TextDisplayObject):
 
     def _repr_html_(self):
         return self.data
 
     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
 
 
 class Math(TextDisplayObject):
 
     def _repr_latex_(self):
         s = self.data.strip('$')
         return "$$%s$$" % s
 
 
 class Latex(TextDisplayObject):
 
     def _repr_latex_(self):
         return self.data
 
 
 class SVG(DisplayObject):
 
     _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
         svg = cast_bytes_py2(svg)
         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
 
 
 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):
         """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.
         """
         self.expanded = expanded
         self.metadata = metadata
         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, str):
             warnings.warn("JSON expects JSONable dict or list, not JSON strings")
             data = json.loads(data)
         self._data = data
 
     def _data_and_metadata(self):
         md = {'expanded': self.expanded}
         if self.metadata:
             md.update(self.metadata)
         return self.data, md
 
     def _repr_json_(self):
         return self._data_and_metadata()
 
 css_t = """$("head").append($("<link/>").attr({
   rel:  "stylesheet",
   type: "text/css",
   href: "%s"
 }));
 """
 
 lib_t1 = """$.getScript("%s", function () {
 """
 lib_t2 = """});
 """
 
 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
     w4h4 = data[ihdr+4:ihdr+12]
     return struct.unpack('>ii', w4h4)
 
 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
 
 class Image(DisplayObject):
 
     _read_flags = 'rb'
     _FMT_JPEG = u'jpeg'
     _FMT_PNG = u'png'
     _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG]
 
     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 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). 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 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
                 if ext == u'png':
                     format = self._FMT_PNG
                 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 = '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))
         self.width = width
         self.height = height
         self.retina = retina
         self.unconfined = unconfined
         self.metadata = metadata
         super(Image, self).__init__(data=data, url=url, filename=filename)
 
         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 == 'png':
             w, h = _pngxy(self.data)
         elif self.format == 'jpeg':
             w, h = _jpegxy(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 _data_and_metadata(self):
         """shortcut for returning metadata with shape information, if defined"""
         md = {}
         if self.width:
             md['width'] = self.width
         if self.height:
             md['height'] = self.height
         if self.unconfined:
             md['unconfined'] = self.unconfined
         if self.metadata:
             md.update(self.metadata)
         if md:
             return self.data, md
         else:
             return self.data
 
     def _repr_png_(self):
         if self.embed and self.format == u'png':
             return self._data_and_metadata()
 
     def _repr_jpeg_(self):
         if self.embed and (self.format == u'jpeg' or self.format == u'jpg'):
             return self._data_and_metadata()
 
     def _find_ext(self, s):
         return s.split('.')[-1].lower()
 
 class Video(DisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, embed=False, mimetype=None):
         """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.
 
         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(b'raw-videodata', embed=True)
         """
         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
         super(Video, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_html_(self):
         # 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}" controls>
       Your browser does not support the <code>video</code> element.
     </video>""".format(url)
             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 = base64_encode(video).decode('ascii').rstrip()
 
         output = """<video controls>
  <source src="data:{0};base64,{1}" type="{0}">
  Your browser does not support the video tag.
  </video>""".format(mimetype, b64_video)
         return output
 
     def reload(self):
         # TODO
         pass
 
     def _repr_png_(self):
         # TODO
         pass
     def _repr_jpeg_(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/extensions.py

@@ -1,174 +1,170 b''
 # encoding: utf-8
 """A class for managing IPython extensions."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import os
 from shutil import copyfile
 import sys
 from importlib import import_module
 
 from traitlets.config.configurable import Configurable
 from IPython.utils.path import ensure_dir_exists
 from traitlets import Instance
 
 try:
     from importlib import reload
 except ImportError :
     ## deprecated since 3.4
     from imp import reload
 
 #-----------------------------------------------------------------------------
 # Main class
 #-----------------------------------------------------------------------------
 
 class ExtensionManager(Configurable):
     """A class to manage IPython extensions.
 
     An IPython extension is an importable Python module that has
     a function with the signature::
 
         def load_ipython_extension(ipython):
             # Do things with ipython
 
     This function is called after your extension is imported and the
     currently active :class:`InteractiveShell` instance is passed as
     the only argument.  You can do anything you want with IPython at
     that point, including defining new magic and aliases, adding new
     components, etc.
     
     You can also optionally define an :func:`unload_ipython_extension(ipython)`
     function, which will be called if the user unloads or reloads the extension.
     The extension manager will only call :func:`load_ipython_extension` again
     if the extension is reloaded.
 
     You can put your extension modules anywhere you want, as long as
     they can be imported by Python's standard import mechanism.  However,
     to make it easy to write extensions, you can also put your extensions
     in ``os.path.join(self.ipython_dir, 'extensions')``.  This directory
     is added to ``sys.path`` automatically.
     """
 
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
 
     def __init__(self, shell=None, **kwargs):
         super(ExtensionManager, self).__init__(shell=shell, **kwargs)
         self.shell.observe(
             self._on_ipython_dir_changed, names=('ipython_dir',)
         )
         self.loaded = set()
 
     @property
     def ipython_extension_dir(self):
         return os.path.join(self.shell.ipython_dir, u'extensions')
 
     def _on_ipython_dir_changed(self, change):
         ensure_dir_exists(self.ipython_extension_dir)
 
     def load_extension(self, module_str):
         """Load an IPython extension by its module name.
 
         Returns the string "already loaded" if the extension is already loaded,
         "no load function" if the module doesn't have a load_ipython_extension
         function, or None if it succeeded.
         """
         if module_str in self.loaded:
             return "already loaded"
         
         from IPython.utils.syspathcontext import prepended_to_syspath
         
         with self.shell.builtin_trap:
             if module_str not in sys.modules:
                 with prepended_to_syspath(self.ipython_extension_dir):
                     import_module(module_str)
             mod = sys.modules[module_str]
             if self._call_load_ipython_extension(mod):
                 self.loaded.add(module_str)
             else:
                 return "no load function"
 
     def unload_extension(self, module_str):
         """Unload an IPython extension by its module name.
 
         This function looks up the extension's name in ``sys.modules`` and
         simply calls ``mod.unload_ipython_extension(self)``.
         
         Returns the string "no unload function" if the extension doesn't define
         a function to unload itself, "not loaded" if the extension isn't loaded,
         otherwise None.
         """
         if module_str not in self.loaded:
             return "not loaded"
         
         if module_str in sys.modules:
             mod = sys.modules[module_str]
             if self._call_unload_ipython_extension(mod):
                 self.loaded.discard(module_str)
             else:
                 return "no unload function"
 
     def reload_extension(self, module_str):
         """Reload an IPython extension by calling reload.
 
         If the module has not been loaded before,
         :meth:`InteractiveShell.load_extension` is called. Otherwise
         :func:`reload` is called and then the :func:`load_ipython_extension`
         function of the module, if it exists is called.
         """
         from IPython.utils.syspathcontext import prepended_to_syspath
 
         if (module_str in self.loaded) and (module_str in sys.modules):
             self.unload_extension(module_str)
             mod = sys.modules[module_str]
             with prepended_to_syspath(self.ipython_extension_dir):
                 reload(mod)
             if self._call_load_ipython_extension(mod):
                 self.loaded.add(module_str)
         else:
             self.load_extension(module_str)
 
     def _call_load_ipython_extension(self, mod):
         if hasattr(mod, 'load_ipython_extension'):
             mod.load_ipython_extension(self.shell)
             return True
 
     def _call_unload_ipython_extension(self, mod):
         if hasattr(mod, 'unload_ipython_extension'):
             mod.unload_ipython_extension(self.shell)
             return True
 
     def install_extension(self, url, filename=None):
         """Download and install an IPython extension. 
 
         If filename is given, the file will be so named (inside the extension
         directory). Otherwise, the name from the URL will be used. The file must
         have a .py or .zip extension; otherwise, a ValueError will be raised.
 
         Returns the full path to the installed file.
         """
         # Ensure the extension directory exists
         ensure_dir_exists(self.ipython_extension_dir)
 
         if os.path.isfile(url):
             src_filename = os.path.basename(url)
             copy = copyfile
         else:
             # Deferred imports
-            try:
-                from urllib.parse import urlparse  # Py3
+            from urllib.parse import urlparse
                 from urllib.request import urlretrieve
-            except ImportError:
-                from urlparse import urlparse
-                from urllib import urlretrieve
             src_filename = urlparse(url).path.split('/')[-1]
             copy = urlretrieve
 
         if filename is None:
             filename = src_filename
         if os.path.splitext(filename)[1] not in ('.py', '.zip'):
             raise ValueError("The file must have a .py or .zip extension", filename)
 
         filename = os.path.join(self.ipython_extension_dir, filename)
         copy(url, filename)
         return filename

IPython/lib/display.py

@@ -1,558 +1,557 b''
 """Various display related classes.
 
 Authors : MinRK, gregcaporaso, dannystaple
 """
 from os.path import exists, isfile, splitext, abspath, join, isdir
 from os import walk, sep
 
 from IPython.core.display import DisplayObject
 
 __all__ = ['Audio', 'IFrame', 'YouTubeVideo', 'VimeoVideo', 'ScribdDocument',
            'FileLink', 'FileLinks']
 
 
 class Audio(DisplayObject):
     """Create an audio object.
 
     When this object is returned by an input cell or passed to the
     display function, it will result in Audio controls being displayed
     in the frontend (only works in the notebook).
 
     Parameters
     ----------
     data : numpy array, list, unicode, str or bytes
         Can be one of
 
           * Numpy 1d array containing the desired waveform (mono)
           * Numpy 2d array containing waveforms for each channel.
             Shape=(NCHAN, NSAMPLES). For the standard channel order, see
             http://msdn.microsoft.com/en-us/library/windows/hardware/dn653308(v=vs.85).aspx
           * List of float or integer representing the waveform (mono)
           * String containing the filename
           * Bytestring containing raw PCM data or
           * URL pointing to a file on the web.
 
         If the array option is used the waveform will be normalized.
 
         If a filename or url is used the format support will be browser
         dependent.
     url : unicode
         A URL to download the data from.
     filename : unicode
         Path to a local file to load the data from.
     embed : boolean
         Should the audio data be embedded using a data URI (True) or should
         the original source be referenced. Set this to True if you want the
         audio to playable later with no internet connection in the notebook.
 
         Default is `True`, unless the keyword argument `url` is set, then
         default value is `False`.
     rate : integer
         The sampling rate of the raw data.
         Only required when data parameter is being used as an array
     autoplay : bool
         Set to True if the audio should immediately start playing.
         Default is `False`.
 
     Examples
     --------
     ::
 
         # Generate a sound
         import numpy as np
         framerate = 44100
         t = np.linspace(0,5,framerate*5)
         data = np.sin(2*np.pi*220*t) + np.sin(2*np.pi*224*t))
         Audio(data,rate=framerate)
 
         # Can also do stereo or more channels
         dataleft = np.sin(2*np.pi*220*t)
         dataright = np.sin(2*np.pi*224*t)
         Audio([dataleft, dataright],rate=framerate)
 
         Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")  # From URL
         Audio(url="http://www.w3schools.com/html/horse.ogg")
 
         Audio('/path/to/sound.wav')  # From file
         Audio(filename='/path/to/sound.ogg')
 
         Audio(b'RAW_WAV_DATA..)  # From bytes
         Audio(data=b'RAW_WAV_DATA..)
 
     """
     _read_flags = 'rb'
 
     def __init__(self, data=None, filename=None, url=None, embed=None, rate=None, autoplay=False):
         if filename is None and url is None and data is None:
             raise ValueError("No image data found. Expecting filename, url, or data.")
         if embed is False and url is None:
             raise ValueError("No url found. Expecting url when embed=False")
 
         if url is not None and embed is not True:
             self.embed = False
         else:
             self.embed = True
         self.autoplay = autoplay
         super(Audio, self).__init__(data=data, url=url, filename=filename)
 
         if self.data is not None and not isinstance(self.data, bytes):
             self.data = self._make_wav(data,rate)
 
     def reload(self):
         """Reload the raw data from file or URL."""
         import mimetypes
         if self.embed:
             super(Audio, self).reload()
 
         if self.filename is not None:
             self.mimetype = mimetypes.guess_type(self.filename)[0]
         elif self.url is not None:
             self.mimetype = mimetypes.guess_type(self.url)[0]
         else:
             self.mimetype = "audio/wav"
 
     def _make_wav(self, data, rate):
         """ Transform a numpy array to a PCM bytestring """
         import struct
         from io import BytesIO
         import wave
 
         try:
             import numpy as np
 
             data = np.array(data, dtype=float)
             if len(data.shape) == 1:
                 nchan = 1
             elif len(data.shape) == 2:
                 # In wave files,channels are interleaved. E.g.,
                 # "L1R1L2R2..." for stereo. See
                 # http://msdn.microsoft.com/en-us/library/windows/hardware/dn653308(v=vs.85).aspx
                 # for channel ordering
                 nchan = data.shape[0]
                 data = data.T.ravel()
             else:
                 raise ValueError('Array audio input must be a 1D or 2D array')
             scaled = np.int16(data/np.max(np.abs(data))*32767).tolist()
         except ImportError:
             # check that it is a "1D" list
             idata = iter(data)  # fails if not an iterable
             try:
                 iter(idata.next())
                 raise TypeError('Only lists of mono audio are '
                     'supported if numpy is not installed')
             except TypeError:
                 # this means it's not a nested list, which is what we want
                 pass
             maxabsvalue = float(max([abs(x) for x in data]))
             scaled = [int(x/maxabsvalue*32767) for x in data]
             nchan = 1
 
         fp = BytesIO()
         waveobj = wave.open(fp,mode='wb')
         waveobj.setnchannels(nchan)
         waveobj.setframerate(rate)
         waveobj.setsampwidth(2)
         waveobj.setcomptype('NONE','NONE')
         waveobj.writeframes(b''.join([struct.pack('<h',x) for x in scaled]))
         val = fp.getvalue()
         waveobj.close()
 
         return val
 
     def _data_and_metadata(self):
         """shortcut for returning metadata with url information, if defined"""
         md = {}
         if self.url:
             md['url'] = self.url
         if md:
             return self.data, md
         else:
             return self.data
 
     def _repr_html_(self):
         src = """
                 <audio controls="controls" {autoplay}>
                     <source src="{src}" type="{type}" />
                     Your browser does not support the audio element.
                 </audio>
               """
         return src.format(src=self.src_attr(),type=self.mimetype, autoplay=self.autoplay_attr())
 
     def src_attr(self):
         import base64
         if self.embed and (self.data is not None):
             data = base64=base64.b64encode(self.data).decode('ascii')
             return """data:{type};base64,{base64}""".format(type=self.mimetype,
                                                             base64=data)
         elif self.url is not None:
             return self.url
         else:
             return ""
 
     def autoplay_attr(self):
         if(self.autoplay):
             return 'autoplay="autoplay"'
         else:
             return ''
 
 class IFrame(object):
     """
     Generic class to embed an iframe in an IPython notebook
     """
 
     iframe = """
         <iframe
             width="{width}"
             height="{height}"
             src="{src}{params}"
             frameborder="0"
             allowfullscreen
         ></iframe>
         """
 
     def __init__(self, src, width, height, **kwargs):
         self.src = src
         self.width = width
         self.height = height
         self.params = kwargs
 
     def _repr_html_(self):
         """return the embed iframe"""
         if self.params:
             try:
                 from urllib.parse import urlencode # Py 3
             except ImportError:
                 from urllib import urlencode
             params = "?" + urlencode(self.params)
         else:
             params = ""
         return self.iframe.format(src=self.src,
                                   width=self.width,
                                   height=self.height,
                                   params=params)
 
 class YouTubeVideo(IFrame):
     """Class for embedding a YouTube Video in an IPython session, based on its video id.
 
     e.g. to embed the video from https://www.youtube.com/watch?v=foo , you would
     do::
 
         vid = YouTubeVideo("foo")
         display(vid)
 
     To start from 30 seconds::
 
         vid = YouTubeVideo("abc", start=30)
         display(vid)
 
     To calculate seconds from time as hours, minutes, seconds use
     :class:`datetime.timedelta`::
 
         start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
 
     Other parameters can be provided as documented at
     https://developers.google.com/youtube/player_parameters#parameter-subheader
     
     When converting the notebook using nbconvert, a jpeg representation of the video
     will be inserted in the document.
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         self.id=id
         src = "https://www.youtube.com/embed/{0}".format(id)
         super(YouTubeVideo, self).__init__(src, width, height, **kwargs)
     
     def _repr_jpeg_(self):
-        try:
-            from urllib.request import urlopen  # Py3
-        except ImportError:
-            from urllib2 import urlopen
+        # Deferred import
+        from urllib.request import urlopen
+
         try:
             return urlopen("https://img.youtube.com/vi/{id}/hqdefault.jpg".format(id=self.id)).read()
         except IOError:
             return None
 
 class VimeoVideo(IFrame):
     """
     Class for embedding a Vimeo video in an IPython session, based on its video id.
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         src="https://player.vimeo.com/video/{0}".format(id)
         super(VimeoVideo, self).__init__(src, width, height, **kwargs)
 
 class ScribdDocument(IFrame):
     """
     Class for embedding a Scribd document in an IPython session
 
     Use the start_page params to specify a starting point in the document
     Use the view_mode params to specify display type one off scroll | slideshow | book
 
     e.g to Display Wes' foundational paper about PANDAS in book mode from page 3
 
     ScribdDocument(71048089, width=800, height=400, start_page=3, view_mode="book")
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         src="https://www.scribd.com/embeds/{0}/content".format(id)
         super(ScribdDocument, self).__init__(src, width, height, **kwargs)
 
 class FileLink(object):
     """Class for embedding a local file link in an IPython session, based on path
 
     e.g. to embed a link that was generated in the IPython notebook as my/data.txt
 
     you would do::
 
         local_file = FileLink("my/data.txt")
         display(local_file)
 
     or in the HTML notebook, just::
 
         FileLink("my/data.txt")
     """
 
     html_link_str = "<a href='%s' target='_blank'>%s</a>"
 
     def __init__(self,
                  path,
                  url_prefix='',
                  result_html_prefix='',
                  result_html_suffix='<br>'):
         """
         Parameters
         ----------
         path : str
             path to the file or directory that should be formatted
         directory_prefix : str
             prefix to be prepended to all files to form a working link [default:
             'files']
         result_html_prefix : str
             text to append to beginning to link [default: none]
         result_html_suffix : str
             text to append at the end of link [default: '<br>']
         """
         if isdir(path):
             raise ValueError("Cannot display a directory using FileLink. "
               "Use FileLinks to display '%s'." % path)
         self.path = path
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
 
     def _format_path(self):
         fp = ''.join([self.url_prefix,self.path])
         return ''.join([self.result_html_prefix,
                         self.html_link_str % (fp, self.path),
                         self.result_html_suffix])
 
     def _repr_html_(self):
         """return html link to file
         """
         if not exists(self.path):
             return ("Path (<tt>%s</tt>) doesn't exist. "
                     "It may still be in the process of "
                     "being generated, or you may have the "
                     "incorrect path." % self.path)
 
         return self._format_path()
 
     def __repr__(self):
         """return absolute path to file
         """
         return abspath(self.path)
 
 class FileLinks(FileLink):
     """Class for embedding local file links in an IPython session, based on path
 
     e.g. to embed links to files that were generated in the IPython notebook
     under ``my/data``, you would do::
 
         local_files = FileLinks("my/data")
         display(local_files)
 
     or in the HTML notebook, just::
 
         FileLinks("my/data")
     """
     def __init__(self,
                  path,
                  url_prefix='',
                  included_suffixes=None,
                  result_html_prefix='',
                  result_html_suffix='<br>',
                  notebook_display_formatter=None,
                  terminal_display_formatter=None,
                  recursive=True):
         """
         See :class:`FileLink` for the ``path``, ``url_prefix``,
         ``result_html_prefix`` and ``result_html_suffix`` parameters.
 
         included_suffixes : list
           Filename suffixes to include when formatting output [default: include
           all files]
 
         notebook_display_formatter : function
           Used to format links for display in the notebook. See discussion of
           formatter functions below.
 
         terminal_display_formatter : function
           Used to format links for display in the terminal. See discussion of
           formatter functions below.
 
         Formatter functions must be of the form::
 
             f(dirname, fnames, included_suffixes)
 
         dirname : str
           The name of a directory
         fnames : list
           The files in that directory
         included_suffixes : list
           The file suffixes that should be included in the output (passing None
           meansto include all suffixes in the output in the built-in formatters)
         recursive : boolean
           Whether to recurse into subdirectories. Default is True.
 
         The function should return a list of lines that will be printed in the
         notebook (if passing notebook_display_formatter) or the terminal (if
         passing terminal_display_formatter). This function is iterated over for
         each directory in self.path. Default formatters are in place, can be
         passed here to support alternative formatting.
 
         """
         if isfile(path):
             raise ValueError("Cannot display a file using FileLinks. "
               "Use FileLink to display '%s'." % path)
         self.included_suffixes = included_suffixes
         # remove trailing slashs for more consistent output formatting
         path = path.rstrip('/')
 
         self.path = path
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
 
         self.notebook_display_formatter = \
              notebook_display_formatter or self._get_notebook_display_formatter()
         self.terminal_display_formatter = \
              terminal_display_formatter or self._get_terminal_display_formatter()
 
         self.recursive = recursive
 
     def _get_display_formatter(self,
                                dirname_output_format,
                                fname_output_format,
                                fp_format,
                                fp_cleaner=None):
         """ generate built-in formatter function
 
            this is used to define both the notebook and terminal built-in
             formatters as they only differ by some wrapper text for each entry
 
            dirname_output_format: string to use for formatting directory
             names, dirname will be substituted for a single "%s" which
             must appear in this string
            fname_output_format: string to use for formatting file names,
             if a single "%s" appears in the string, fname will be substituted
             if two "%s" appear in the string, the path to fname will be
              substituted for the first and fname will be substituted for the
              second
            fp_format: string to use for formatting filepaths, must contain
             exactly two "%s" and the dirname will be subsituted for the first
             and fname will be substituted for the second
         """
         def f(dirname, fnames, included_suffixes=None):
             result = []
             # begin by figuring out which filenames, if any,
             # are going to be displayed
             display_fnames = []
             for fname in fnames:
                 if (isfile(join(dirname,fname)) and
                        (included_suffixes is None or
                         splitext(fname)[1] in included_suffixes)):
                       display_fnames.append(fname)
 
             if len(display_fnames) == 0:
                 # if there are no filenames to display, don't print anything
                 # (not even the directory name)
                 pass
             else:
                 # otherwise print the formatted directory name followed by
                 # the formatted filenames
                 dirname_output_line = dirname_output_format % dirname
                 result.append(dirname_output_line)
                 for fname in display_fnames:
                     fp = fp_format % (dirname,fname)
                     if fp_cleaner is not None:
                         fp = fp_cleaner(fp)
                     try:
                         # output can include both a filepath and a filename...
                         fname_output_line = fname_output_format % (fp, fname)
                     except TypeError:
                         # ... or just a single filepath
                         fname_output_line = fname_output_format % fname
                     result.append(fname_output_line)
             return result
         return f
 
     def _get_notebook_display_formatter(self,
                                         spacer="&nbsp;&nbsp;"):
         """ generate function to use for notebook formatting
         """
         dirname_output_format = \
          self.result_html_prefix + "%s/" + self.result_html_suffix
         fname_output_format = \
          self.result_html_prefix + spacer + self.html_link_str + self.result_html_suffix
         fp_format = self.url_prefix + '%s/%s'
         if sep == "\\":
             # Working on a platform where the path separator is "\", so
             # must convert these to "/" for generating a URI
             def fp_cleaner(fp):
                 # Replace all occurences of backslash ("\") with a forward
                 # slash ("/") - this is necessary on windows when a path is
                 # provided as input, but we must link to a URI
                 return fp.replace('\\','/')
         else:
             fp_cleaner = None
 
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format,
                                            fp_cleaner)
 
     def _get_terminal_display_formatter(self,
                                         spacer="  "):
         """ generate function to use for terminal formatting
         """
         dirname_output_format = "%s/"
         fname_output_format = spacer + "%s"
         fp_format = '%s/%s'
 
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format)
 
     def _format_path(self):
         result_lines = []
         if self.recursive:
             walked_dir = list(walk(self.path))
         else:
             walked_dir = [next(walk(self.path))]
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.notebook_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)
 
     def __repr__(self):
         """return newline-separated absolute paths
         """
         result_lines = []
         if self.recursive:
             walked_dir = list(walk(self.path))
         else:
             walked_dir = [next(walk(self.path))]
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.terminal_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)