widget.py
442 lines
| 15.1 KiB
| text/x-python
|
PythonLexer
|
r14586 | """Base Widget class. Allows user to create widgets in the back-end that render | ||
in the IPython notebook front-end. | ||||
|
r14283 | """ | ||
#----------------------------------------------------------------------------- | ||||
# Copyright (c) 2013, the IPython Development Team. | ||||
# | ||||
# Distributed under the terms of the Modified BSD License. | ||||
# | ||||
# The full license is in the file COPYING.txt, distributed with this software. | ||||
#----------------------------------------------------------------------------- | ||||
#----------------------------------------------------------------------------- | ||||
# Imports | ||||
#----------------------------------------------------------------------------- | ||||
|
r14579 | from contextlib import contextmanager | ||
|
r14341 | import inspect | ||
|
r14344 | import types | ||
|
r14223 | |||
|
r14229 | from IPython.kernel.comm import Comm | ||
from IPython.config import LoggingConfigurable | ||||
|
r14584 | from IPython.utils.traitlets import Unicode, Dict, Instance, Bool | ||
|
r14232 | from IPython.utils.py3compat import string_types | ||
|
r14283 | #----------------------------------------------------------------------------- | ||
# Classes | ||||
#----------------------------------------------------------------------------- | ||||
|
r14540 | class Widget(LoggingConfigurable): | ||
|
r14223 | |||
|
r14478 | # Shared declarations (Class level) | ||
widget_construction_callback = None | ||||
|
r14586 | widgets = {} | ||
|
r14478 | |||
|
r14583 | keys = ['view_name'] # TODO: Sync = True | ||
|
r14530 | |||
|
r14478 | def on_widget_constructed(callback): | ||
"""Class method, registers a callback to be called when a widget is | ||||
constructed. The callback must have the following signature: | ||||
callback(widget)""" | ||||
|
r14540 | Widget.widget_construction_callback = callback | ||
|
r14478 | |||
|
r14542 | def _call_widget_constructed(widget): | ||
|
r14478 | """Class method, called when a widget is constructed.""" | ||
|
r14540 | if Widget.widget_construction_callback is not None and callable(Widget.widget_construction_callback): | ||
Widget.widget_construction_callback(widget) | ||||
|
r14478 | |||
|
r14313 | |||
|
r14478 | |||
# Public declarations (Instance level) | ||||
|
r14586 | model_name = Unicode('widget', help="""Name of the backbone model | ||
registered in the front-end to create and sync this widget with.""") | ||||
view_name = Unicode(help="""Default view registered in the front-end | ||||
|
r14283 | to use to represent the widget.""") | ||
|
r14313 | |||
|
r14586 | @contextmanager | ||
def property_lock(self, key, value): | ||||
"""Lock a property-value pair. | ||||
NOTE: This, in addition to the single lock for all state changes, is | ||||
flawed. In the future we may want to look into buffering state changes | ||||
back to the front-end.""" | ||||
self._property_lock = (key, value) | ||||
try: | ||||
yield | ||||
finally: | ||||
self._property_lock = (None, None) | ||||
def should_send_property(self, key, value): | ||||
"""Check the property lock (property_lock)""" | ||||
return key != self._property_lock[0] or \ | ||||
value != self._property_lock[1] | ||||
|
r14283 | # Private/protected declarations | ||
|
r14486 | _comm = Instance('IPython.kernel.comm.Comm') | ||
|
r14223 | |||
|
r14310 | def __init__(self, **kwargs): | ||
|
r14283 | """Public constructor | ||
""" | ||||
|
r14583 | self.closed = False | ||
|
r14586 | self._property_lock = (None, None) | ||
|
r14330 | self._display_callbacks = [] | ||
|
r14387 | self._msg_callbacks = [] | ||
|
r14540 | super(Widget, self).__init__(**kwargs) | ||
|
r14478 | |||
|
r14487 | self.on_trait_change(self._handle_property_changed, self.keys) | ||
|
r14542 | Widget._call_widget_constructed(self) | ||
|
r14485 | |||
|
r14223 | def __del__(self): | ||
|
r14283 | """Object disposal""" | ||
|
r14223 | self.close() | ||
|
r14485 | |||
|
r14223 | def close(self): | ||
|
r14283 | """Close method. Closes the widget which closes the underlying comm. | ||
|
r14485 | When the comm is closed, all of the widget views are automatically | ||
|
r14586 | removed from the front-end.""" | ||
|
r14583 | if not self.closed: | ||
|
r14586 | self._comm.close() | ||
self._close() | ||||
def _close(self): | ||||
"""Unsafe close""" | ||||
del Widget.widgets[self.model_id] | ||||
self._comm = None | ||||
self.closed = True | ||||
|
r14485 | @property | ||
def comm(self): | ||||
if self._comm is None: | ||||
|
r14586 | # Create a comm. | ||
self._comm = Comm(target_name=self.model_name) | ||||
self._comm.on_msg(self._handle_msg) | ||||
self._comm.on_close(self._close) | ||||
Widget.widgets[self.model_id] = self | ||||
# first update | ||||
self.send_state() | ||||
|
r14485 | return self._comm | ||
|
r14512 | |||
@property | ||||
def model_id(self): | ||||
|
r14527 | return self.comm.comm_id | ||
|
r14485 | |||
|
r14283 | # Event handlers | ||
|
r14223 | def _handle_msg(self, msg): | ||
|
r14586 | """Called when a msg is received from the front-end""" | ||
|
r14387 | data = msg['content']['data'] | ||
|
r14432 | method = data['method'] | ||
|
r14586 | if not method in ['backbone', 'custom']: | ||
self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method) | ||||
|
r14583 | |||
|
r14538 | # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one. | ||
if method == 'backbone' and 'sync_data' in data: | ||||
sync_data = data['sync_data'] | ||||
|
r14585 | self._handle_receive_state(sync_data) # handles all methods | ||
|
r14387 | |||
# Handle a custom msg from the front-end | ||||
|
r14432 | elif method == 'custom': | ||
if 'custom_content' in data: | ||||
self._handle_custom_msg(data['custom_content']) | ||||
|
r14387 | |||
|
r14558 | |||
|
r14585 | def _handle_receive_state(self, sync_data): | ||
|
r14586 | """Called when a state is received from the front-end.""" | ||
|
r14558 | for name in self.keys: | ||
if name in sync_data: | ||||
|
r14583 | value = self._unpack_widgets(sync_data[name]) | ||
|
r14586 | with self.property_lock(name, value): | ||
|
r14579 | setattr(self, name, value) | ||
|
r14558 | |||
|
r14387 | def _handle_custom_msg(self, content): | ||
|
r14585 | """Called when a custom msg is received.""" | ||
|
r14387 | for handler in self._msg_callbacks: | ||
|
r14586 | handler(self, content) | ||
|
r14485 | |||
|
r14223 | def _handle_property_changed(self, name, old, new): | ||
|
r14486 | """Called when a property has been changed.""" | ||
|
r14392 | # Make sure this isn't information that the front-end just sent us. | ||
|
r14579 | if should_send_property(self, name, new): | ||
|
r14586 | # Send new state to front-end | ||
|
r14273 | self.send_state(key=name) | ||
|
r14232 | |||
|
r14484 | def _handle_displayed(self, **kwargs): | ||
|
r14550 | """Called when a view has been displayed for this widget instance""" | ||
|
r14387 | for handler in self._display_callbacks: | ||
|
r14586 | handler(self, **kwargs) | ||
|
r14485 | |||
|
r14283 | # Public methods | ||
def send_state(self, key=None): | ||||
|
r14586 | """Sends the widget state, or a piece of it, to the front-end. | ||
|
r14283 | |||
Parameters | ||||
---------- | ||||
key : unicode (optional) | ||||
|
r14586 | A single property's name to sync with the front-end. | ||
|
r14283 | """ | ||
|
r14479 | self._send({"method": "update", | ||
|
r14514 | "state": self.get_state()}) | ||
|
r14283 | |||
|
r14486 | def get_state(self, key=None): | ||
|
r14485 | """Gets the widget state, or a piece of it. | ||
|
r14283 | |||
Parameters | ||||
---------- | ||||
|
r14485 | key : unicode (optional) | ||
A single property's name to get. | ||||
|
r14283 | """ | ||
|
r14586 | keys = self.keys if key is None else [key] | ||
return {k: self._pack_widgets(getattr(self, k)) for k in keys} | ||||
|
r14283 | |||
|
r14583 | def _pack_widgets(self, values): | ||
"""This function recursively converts all widget instances to model id | ||||
strings. | ||||
Children widgets will be stored and transmitted to the front-end by | ||||
their model ids.""" | ||||
if isinstance(values, dict): | ||||
new_dict = {} | ||||
|
r14586 | for key, value in values.items(): | ||
new_dict[key] = self._pack_widgets(value) | ||||
|
r14583 | return new_dict | ||
elif isinstance(values, list): | ||||
new_list = [] | ||||
for value in values: | ||||
new_list.append(self._pack_widgets(value)) | ||||
return new_list | ||||
elif isinstance(values, Widget): | ||||
return values.model_id | ||||
else: | ||||
return values | ||||
def _unpack_widgets(self, values): | ||||
"""This function recursively converts all model id strings to widget | ||||
instances. | ||||
Children widgets will be stored and transmitted to the front-end by | ||||
their model ids.""" | ||||
if isinstance(values, dict): | ||||
new_dict = {} | ||||
|
r14586 | for key, values in values.items(): | ||
|
r14583 | new_dict[key] = self._unpack_widgets(values[key]) | ||
return new_dict | ||||
elif isinstance(values, list): | ||||
new_list = [] | ||||
for value in values: | ||||
new_list.append(self._unpack_widgets(value)) | ||||
return new_list | ||||
elif isinstance(values, string_types): | ||||
|
r14586 | if widget.model_id in Widget.widgets: | ||
return Widget.widgets[widget.model_id] | ||||
else: | ||||
return values | ||||
|
r14583 | else: | ||
return values | ||||
|
r14387 | def send(self, content): | ||
"""Sends a custom msg to the widget model in the front-end. | ||||
Parameters | ||||
---------- | ||||
content : dict | ||||
Content of the message to send. | ||||
""" | ||||
|
r14586 | self._send({"method": "custom", "custom_content": content}) | ||
|
r14387 | |||
|
r14586 | def on_msg(self, callback, remove=False): | ||
"""Register or unregister a callback for when a custom msg is recieved | ||||
|
r14583 | from the front-end. | ||
|
r14387 | |||
Parameters | ||||
---------- | ||||
callback: method handler | ||||
Can have a signature of: | ||||
- callback(content) | ||||
- callback(sender, content) | ||||
remove: bool | ||||
True if the callback should be unregistered.""" | ||||
if remove and callback in self._msg_callbacks: | ||||
self._msg_callbacks.remove(callback) | ||||
elif not remove and not callback in self._msg_callbacks: | ||||
|
r14586 | if callable(callback): | ||
argspec = inspect.getargspec(callback) | ||||
nargs = len(argspec[0]) | ||||
# Bound methods have an additional 'self' argument | ||||
if isinstance(callback, types.MethodType): | ||||
nargs -= 1 | ||||
# Call the callback | ||||
if nargs == 1: | ||||
self._msg_callbacks.append(lambda sender, content: callback(content)) | ||||
elif nargs == 2: | ||||
self._msg_callbacks.append(callback) | ||||
else: | ||||
raise TypeError('Widget msg callback must ' \ | ||||
'accept 1 or 2 arguments, not %d.' % nargs) | ||||
else: | ||||
raise Exception('Callback must be callable.') | ||||
|
r14387 | |||
|
r14330 | def on_displayed(self, callback, remove=False): | ||
|
r14583 | """Register or unregister a callback to be called when the widget has | ||
been displayed. | ||||
|
r14330 | |||
|
r14332 | Parameters | ||
---------- | ||||
|
r14330 | callback: method handler | ||
Can have a signature of: | ||||
|
r14484 | - callback(sender, **kwargs) | ||
kwargs from display call passed through without modification. | ||||
|
r14330 | remove: bool | ||
True if the callback should be unregistered.""" | ||||
|
r14387 | if remove and callback in self._display_callbacks: | ||
|
r14330 | self._display_callbacks.remove(callback) | ||
|
r14387 | elif not remove and not callback in self._display_callbacks: | ||
|
r14586 | if callable(handler): | ||
self._display_callbacks.append(callback) | ||||
else: | ||||
raise Exception('Callback must be callable.') | ||||
|
r14330 | |||
|
r14283 | # Support methods | ||
|
r14586 | def _ipython_display_(self, **kwargs): | ||
|
r14283 | """Function that is called when `IPython.display.display` is called on | ||
|
r14549 | the widget.""" | ||
|
r14223 | |||
|
r14548 | # Show view. By sending a display message, the comm is opened and the | ||
# initial state is sent. | ||||
|
r14549 | self._send({"method": "display"}) | ||
|
r14485 | self._handle_displayed(**kwargs) | ||
|
r14479 | |||
def _send(self, msg): | ||||
"""Sends a message to the model in the front-end""" | ||||
|
r14548 | self.comm.send(msg) | ||
|
r14516 | |||
|
r14540 | class DOMWidget(Widget): | ||
|
r14485 | visible = Bool(True, help="Whether or not the widget is visible.") | ||
# Private/protected declarations | ||||
_css = Dict() # Internal CSS property dict | ||||
|
r14540 | keys = ['visible', '_css'] + Widget.keys | ||
|
r14485 | |||
def get_css(self, key, selector=""): | ||||
|
r14581 | """Get a CSS property of the widget. | ||
Note: This function does not actually request the CSS from the | ||||
front-end; Only properties that have been set with set_css can be read. | ||||
|
r14485 | |||
Parameters | ||||
---------- | ||||
key: unicode | ||||
CSS key | ||||
selector: unicode (optional) | ||||
JQuery selector used when the CSS key/value was set. | ||||
""" | ||||
if selector in self._css and key in self._css[selector]: | ||||
return self._css[selector][key] | ||||
else: | ||||
return None | ||||
def set_css(self, *args, **kwargs): | ||||
|
r14581 | """Set one or more CSS properties of the widget. | ||
This function has two signatures: | ||||
|
r14551 | - set_css(css_dict, selector='') | ||
- set_css(key, value, selector='') | ||||
|
r14485 | |||
Parameters | ||||
---------- | ||||
css_dict : dict | ||||
CSS key/value pairs to apply | ||||
key: unicode | ||||
CSS key | ||||
value | ||||
CSS value | ||||
selector: unicode (optional) | ||||
|
r14581 | JQuery selector to use to apply the CSS key/value. If no selector | ||
is provided, an empty selector is used. An empty selector makes the | ||||
front-end try to apply the css to a default element. The default | ||||
element is an attribute unique to each view, which is a DOM element | ||||
of the view that should be styled with common CSS (see | ||||
`$el_to_style` in the Javascript code). | ||||
|
r14485 | """ | ||
selector = kwargs.get('selector', '') | ||||
|
r14551 | # Signature 1: set_css(css_dict, selector='') | ||
|
r14485 | if len(args) == 1: | ||
if isinstance(args[0], dict): | ||||
for (key, value) in args[0].items(): | ||||
|
r14583 | if not (key in self._css[selector] and value == self._css[selector][key]): | ||
|
r14552 | self._css[selector][key] = value | ||
self.send_state('_css') | ||||
|
r14485 | else: | ||
raise Exception('css_dict must be a dict.') | ||||
|
r14551 | # Signature 2: set_css(key, value, selector='') | ||
|
r14485 | elif len(args) == 2 or len(args) == 3: | ||
# Selector can be a positional arg if it's the 3rd value | ||||
if len(args) == 3: | ||||
selector = args[2] | ||||
if selector not in self._css: | ||||
self._css[selector] = {} | ||||
# Only update the property if it has changed. | ||||
key = args[0] | ||||
value = args[1] | ||||
|
r14583 | if not (key in self._css[selector] and value == self._css[selector][key]): | ||
|
r14485 | self._css[selector][key] = value | ||
self.send_state('_css') # Send new state to client. | ||||
else: | ||||
raise Exception('set_css only accepts 1-3 arguments') | ||||
|
r14539 | def add_class(self, class_names, selector=""): | ||
|
r14485 | """Add class[es] to a DOM element | ||
Parameters | ||||
---------- | ||||
|
r14539 | class_names: unicode or list | ||
Class name(s) to add to the DOM element(s). | ||||
|
r14485 | selector: unicode (optional) | ||
JQuery selector to select the DOM element(s) that the class(es) will | ||||
be added to. | ||||
""" | ||||
|
r14539 | class_list = class_names | ||
|
r14583 | if isinstance(class_list, list): | ||
|
r14539 | class_list = ' '.join(class_list) | ||
|
r14504 | self.send({"msg_type": "add_class", | ||
|
r14539 | "class_list": class_list, | ||
|
r14514 | "selector": selector}) | ||
|
r14485 | |||
|
r14539 | def remove_class(self, class_names, selector=""): | ||
|
r14485 | """Remove class[es] from a DOM element | ||
Parameters | ||||
---------- | ||||
|
r14539 | class_names: unicode or list | ||
Class name(s) to remove from the DOM element(s). | ||||
|
r14485 | selector: unicode (optional) | ||
JQuery selector to select the DOM element(s) that the class(es) will | ||||
be removed from. | ||||
""" | ||||
|
r14539 | class_list = class_names | ||
|
r14583 | if isinstance(class_list, list): | ||
|
r14539 | class_list = ' '.join(class_list) | ||
|
r14504 | self.send({"msg_type": "remove_class", | ||
|
r14539 | "class_list": class_list, | ||
|
r14514 | "selector": selector}) | ||