|
|
# -*- coding: utf-8 -*-
|
|
|
"""An interface for publishing rich data to frontends.
|
|
|
|
|
|
Authors:
|
|
|
|
|
|
* Brian Granger
|
|
|
"""
|
|
|
|
|
|
#-----------------------------------------------------------------------------
|
|
|
# Copyright (C) 2008-2010 The IPython Development Team
|
|
|
#
|
|
|
# Distributed under the terms of the BSD License. The full license is in
|
|
|
# the file COPYING, distributed as part of this software.
|
|
|
#-----------------------------------------------------------------------------
|
|
|
|
|
|
#-----------------------------------------------------------------------------
|
|
|
# Imports
|
|
|
#-----------------------------------------------------------------------------
|
|
|
|
|
|
from IPython.config.configurable import Configurable
|
|
|
|
|
|
#-----------------------------------------------------------------------------
|
|
|
# Main payload class
|
|
|
#-----------------------------------------------------------------------------
|
|
|
|
|
|
class DisplayPublisher(Configurable):
|
|
|
|
|
|
def _validate_data(self, source, data, metadata=None):
|
|
|
if not isinstance(source, str):
|
|
|
raise TypeError('source must be a str, got: %r' % source)
|
|
|
if not isinstance(data, dict):
|
|
|
raise TypeError('data must be a dict, got: %r' % data)
|
|
|
if metadata is not None:
|
|
|
if not isinstance(metadata, dict):
|
|
|
raise TypeError('metadata must be a dict, got: %r' % data)
|
|
|
|
|
|
def publish(self, source, data, metadata=None):
|
|
|
"""Publish data and metadata to all frontends.
|
|
|
|
|
|
See the ``display_data`` message in the messaging documentation for
|
|
|
more details about this message type.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
source : str
|
|
|
A string that give the function or method that created the data,
|
|
|
such as 'IPython.core.page'.
|
|
|
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.
|
|
|
"""
|
|
|
from IPython.utils import io
|
|
|
# The default is to simply write the plain text data using io.Term.
|
|
|
if data.has_key('text/plain'):
|
|
|
print >>io.Term.cout, data['text/plain']
|
|
|
|
|
|
|
|
|
def publish_display_data(source, text, svg=None, png=None,
|
|
|
html=None, metadata=None):
|
|
|
"""Publish a display data to the frontends.
|
|
|
|
|
|
This function is a high level helper for the publishing of display data.
|
|
|
It handle a number of common MIME types in a clean API. For other MIME
|
|
|
types, use ``get_ipython().display_pub.publish`` directly.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
text : str/unicode
|
|
|
The string representation of the plot.
|
|
|
|
|
|
svn : str/unicode
|
|
|
The raw svg data of the plot.
|
|
|
|
|
|
png : ???
|
|
|
The raw png data of the plot.
|
|
|
|
|
|
metadata : dict, optional [default empty]
|
|
|
Allows for specification of additional information about the plot data.
|
|
|
"""
|
|
|
from IPython.core.interactiveshell import InteractiveShell
|
|
|
|
|
|
data_dict = {}
|
|
|
data_dict['text/plain'] = text
|
|
|
if svg is not None:
|
|
|
data_dict['image/svg+xml'] = svg
|
|
|
if png is not None:
|
|
|
data_dict['image/png'] = png
|
|
|
if html is not None:
|
|
|
data_dict['text/html'] = html
|
|
|
InteractiveShell.instance().display_pub.publish(
|
|
|
source,
|
|
|
data_dict,
|
|
|
metadata
|
|
|
)
|
|
|
|
