Document IPython.display API correctly

IPython/core/display.py

@@ -1,811 +1,817 b''
 # -*- coding: utf-8 -*-
 """Top-level display functions for displaying object in different formats.
 
 Authors:
 
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #       Copyright (C) 2013 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 __future__ import print_function
 
 import os
 import struct
 
 from IPython.core.formatters import _safe_get_formatter_method
 from IPython.utils.py3compat import (string_types, cast_bytes_py2, cast_unicode,
                                      unicode_type)
 from IPython.testing.skipdoctest import skip_doctest
 from .displaypub import publish_display_data
 
+__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',
+'clear_output', 'set_matplotlib_formats', 'set_matplotlib_close']
+
 #-----------------------------------------------------------------------------
 # 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
 #-----------------------------------------------------------------------------
 
 def display(*objs, **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.
     """
     raw = kwargs.get('raw', False)
     include = kwargs.get('include')
     exclude = kwargs.get('exclude')
     metadata = kwargs.get('metadata')
 
     from IPython.core.interactiveshell import InteractiveShell
 
     if not raw:
         format = InteractiveShell.instance().display_formatter.format
 
     for obj in objs:
 
         # If _ipython_display_ is defined, use that to display this object.
         display_method = _safe_get_formatter_method(obj, '_ipython_display_')
         if display_method is not None:
             try:
                 display_method(**kwargs)
             except NotImplementedError:
                 pass
             else:
                 continue
         if raw:
             publish_display_data(data=obj, metadata=metadata)
         else:
             format_dict, md_dict = format(obj, include=include, exclude=exclude)
             if metadata:
                 # kwarg-specified metadata gets precedence
                 _merge(md_dict, metadata)
             publish_display_data(data=format_dict, metadata=md_dict)
 
 
 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.
 
     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, string_types):
             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 = None if filename is None else unicode_type(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
                 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, string_types):
             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):
 
     # 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(TextDisplayObject):
 
     def _repr_json_(self):
         return self.data
 
 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, string_types):
             lib = [lib]
         elif lib is None:
             lib = []
         if isinstance(css, string_types):
             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=u'png', embed=None, width=None, height=None, retina=False):
         """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 to which to constrain the image in html
         height : int
             Height 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.
 
         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, string_types) and (
             data.startswith('http') or _safe_exists(data)
         ):
             ext = self._find_ext(data)
         else:
             ext = None
 
         if ext is not None:
             format = ext.lower()
             if ext == u'jpg' or ext == u'jpeg':
                 format = self._FMT_JPEG
             if ext == u'png':
                 format = self._FMT_PNG
         elif isinstance(data, bytes) and format == 'png':
             # infer image type from image data header,
             # only if format might not have been specified.
             if data[:2] == _JPEG:
                 format = 'jpeg'
 
         self.format = unicode_type(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
         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 = ''
             if self.width:
                 width = ' width="%d"' % self.width
             if self.height:
                 height = ' height="%d"' % self.height
             return u'<img src="%s"%s%s/>' % (self.url, width, height)
 
     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 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 unicode_type(s.split('.')[-1].lower())
 
 
 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:
         from IPython.utils import io
         print('\033[2K\r', file=io.stdout, end='')
         io.stdout.flush()
         print('\033[2K\r', file=io.stderr, end='')
         io.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
     from IPython.kernel.zmq.pylab.config import InlineBackend
     # build kwargs, starting with InlineBackend config
     kw = {}
     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 IPython.kernel.zmq.pylab.config import InlineBackend
     cfg = InlineBackend.instance()
     cfg.close_figures = close
 

IPython/lib/display.py

@@ -1,530 +1,533 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 image 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
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         src = "https://www.youtube.com/embed/{0}".format(id)
         super(YouTubeVideo, self).__init__(src, width, height, **kwargs)
 
 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):
         """
         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)
 
         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()
 
     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 == 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 = []
         walked_dir = list(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 = []
         walked_dir = list(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)

docs/autogen_api.py

@@ -1,58 +1,62 b''
 #!/usr/bin/env python
 """Script to auto-generate our API docs.
 """
 # stdlib imports
 import os
 import sys
 
 # local imports
 sys.path.append(os.path.abspath('sphinxext'))
 from apigen import ApiDocWriter
 
 #*****************************************************************************
 if __name__ == '__main__':
     pjoin = os.path.join
     package = 'IPython'
     outdir = pjoin('source','api','generated')
     docwriter = ApiDocWriter(package,rst_extension='.rst')
     # You have to escape the . here because . is a special char for regexps.
     # You must do make clean if you change this!
     docwriter.package_skip_patterns += [r'\.external$',
                                         # Extensions are documented elsewhere.
                                         r'\.extensions',
                                         r'\.config\.profile',
                                         # These should be accessed via nbformat.current
                                         r'\.nbformat\.v\d+',
                                         ]
 
     # The inputhook* modules often cause problems on import, such as trying to
     # load incompatible Qt bindings. It's easiest to leave them all out. The
     # main API is in the inputhook module, which is documented.
     docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+',
                                         r'\.ipdoctest',
                                         r'\.testing\.plugin',
                                         # This just prints a deprecation msg:
                                         r'\.frontend$',
                                         # We document this manually.
                                         r'\.utils\.py3compat',
                                         # These are exposed by nbformat.current
                                         r'\.nbformat\.convert',
                                         r'\.nbformat\.validator',
+                                        # These are exposed in display
+                                        r'\.core\.display',
+                                        r'\.lib\.display',
                                         ]
 
     # These modules import functions and classes from other places to expose
     # them as part of the public API. They must have __all__ defined. The
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
         'IPython.nbformat.current',
+        'IPython.display',
     })
     
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
     # Write index with .txt extension - we can include it, but Sphinx won't try
     # to compile it
     docwriter.write_index(outdir, 'gen.txt',
                           relative_to = pjoin('source','api')
                           )
     print ('%d files written' % len(docwriter.written_modules))