display.py
967 lines
| 32.4 KiB
| text/x-python
|
PythonLexer
Brian Granger
|
r3278 | # -*- coding: utf-8 -*- | ||
Min RK
|
r19557 | """Top-level display functions for displaying object in different formats.""" | ||
Brian Granger
|
r3278 | |||
Min RK
|
r19557 | # Copyright (c) IPython Development Team. | ||
# Distributed under the terms of the Modified BSD License. | ||||
Brian Granger
|
r3278 | |||
MinRK
|
r6422 | from __future__ import print_function | ||
Min RK
|
r19557 | import json | ||
import mimetypes | ||||
MinRK
|
r10050 | import os | ||
MinRK
|
r10803 | import struct | ||
Min RK
|
r19557 | import warnings | ||
MinRK
|
r10050 | |||
MinRK
|
r15486 | from IPython.core.formatters import _safe_get_formatter_method | ||
Thomas Kluyver
|
r13353 | from IPython.utils.py3compat import (string_types, cast_bytes_py2, cast_unicode, | ||
unicode_type) | ||||
Brian E. Granger
|
r15126 | from IPython.testing.skipdoctest import skip_doctest | ||
MinRK
|
r10449 | |||
Thomas Kluyver
|
r17121 | __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', | ||||
Thomas Kluyver
|
r17125 | 'Image', 'clear_output', 'set_matplotlib_formats', 'set_matplotlib_close', | ||
Thomas Kluyver
|
r17124 | 'publish_display_data'] | ||
Thomas Kluyver
|
r17121 | |||
Brian Granger
|
r3278 | #----------------------------------------------------------------------------- | ||
MinRK
|
r10050 | # utility functions | ||
#----------------------------------------------------------------------------- | ||||
def _safe_exists(path): | ||||
Kyle Kelley
|
r10213 | """Check path, but don't let exceptions raise""" | ||
MinRK
|
r10050 | try: | ||
return os.path.exists(path) | ||||
except Exception: | ||||
return False | ||||
MinRK
|
r10448 | def _merge(d1, d2): | ||
"""Like update, but merges sub-dicts instead of clobbering at the top level. | ||||
Dan McDougall
|
r10490 | |||
MinRK
|
r10448 | Updates d1 in-place | ||
""" | ||||
Dan McDougall
|
r10490 | |||
MinRK
|
r10448 | 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 | ||||
MinRK
|
r10449 | 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) | ||||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
MinRK
|
r10449 | """ | ||
MinRK
|
r10450 | if metadata: | ||
metadata = {mimetype: metadata} | ||||
MinRK
|
r10449 | if raw: | ||
MinRK
|
r10450 | # 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]) | ||||
MinRK
|
r10050 | #----------------------------------------------------------------------------- | ||
Brian Granger
|
r3278 | # Main functions | ||
#----------------------------------------------------------------------------- | ||||
Thomas Kluyver
|
r17124 | def publish_display_data(data, metadata=None, source=None): | ||
"""Publish data and metadata to all frontends. | ||||
See the ``display_data`` message in the messaging documentation for | ||||
more details about this message type. | ||||
The following MIME types are currently implemented: | ||||
* text/plain | ||||
* text/html | ||||
* text/markdown | ||||
* text/latex | ||||
* application/json | ||||
* application/javascript | ||||
* image/png | ||||
* image/jpeg | ||||
* image/svg+xml | ||||
Parameters | ||||
---------- | ||||
data : dict | ||||
A dictionary having keys that are valid MIME types (like | ||||
'text/plain' or 'image/svg+xml') and values that are the data for | ||||
that MIME type. The data itself must be a JSON'able data | ||||
structure. Minimally all data should have the 'text/plain' data, | ||||
which can be displayed by all frontends. If more than the plain | ||||
text is given, it is up to the frontend to decide which | ||||
representation to use. | ||||
metadata : dict | ||||
A dictionary for metadata related to the data. This can contain | ||||
arbitrary key, value pairs that frontends can use to interpret | ||||
the data. mime-type keys matching those in data can be used | ||||
to specify metadata about particular representations. | ||||
source : str, deprecated | ||||
Unused. | ||||
""" | ||||
from IPython.core.interactiveshell import InteractiveShell | ||||
InteractiveShell.instance().display_pub.publish( | ||||
data=data, | ||||
metadata=metadata, | ||||
) | ||||
Brian Granger
|
r3288 | def display(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """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 | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
The Python objects to display. | ||||
MinRK
|
r10450 | 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] | ||||
Brian Granger
|
r3278 | 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 | ||||
Kyle Kelley
|
r10213 | A list of format type strings (MIME types) to exclude in the format | ||
Brian Granger
|
r3278 | data dict. If this is set all format types will be computed, | ||
except for those included in this argument. | ||||
MinRK
|
r10448 | 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. | ||||
Brian Granger
|
r3278 | """ | ||
MinRK
|
r10450 | raw = kwargs.get('raw', False) | ||
Brian Granger
|
r3288 | include = kwargs.get('include') | ||
exclude = kwargs.get('exclude') | ||||
MinRK
|
r10448 | metadata = kwargs.get('metadata') | ||
Bernardo B. Marques
|
r4872 | |||
Brian Granger
|
r3278 | from IPython.core.interactiveshell import InteractiveShell | ||
Dan McDougall
|
r10490 | |||
Jonathan Frederic
|
r14233 | if not raw: | ||
format = InteractiveShell.instance().display_formatter.format | ||||
for obj in objs: | ||||
MinRK
|
r14795 | if raw: | ||
MinRK
|
r16585 | publish_display_data(data=obj, metadata=metadata) | ||
MinRK
|
r14795 | else: | ||
format_dict, md_dict = format(obj, include=include, exclude=exclude) | ||||
Min RK
|
r19381 | if not format_dict: | ||
# nothing to display (e.g. _ipython_display_ took over) | ||||
continue | ||||
MinRK
|
r14795 | if metadata: | ||
# kwarg-specified metadata gets precedence | ||||
_merge(md_dict, metadata) | ||||
MinRK
|
r16585 | publish_display_data(data=format_dict, metadata=md_dict) | ||
Brian Granger
|
r3279 | |||
MinRK
|
r10448 | |||
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) | ||||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
MinRK
|
r10448 | """ | ||
_display_mimetype('text/plain', objs, **kwargs) | ||||
Brian Granger
|
r3279 | |||
Brian E. Granger
|
r4526 | def display_html(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """Display the HTML representation of an object. | ||
Parameters | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
Brian E. Granger
|
r4528 | The Python objects to display, or if raw=True raw HTML data to | ||
Brian E. Granger
|
r4526 | display. | ||
raw : bool | ||||
Are the data objects raw data or Python objects that need to be | ||||
formatted before display? [default: False] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian E. Granger
|
r4526 | """ | ||
MinRK
|
r10448 | _display_mimetype('text/html', objs, **kwargs) | ||
Brian Granger
|
r3278 | |||
Andrew Jesaitis
|
r16364 | 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) | ||||
Brian E. Granger
|
r4526 | def display_svg(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """Display the SVG representation of an object. | ||
Parameters | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
Brian E. Granger
|
r4526 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian Granger
|
r3278 | """ | ||
MinRK
|
r10448 | _display_mimetype('image/svg+xml', objs, **kwargs) | ||
Brian Granger
|
r3278 | |||
Brian E. Granger
|
r4526 | def display_png(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """Display the PNG representation of an object. | ||
Parameters | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
Brian E. Granger
|
r4526 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian Granger
|
r3278 | """ | ||
MinRK
|
r10448 | _display_mimetype('image/png', objs, **kwargs) | ||
Brian Granger
|
r3278 | |||
Brian E. Granger
|
r4528 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian E. Granger
|
r4528 | """ | ||
MinRK
|
r10448 | _display_mimetype('image/jpeg', objs, **kwargs) | ||
Brian E. Granger
|
r4528 | |||
Brian E. Granger
|
r4526 | def display_latex(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """Display the LaTeX representation of an object. | ||
Parameters | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
Brian E. Granger
|
r4526 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian Granger
|
r3278 | """ | ||
MinRK
|
r10448 | _display_mimetype('text/latex', objs, **kwargs) | ||
Brian Granger
|
r3278 | |||
Brian E. Granger
|
r4526 | def display_json(*objs, **kwargs): | ||
Brian Granger
|
r3278 | """Display the JSON representation of an object. | ||
Kyle Kelley
|
r10212 | |||
Thomas Kluyver
|
r8086 | Note that not many frontends support displaying JSON. | ||
Brian Granger
|
r3278 | |||
Parameters | ||||
---------- | ||||
Brian Granger
|
r3288 | objs : tuple of objects | ||
Brian E. Granger
|
r4526 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian Granger
|
r3278 | """ | ||
MinRK
|
r10448 | _display_mimetype('application/json', objs, **kwargs) | ||
Brian Granger
|
r3278 | |||
Brian E. Granger
|
r4526 | def display_javascript(*objs, **kwargs): | ||
Brian Granger
|
r3878 | """Display the Javascript representation of an object. | ||
Brian Granger
|
r3278 | |||
Brian Granger
|
r3878 | Parameters | ||
---------- | ||||
objs : tuple of objects | ||||
Brian E. Granger
|
r4526 | 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] | ||||
MinRK
|
r10448 | metadata : dict (optional) | ||
MinRK
|
r10450 | Metadata to be associated with the specific mimetype output. | ||
Brian Granger
|
r3878 | """ | ||
MinRK
|
r10448 | _display_mimetype('application/javascript', objs, **kwargs) | ||
Brian E. Granger
|
r4526 | |||
Brian E. Granger
|
r15121 | |||
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) | ||||
Brian E. Granger
|
r4526 | #----------------------------------------------------------------------------- | ||
# Smart classes | ||||
#----------------------------------------------------------------------------- | ||||
class DisplayObject(object): | ||||
"""An object that wraps data to be displayed.""" | ||||
Brian E. Granger
|
r4528 | _read_flags = 'r' | ||
Jessica B. Hamrick
|
r16396 | _show_mem_addr = False | ||
Brian E. Granger
|
r4528 | |||
def __init__(self, data=None, url=None, filename=None): | ||||
"""Create a display object given raw data. | ||||
Brian E. Granger
|
r4526 | |||
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 | ||||
Bernardo B. Marques
|
r4872 | and then displayed. If | ||
Brian E. Granger
|
r4526 | |||
Parameters | ||||
---------- | ||||
data : unicode, str or bytes | ||||
MinRK
|
r10050 | The raw data or a URL or file to load the data from | ||
Brian E. Granger
|
r4528 | url : unicode | ||
A URL to download the data from. | ||||
filename : unicode | ||||
Path to a local file to load the data from. | ||||
Brian E. Granger
|
r4526 | """ | ||
MinRK
|
r10050 | 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 | ||||
Kyle Kelley
|
r10212 | |||
MinRK
|
r10050 | self.data = data | ||
self.url = url | ||||
Thomas Kluyver
|
r13353 | self.filename = None if filename is None else unicode_type(filename) | ||
Kyle Kelley
|
r10212 | |||
Brian E. Granger
|
r4528 | self.reload() | ||
MinRK
|
r14153 | self._check_data() | ||
Jessica B. Hamrick
|
r16396 | |||
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 | ||||
MinRK
|
r14153 | def _check_data(self): | ||
"""Override in subclasses if there's something to check.""" | ||||
pass | ||||
Brian E. Granger
|
r4528 | |||
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: | ||||
Sean Vig
|
r13640 | try: | ||
from urllib.request import urlopen # Py3 | ||||
except ImportError: | ||||
from urllib2 import urlopen | ||||
response = urlopen(self.url) | ||||
Brian E. Granger
|
r4528 | self.data = response.read() | ||
MinRK
|
r4684 | # 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') | ||||
Brian E. Granger
|
r4528 | except: | ||
self.data = None | ||||
Brian E. Granger
|
r4526 | |||
MinRK
|
r14153 | 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): | ||||
MinRK
|
r14159 | raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data)) | ||
MinRK
|
r14153 | |||
class Pretty(TextDisplayObject): | ||||
Brian E. Granger
|
r4526 | |||
def _repr_pretty_(self): | ||||
return self.data | ||||
MinRK
|
r14153 | class HTML(TextDisplayObject): | ||
Brian E. Granger
|
r4526 | |||
def _repr_html_(self): | ||||
return self.data | ||||
Dan McDougall
|
r10490 | 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_() | ||||
Brian E. Granger
|
r4526 | |||
Andrew Jesaitis
|
r16364 | class Markdown(TextDisplayObject): | ||
def _repr_markdown_(self): | ||||
return self.data | ||||
MinRK
|
r14153 | class Math(TextDisplayObject): | ||
Brian E. Granger
|
r4526 | |||
def _repr_latex_(self): | ||||
Brian Granger
|
r6065 | s = self.data.strip('$') | ||
return "$$%s$$" % s | ||||
MinRK
|
r14153 | class Latex(TextDisplayObject): | ||
Brian Granger
|
r6065 | |||
def _repr_latex_(self): | ||||
Brian E. Granger
|
r4526 | return self.data | ||
Brian E. Granger
|
r4528 | class SVG(DisplayObject): | ||
Kyle Kelley
|
r10212 | |||
MinRK
|
r5671 | # wrap data in a property, which extracts the <svg> tag, discarding | ||
# document headers | ||||
_data = None | ||||
Kyle Kelley
|
r10212 | |||
MinRK
|
r5671 | @property | ||
def data(self): | ||||
return self._data | ||||
Kyle Kelley
|
r10212 | |||
MinRK
|
r5671 | @data.setter | ||
def data(self, svg): | ||||
if svg is None: | ||||
self._data = None | ||||
return | ||||
# parse into dom object | ||||
Thomas Kluyver
|
r9390 | from xml.dom import minidom | ||
MinRK
|
r11535 | svg = cast_bytes_py2(svg) | ||
MinRK
|
r5671 | 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 | ||||
MinRK
|
r11535 | svg = cast_unicode(svg) | ||
MinRK
|
r5671 | self._data = svg | ||
Kyle Kelley
|
r10212 | |||
Brian E. Granger
|
r4526 | def _repr_svg_(self): | ||
return self.data | ||||
Min RK
|
r19557 | 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 _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, string_types): | ||||
warnings.warn("JSON expects JSONable dict or list, not JSON strings") | ||||
data = json.loads(data) | ||||
self._data = data | ||||
Brian E. Granger
|
r4526 | |||
def _repr_json_(self): | ||||
return self.data | ||||
Brian Granger
|
r6120 | css_t = """$("head").append($("<link/>").attr({ | ||
rel: "stylesheet", | ||||
type: "text/css", | ||||
href: "%s" | ||||
})); | ||||
""" | ||||
lib_t1 = """$.getScript("%s", function () { | ||||
""" | ||||
lib_t2 = """}); | ||||
""" | ||||
Brian E. Granger
|
r4526 | |||
MinRK
|
r14153 | class Javascript(TextDisplayObject): | ||
Brian E. Granger
|
r4526 | |||
Brian Granger
|
r6120 | 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 | ||||
Kyle Kelley
|
r10212 | downloaded and then displayed. | ||
MinRK
|
r6425 | In the Notebook, the containing element will be available as `element`, | ||
Andrew Payne
|
r17002 | and jQuery will be available. Content appended to `element` will be | ||
visible in the output area. | ||||
Brian Granger
|
r6120 | |||
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. | ||||
Kyle Kelley
|
r10212 | The full URLs of the css files should be given. A single css URL | ||
Brian Granger
|
r6120 | can also be given as a string. | ||
""" | ||||
Thomas Kluyver
|
r13353 | if isinstance(lib, string_types): | ||
Brian Granger
|
r6120 | lib = [lib] | ||
elif lib is None: | ||||
lib = [] | ||||
Thomas Kluyver
|
r13353 | if isinstance(css, string_types): | ||
Brian Granger
|
r6120 | 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) | ||||
Brian E. Granger
|
r4526 | def _repr_javascript_(self): | ||
Brian Granger
|
r6120 | r = '' | ||
for c in self.css: | ||||
r += css_t % c | ||||
for l in self.lib: | ||||
r += lib_t1 % l | ||||
r += self.data | ||||
Brian Granger
|
r6121 | r += lib_t2*len(self.lib) | ||
Brian Granger
|
r6120 | return r | ||
Brian E. Granger
|
r4526 | |||
MinRK
|
r10049 | # constants for identifying png/jpeg data | ||
_PNG = b'\x89PNG\r\n\x1a\n' | ||||
_JPEG = b'\xff\xd8' | ||||
Brian E. Granger
|
r4526 | |||
MinRK
|
r10803 | 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 | ||||
Brian E. Granger
|
r4528 | class Image(DisplayObject): | ||
_read_flags = 'rb' | ||||
Jerry Fowler
|
r8077 | _FMT_JPEG = u'jpeg' | ||
_FMT_PNG = u'png' | ||||
_ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG] | ||||
Brian E. Granger
|
r4528 | |||
Min RK
|
r20986 | def __init__(self, data=None, url=None, filename=None, format=u'png', | ||
embed=None, width=None, height=None, retina=False, | ||||
unconfined=False, metadata=None): | ||||
Andrew Mark
|
r12557 | """Create a PNG/JPEG image object given raw data. | ||
Brian E. Granger
|
r4528 | |||
Andrew Mark
|
r12557 | When this object is returned by an input cell or passed to the | ||
Brian E. Granger
|
r4528 | display function, it will result in the image being displayed | ||
in the frontend. | ||||
Parameters | ||||
---------- | ||||
data : unicode, str or bytes | ||||
MinRK
|
r10619 | The raw image data or a URL or filename to load the data from. | ||
This always results in embedded image data. | ||||
Brian E. Granger
|
r4528 | url : unicode | ||
MinRK
|
r10619 | A URL to download the data from. If you specify `url=`, | ||
the image data will not be embedded unless you also specify `embed=True`. | ||||
Brian E. Granger
|
r4528 | filename : unicode | ||
Path to a local file to load the data from. | ||||
MinRK
|
r10619 | Images from a file are always embedded. | ||
Brian E. Granger
|
r4528 | 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 | ||||
Matthias BUSSONNIER
|
r6529 | 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` | ||||
Jerry Fowler
|
r8077 | width : int | ||
Width to which to constrain the image in html | ||||
height : int | ||||
Height to which to constrain the image in html | ||||
MinRK
|
r10803 | 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. | ||||
Min RK
|
r20986 | unconfined: bool | ||
Set unconfined=True to disable max-width confinement of the image. | ||||
metadata: dict | ||||
Specify extra metadata to attach to the image. | ||||
Matthias BUSSONNIER
|
r6529 | |||
Examples | ||||
-------- | ||||
MinRK
|
r10619 | # 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. | ||||
Matthias BUSSONNIER
|
r6529 | Image('http://www.google.fr/images/srpr/logo3w.png') | ||
MinRK
|
r10619 | Image('/path/to/image.jpg') | ||
Image(b'RAW_PNG_DATA...') | ||||
Matthias BUSSONNIER
|
r6529 | |||
MinRK
|
r10619 | # 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. | ||||
Matthias BUSSONNIER
|
r6529 | Image(url='http://www.google.fr/images/srpr/logo3w.png') | ||
Brian E. Granger
|
r4528 | """ | ||
if filename is not None: | ||||
ext = self._find_ext(filename) | ||||
elif url is not None: | ||||
ext = self._find_ext(url) | ||||
Jerry Fowler
|
r8077 | elif data is None: | ||
raise ValueError("No image data found. Expecting filename, url, or data.") | ||||
MinRK
|
r10050 | elif isinstance(data, string_types) and ( | ||
data.startswith('http') or _safe_exists(data) | ||||
): | ||||
Brian E. Granger
|
r4528 | ext = self._find_ext(data) | ||
else: | ||||
ext = None | ||||
Jerry Fowler
|
r8077 | |||
Brian E. Granger
|
r4528 | if ext is not None: | ||
Jerry Fowler
|
r8077 | format = ext.lower() | ||
Brian E. Granger
|
r4528 | if ext == u'jpg' or ext == u'jpeg': | ||
Jerry Fowler
|
r8077 | format = self._FMT_JPEG | ||
Brian E. Granger
|
r4528 | if ext == u'png': | ||
Jerry Fowler
|
r8077 | format = self._FMT_PNG | ||
MinRK
|
r10049 | 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' | ||||
Jerry Fowler
|
r8077 | |||
Thomas Kluyver
|
r13353 | self.format = unicode_type(format).lower() | ||
Matthias BUSSONNIER
|
r6529 | self.embed = embed if embed is not None else (url is None) | ||
Jerry Fowler
|
r8077 | |||
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 | ||||
MinRK
|
r10803 | self.retina = retina | ||
Min RK
|
r20986 | self.unconfined = unconfined | ||
self.metadata = metadata | ||||
Brian E. Granger
|
r4528 | super(Image, self).__init__(data=data, url=url, filename=filename) | ||
MinRK
|
r10803 | |||
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 | ||||
Brian E. Granger
|
r4528 | |||
def reload(self): | ||||
"""Reload the raw data from file or URL.""" | ||||
if self.embed: | ||||
super(Image,self).reload() | ||||
MinRK
|
r10803 | if self.retina: | ||
self._retina_shape() | ||||
Brian E. Granger
|
r4528 | |||
def _repr_html_(self): | ||||
if not self.embed: | ||||
Min RK
|
r20986 | width = height = klass = '' | ||
Jerry Fowler
|
r8077 | if self.width: | ||
width = ' width="%d"' % self.width | ||||
if self.height: | ||||
height = ' height="%d"' % self.height | ||||
Min RK
|
r20986 | if self.unconfined: | ||
klass = ' class="unconfined"' | ||||
return u'<img src="{url}"{width}{height}{klass}/>'.format( | ||||
url=self.url, | ||||
width=width, | ||||
height=height, | ||||
klass=klass, | ||||
) | ||||
Dan McDougall
|
r10490 | |||
MinRK
|
r10444 | 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 | ||||
Min RK
|
r20986 | if self.unconfined: | ||
md['unconfined'] = self.unconfined | ||||
if self.metadata: | ||||
md.update(self.metadata) | ||||
MinRK
|
r10444 | if md: | ||
return self.data, md | ||||
else: | ||||
return self.data | ||||
Brian E. Granger
|
r4528 | |||
def _repr_png_(self): | ||||
if self.embed and self.format == u'png': | ||||
MinRK
|
r10444 | return self._data_and_metadata() | ||
Brian E. Granger
|
r4528 | |||
def _repr_jpeg_(self): | ||||
if self.embed and (self.format == u'jpeg' or self.format == u'jpg'): | ||||
MinRK
|
r10444 | return self._data_and_metadata() | ||
Brian E. Granger
|
r4528 | |||
def _find_ext(self, s): | ||||
Thomas Kluyver
|
r13353 | return unicode_type(s.split('.')[-1].lower()) | ||
Brian Granger
|
r5080 | |||
Daniel Wehner
|
r17001 | class Video(DisplayObject): | ||
def __init__(self, data=None, url=None, filename=None, embed=None, 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 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. | ||||
Videos from a file are always embedded. | ||||
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` | ||||
mimetype: unicode | ||||
Specify the mimetype in case you load in a encoded video. | ||||
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=False) | ||||
""" | ||||
if url is None and (data.startswith('http') or data.startswith('https')): | ||||
url = data | ||||
data = None | ||||
embed = False | ||||
elif os.path.exists(data): | ||||
filename = data | ||||
data = None | ||||
self.mimetype = mimetype | ||||
self.embed = embed if embed is not None else (filename is not None) | ||||
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 uses base64 encoded videos. | ||||
if self.filename is not None: | ||||
mimetypes.init() | ||||
mimetype, encoding = mimetypes.guess_type(self.filename) | ||||
video = open(self.filename, 'rb').read() | ||||
video_encoded = video.encode('base64') | ||||
else: | ||||
video_encoded = self.data | ||||
mimetype = self.mimetype | ||||
output = """<video controls> | ||||
<source src="data:{0};base64,{1}" type="{0}"> | ||||
Your browser does not support the video tag. | ||||
</video>""".format(mimetype, video_encoded) | ||||
return output | ||||
def reload(self): | ||||
# TODO | ||||
pass | ||||
def _repr_png_(self): | ||||
# TODO | ||||
pass | ||||
def _repr_jpeg_(self): | ||||
# TODO | ||||
pass | ||||
Brian Granger
|
r5080 | |||
Jonathan Frederic
|
r12592 | 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.""" | ||||
Brian Granger
|
r5080 | from IPython.core.interactiveshell import InteractiveShell | ||
MinRK
|
r6422 | if InteractiveShell.initialized(): | ||
Jonathan Frederic
|
r12592 | InteractiveShell.instance().display_pub.clear_output(wait) | ||
MinRK
|
r6422 | else: | ||
from IPython.utils import io | ||||
Jonathan Frederic
|
r12589 | print('\033[2K\r', file=io.stdout, end='') | ||
io.stdout.flush() | ||||
print('\033[2K\r', file=io.stderr, end='') | ||||
io.stderr.flush() | ||||
Brian E. Granger
|
r15124 | |||
Brian E. Granger
|
r15126 | @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:: | ||||
MinRK
|
r15393 | c.InlineBackend.figure_formats = {'png', 'jpeg'} | ||
c.InlineBackend.print_figure_kwargs.update({'quality' : 90}) | ||||
Brian E. Granger
|
r15124 | |||
Parameters | ||||
Brian E. Granger
|
r15126 | ---------- | ||
MinRK
|
r15393 | *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``. | ||||
Brian E. Granger
|
r15124 | """ | ||
from IPython.core.interactiveshell import InteractiveShell | ||||
from IPython.core.pylabtools import select_figure_formats | ||||
MinRK
|
r15393 | 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) | ||||
Brian E. Granger
|
r15124 | shell = InteractiveShell.instance() | ||
MinRK
|
r15393 | select_figure_formats(shell, formats, **kw) | ||
Brian E. Granger
|
r15124 | |||
Brian E. Granger
|
r15126 | @skip_doctest | ||
MinRK
|
r15395 | def set_matplotlib_close(close=True): | ||
Brian E. Granger
|
r15197 | """Set whether the inline backend closes all figures automatically or not. | ||
Brian E. Granger
|
r15126 | |||
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? | ||||
""" | ||||
MinRK
|
r15395 | from IPython.kernel.zmq.pylab.config import InlineBackend | ||
cfg = InlineBackend.instance() | ||||
cfg.close_figures = close | ||||
Brian E. Granger
|
r15126 | |||