widget.py
489 lines
| 17.9 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 | ||
|
r17621 | import collections | ||
|
r14223 | |||
|
r15192 | from IPython.core.getipython import get_ipython | ||
|
r14229 | from IPython.kernel.comm import Comm | ||
from IPython.config import LoggingConfigurable | ||||
|
r18506 | from IPython.utils.importstring import import_item | ||
|
r17723 | from IPython.utils.traitlets import Unicode, Dict, Instance, Bool, List, \ | ||
CaselessStrEnum, Tuple, CUnicode, Int, Set | ||||
|
r14232 | from IPython.utils.py3compat import string_types | ||
|
r14283 | #----------------------------------------------------------------------------- | ||
# Classes | ||||
#----------------------------------------------------------------------------- | ||||
|
r14658 | class CallbackDispatcher(LoggingConfigurable): | ||
|
r14793 | """A structure for registering and running callbacks""" | ||
callbacks = List() | ||||
def __call__(self, *args, **kwargs): | ||||
"""Call all of the registered callbacks.""" | ||||
|
r14721 | value = None | ||
|
r14793 | for callback in self.callbacks: | ||
try: | ||||
local_value = callback(*args, **kwargs) | ||||
except Exception as e: | ||||
|
r15192 | ip = get_ipython() | ||
if ip is None: | ||||
self.log.warn("Exception in callback %s: %s", callback, e, exc_info=True) | ||||
else: | ||||
ip.showtraceback() | ||||
|
r14793 | else: | ||
|
r14721 | value = local_value if local_value is not None else value | ||
return value | ||||
|
r14658 | |||
def register_callback(self, callback, remove=False): | ||||
"""(Un)Register a callback | ||||
Parameters | ||||
---------- | ||||
callback: method handle | ||||
|
r14793 | Method to be registered or unregistered. | ||
|
r14658 | remove=False: bool | ||
|
r14793 | Whether to unregister the callback.""" | ||
|
r14658 | # (Un)Register the callback. | ||
|
r14793 | if remove and callback in self.callbacks: | ||
self.callbacks.remove(callback) | ||||
elif not remove and callback not in self.callbacks: | ||||
self.callbacks.append(callback) | ||||
|
r14223 | |||
|
r15192 | def _show_traceback(method): | ||
"""decorator for showing tracebacks in IPython""" | ||||
def m(self, *args, **kwargs): | ||||
try: | ||||
return(method(self, *args, **kwargs)) | ||||
except Exception as e: | ||||
ip = get_ipython() | ||||
if ip is None: | ||||
self.log.warn("Exception in widget method %s: %s", method, e, exc_info=True) | ||||
else: | ||||
ip.showtraceback() | ||||
return m | ||||
|
r14658 | |||
|
r18530 | |||
def register(key=None): | ||||
|
r18532 | """Returns a decorator registering a widget class in the widget registry. | ||
If no key is provided, the class name is used as a key. A key is | ||||
|
r18533 | provided for each core IPython widget so that the frontend can use | ||
|
r18532 | this key regardless of the language of the kernel""" | ||
|
r18530 | def wrap(widget): | ||
|
r18532 | l = key if key is not None else widget.__module__ + widget.__name__ | ||
|
r18530 | Widget.widget_types[l] = widget | ||
return widget | ||||
return wrap | ||||
|
r14658 | class Widget(LoggingConfigurable): | ||
|
r14653 | #------------------------------------------------------------------------- | ||
# Class attributes | ||||
#------------------------------------------------------------------------- | ||||
|
r14793 | _widget_construction_callback = None | ||
|
r14586 | widgets = {} | ||
|
r18530 | widget_types = {} | ||
|
r14478 | |||
|
r14793 | @staticmethod | ||
|
r14478 | def on_widget_constructed(callback): | ||
|
r14793 | """Registers a callback to be called when a widget is constructed. | ||
|
r14607 | |||
The callback must have the following signature: | ||||
|
r14478 | callback(widget)""" | ||
|
r14793 | Widget._widget_construction_callback = callback | ||
|
r14478 | |||
|
r14793 | @staticmethod | ||
|
r14542 | def _call_widget_constructed(widget): | ||
|
r14793 | """Static method, called when a widget is constructed.""" | ||
if Widget._widget_construction_callback is not None and callable(Widget._widget_construction_callback): | ||||
Widget._widget_construction_callback(widget) | ||||
|
r14478 | |||
|
r18506 | @staticmethod | ||
def handle_comm_opened(comm, msg): | ||||
"""Static method, called when a widget is constructed.""" | ||||
|
r18515 | widget_class = import_item(msg['content']['data']['widget_class']) | ||
|
r18514 | widget = widget_class(comm=comm) | ||
|
r18506 | |||
|
r14653 | #------------------------------------------------------------------------- | ||
# Traits | ||||
#------------------------------------------------------------------------- | ||||
|
r18466 | _model_module = Unicode(None, allow_none=True, help="""A requirejs module name | ||
in which to find _model_name. If empty, look in the global registry.""") | ||||
|
r14896 | _model_name = Unicode('WidgetModel', help="""Name of the backbone model | ||
|
r14586 | registered in the front-end to create and sync this widget with.""") | ||
|
r18143 | _view_module = Unicode(help="""A requirejs module in which to find _view_name. | ||
|
r18142 | If empty, look in the global registry.""", sync=True) | ||
|
r17989 | _view_name = Unicode(None, allow_none=True, help="""Default view registered in the front-end | ||
|
r14588 | to use to represent the widget.""", sync=True) | ||
|
r17615 | comm = Instance('IPython.kernel.comm.Comm') | ||
|
r14793 | |||
|
r15368 | msg_throttle = Int(3, sync=True, help="""Maximum number of msgs the | ||
front-end can send before receiving an idle msg from the back-end.""") | ||||
|
r14793 | |||
|
r18311 | version = Int(0, sync=True, help="""Widget's version""") | ||
|
r14793 | keys = List() | ||
def _keys_default(self): | ||||
return [name for name in self.traits(sync=True)] | ||||
_property_lock = Tuple((None, None)) | ||||
|
r17621 | _send_state_lock = Int(0) | ||
_states_to_send = Set(allow_none=False) | ||||
|
r14793 | _display_callbacks = Instance(CallbackDispatcher, ()) | ||
_msg_callbacks = Instance(CallbackDispatcher, ()) | ||||
|
r14653 | #------------------------------------------------------------------------- | ||
# (Con/de)structor | ||||
|
r14793 | #------------------------------------------------------------------------- | ||
|
r18517 | def __init__(self, **kwargs): | ||
|
r14607 | """Public constructor""" | ||
|
r17616 | self._model_id = kwargs.pop('model_id', None) | ||
|
r14540 | super(Widget, self).__init__(**kwargs) | ||
|
r14478 | |||
|
r14542 | Widget._call_widget_constructed(self) | ||
|
r18514 | self.open() | ||
|
r14485 | |||
|
r14223 | def __del__(self): | ||
|
r14283 | """Object disposal""" | ||
|
r14223 | self.close() | ||
|
r14485 | |||
|
r14653 | #------------------------------------------------------------------------- | ||
# Properties | ||||
|
r14793 | #------------------------------------------------------------------------- | ||
|
r14586 | |||
|
r17612 | def open(self): | ||
"""Open a comm to the frontend if one isn't already open.""" | ||||
|
r17615 | if self.comm is None: | ||
|
r18466 | args = dict(target_name='ipython.widget', | ||
data={'model_name': self._model_name, | ||||
'model_module': self._model_module}) | ||||
|
r18264 | if self._model_id is not None: | ||
args['comm_id'] = self._model_id | ||||
|
r18511 | self.comm = Comm(**args) | ||
|
r17612 | |||
|
r18511 | def _comm_changed(self, name, new): | ||
"""Called when the comm is changed.""" | ||||
|
r18796 | if new is None: | ||
return | ||||
|
r18509 | self._model_id = self.model_id | ||
self.comm.on_msg(self._handle_msg) | ||||
Widget.widgets[self.model_id] = self | ||||
|
r18507 | # first update | ||
self.send_state() | ||||
|
r14512 | @property | ||
def model_id(self): | ||||
|
r14654 | """Gets the model id of this widget. | ||
If a Comm doesn't exist yet, a Comm will be created automagically.""" | ||||
|
r14527 | return self.comm.comm_id | ||
|
r14485 | |||
|
r14653 | #------------------------------------------------------------------------- | ||
# Methods | ||||
|
r14793 | #------------------------------------------------------------------------- | ||
|
r14653 | def close(self): | ||
|
r14793 | """Close method. | ||
|
r14232 | |||
|
r17405 | Closes the underlying comm. | ||
|
r14653 | When the comm is closed, all of the widget views are automatically | ||
removed from the front-end.""" | ||||
|
r17615 | if self.comm is not None: | ||
|
r17540 | Widget.widgets.pop(self.model_id, None) | ||
|
r17615 | self.comm.close() | ||
self.comm = None | ||||
|
r17465 | |||
|
r14283 | def send_state(self, key=None): | ||
|
r14586 | """Sends the widget state, or a piece of it, to the front-end. | ||
|
r14283 | |||
Parameters | ||||
---------- | ||||
|
r17621 | key : unicode, or iterable (optional) | ||
A single property's name or iterable of property names to sync with the front-end. | ||||
|
r14283 | """ | ||
|
r14610 | self._send({ | ||
"method" : "update", | ||||
|
r17621 | "state" : self.get_state(key=key) | ||
|
r14610 | }) | ||
|
r14283 | |||
|
r14486 | def get_state(self, key=None): | ||
|
r14485 | """Gets the widget state, or a piece of it. | ||
|
r14283 | |||
Parameters | ||||
---------- | ||||
|
r17621 | key : unicode or iterable (optional) | ||
A single property's name or iterable of property names to get. | ||||
|
r14283 | """ | ||
|
r17621 | if key is None: | ||
keys = self.keys | ||||
elif isinstance(key, string_types): | ||||
keys = [key] | ||||
elif isinstance(key, collections.Iterable): | ||||
keys = key | ||||
else: | ||||
raise ValueError("key must be a string, an iterable of keys, or None") | ||||
|
r17237 | state = {} | ||
for k in keys: | ||||
|
r17674 | f = self.trait_metadata(k, 'to_json', self._trait_to_json) | ||
|
r17294 | value = getattr(self, k) | ||
state[k] = f(value) | ||||
|
r17237 | return state | ||
|
r18070 | |||
def set_state(self, sync_data): | ||||
"""Called when a state is received from the front-end.""" | ||||
for name in self.keys: | ||||
if name in sync_data: | ||||
json_value = sync_data[name] | ||||
from_json = self.trait_metadata(name, 'from_json', self._trait_from_json) | ||||
with self._lock_property(name, json_value): | ||||
setattr(self, name, from_json(json_value)) | ||||
|
r17237 | |||
|
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. | ||||
""" | ||||
|
r14655 | self._send({"method": "custom", "content": content}) | ||
|
r14387 | |||
|
r14586 | def on_msg(self, callback, remove=False): | ||
|
r14793 | """(Un)Register a custom msg receive callback. | ||
|
r14387 | |||
Parameters | ||||
---------- | ||||
|
r14793 | callback: callable | ||
|
r14915 | callback will be passed two arguments when a message arrives:: | ||
|
r14793 | callback(widget, content) | ||
|
r14915 | |||
|
r14387 | remove: bool | ||
True if the callback should be unregistered.""" | ||||
|
r14658 | self._msg_callbacks.register_callback(callback, remove=remove) | ||
|
r14387 | |||
|
r14330 | def on_displayed(self, callback, remove=False): | ||
|
r14607 | """(Un)Register a widget displayed callback. | ||
|
r14330 | |||
|
r14332 | Parameters | ||
---------- | ||||
|
r14330 | callback: method handler | ||
|
r14915 | Must have a signature of:: | ||
|
r14793 | callback(widget, **kwargs) | ||
|
r14915 | |||
|
r14793 | kwargs from display are passed through without modification. | ||
|
r14330 | remove: bool | ||
True if the callback should be unregistered.""" | ||||
|
r14658 | self._display_callbacks.register_callback(callback, remove=remove) | ||
|
r14330 | |||
|
r14653 | #------------------------------------------------------------------------- | ||
|
r14283 | # Support methods | ||
|
r14653 | #------------------------------------------------------------------------- | ||
@contextmanager | ||||
|
r14659 | def _lock_property(self, key, value): | ||
|
r14653 | """Lock a property-value pair. | ||
|
r17674 | The value should be the JSON state of the property. | ||
|
r14653 | 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) | ||||
|
r17621 | @contextmanager | ||
def hold_sync(self): | ||||
"""Hold syncing any state until the context manager is released""" | ||||
# We increment a value so that this can be nested. Syncing will happen when | ||||
# all levels have been released. | ||||
self._send_state_lock += 1 | ||||
try: | ||||
yield | ||||
finally: | ||||
self._send_state_lock -=1 | ||||
if self._send_state_lock == 0: | ||||
self.send_state(self._states_to_send) | ||||
self._states_to_send.clear() | ||||
|
r14653 | def _should_send_property(self, key, value): | ||
"""Check the property lock (property_lock)""" | ||||
|
r17674 | to_json = self.trait_metadata(key, 'to_json', self._trait_to_json) | ||
if (key == self._property_lock[0] | ||||
and to_json(value) == self._property_lock[1]): | ||||
|
r17623 | return False | ||
elif self._send_state_lock > 0: | ||||
|
r17621 | self._states_to_send.add(key) | ||
return False | ||||
|
r17623 | else: | ||
return True | ||||
|
r14653 | |||
# Event handlers | ||||
|
r15192 | @_show_traceback | ||
|
r14653 | def _handle_msg(self, msg): | ||
"""Called when a msg is received from the front-end""" | ||||
data = msg['content']['data'] | ||||
method = data['method'] | ||||
# Handle backbone sync methods CREATE, PATCH, and UPDATE all in one. | ||||
|
r19350 | if method == 'backbone': | ||
if 'sync_data' in data: | ||||
sync_data = data['sync_data'] | ||||
self.set_state(sync_data) # handles all methods | ||||
# Handle a state request. | ||||
elif method == 'request_state': | ||||
self.send_state() | ||||
|
r14653 | |||
|
r19350 | # Handle a custom msg from the front-end. | ||
|
r14653 | elif method == 'custom': | ||
|
r14655 | if 'content' in data: | ||
self._handle_custom_msg(data['content']) | ||||
|
r14653 | |||
|
r19350 | # Catch remainder. | ||
else: | ||||
self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method) | ||||
|
r14653 | def _handle_custom_msg(self, content): | ||
"""Called when a custom msg is received.""" | ||||
|
r14793 | self._msg_callbacks(self, content) | ||
|
r18506 | |||
|
r17967 | def _notify_trait(self, name, old_value, new_value): | ||
|
r14653 | """Called when a property has been changed.""" | ||
|
r17967 | # Trigger default traitlet callback machinery. This allows any user | ||
# registered validation to be processed prior to allowing the widget | ||||
# machinery to handle the state. | ||||
|
r17994 | LoggingConfigurable._notify_trait(self, name, old_value, new_value) | ||
|
r17967 | |||
# Send the state after the user registered callbacks for trait changes | ||||
# have all fired (allows for user to validate values). | ||||
|
r17994 | if self.comm is not None and name in self.keys: | ||
|
r19350 | # Make sure this isn't information that the front-end just sent us. | ||
|
r17967 | if self._should_send_property(name, new_value): | ||
|
r18509 | # Send new state to front-end | ||
self.send_state(key=name) | ||||
|
r14653 | |||
def _handle_displayed(self, **kwargs): | ||||
"""Called when a view has been displayed for this widget instance""" | ||||
|
r14793 | self._display_callbacks(self, **kwargs) | ||
|
r14653 | |||
|
r17328 | def _trait_to_json(self, x): | ||
"""Convert a trait value to json | ||||
|
r14653 | |||
|
r17237 | Traverse lists/tuples and dicts and serialize their values as well. | ||
Replace any widgets with their model_id | ||||
""" | ||||
|
r14656 | if isinstance(x, dict): | ||
|
r17328 | return {k: self._trait_to_json(v) for k, v in x.items()} | ||
|
r15465 | elif isinstance(x, (list, tuple)): | ||
|
r17328 | return [self._trait_to_json(v) for v in x] | ||
|
r14656 | elif isinstance(x, Widget): | ||
|
r17262 | return "IPY_MODEL_" + x.model_id | ||
|
r14653 | else: | ||
|
r14657 | return x # Value must be JSON-able | ||
|
r14653 | |||
|
r17328 | def _trait_from_json(self, x): | ||
|
r17237 | """Convert json values to objects | ||
|
r14653 | |||
|
r17328 | Replace any strings representing valid model id values to Widget references. | ||
|
r17237 | """ | ||
|
r14656 | if isinstance(x, dict): | ||
|
r17328 | return {k: self._trait_from_json(v) for k, v in x.items()} | ||
|
r15465 | elif isinstance(x, (list, tuple)): | ||
|
r17328 | return [self._trait_from_json(v) for v in x] | ||
|
r17262 | elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets: | ||
|
r17237 | # we want to support having child widgets at any level in a hierarchy | ||
# trusting that a widget UUID will not appear out in the wild | ||||
|
r17733 | return Widget.widgets[x[10:]] | ||
|
r14653 | else: | ||
|
r14656 | return x | ||
|
r14653 | |||
|
r14586 | def _ipython_display_(self, **kwargs): | ||
|
r14607 | """Called when `IPython.display.display` is called on the widget.""" | ||
|
r17989 | # Show view. | ||
if self._view_name is not None: | ||||
self._send({"method": "display"}) | ||||
self._handle_displayed(**kwargs) | ||||
|
r14479 | |||
def _send(self, msg): | ||||
|
r14607 | """Sends a message to the model in the front-end.""" | ||
|
r14548 | self.comm.send(msg) | ||
|
r14516 | |||
|
r14540 | class DOMWidget(Widget): | ||
|
r14793 | visible = Bool(True, help="Whether the widget is visible.", sync=True) | ||
|
r17723 | _css = Tuple(sync=True, help="CSS property list: (selector, key, value)") | ||
_dom_classes = Tuple(sync=True, help="DOM classes applied to widget.$el.") | ||||
|
r17722 | |||
width = CUnicode(sync=True) | ||||
height = CUnicode(sync=True) | ||||
|
r19372 | # A default padding of 2.5 px makes the widgets look nice when displayed inline. | ||
padding = CUnicode("2.5px", sync=True) | ||||
|
r17727 | margin = CUnicode(sync=True) | ||
|
r17722 | |||
|
r17860 | color = Unicode(sync=True) | ||
background_color = Unicode(sync=True) | ||||
|
r17722 | border_color = Unicode(sync=True) | ||
border_width = CUnicode(sync=True) | ||||
|
r17947 | border_radius = CUnicode(sync=True) | ||
|
r17722 | border_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_border-style.asp | ||
'none', | ||||
'hidden', | ||||
'dotted', | ||||
'dashed', | ||||
'solid', | ||||
'double', | ||||
'groove', | ||||
'ridge', | ||||
'inset', | ||||
'outset', | ||||
'initial', | ||||
'inherit', ''], | ||||
default_value='', sync=True) | ||||
font_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_font-style.asp | ||||
'normal', | ||||
'italic', | ||||
'oblique', | ||||
'initial', | ||||
'inherit', ''], | ||||
default_value='', sync=True) | ||||
font_weight = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_weight.asp | ||||
'normal', | ||||
'bold', | ||||
'bolder', | ||||
'lighter', | ||||
'initial', | ||||
'inherit', ''] + [str(100 * (i+1)) for i in range(9)], | ||||
default_value='', sync=True) | ||||
font_size = CUnicode(sync=True) | ||||
font_family = Unicode(sync=True) | ||||
|
r17947 | |||
def __init__(self, *pargs, **kwargs): | ||||
super(DOMWidget, self).__init__(*pargs, **kwargs) | ||||
def _validate_border(name, old, new): | ||||
if new is not None and new != '': | ||||
if name != 'border_width' and not self.border_width: | ||||
self.border_width = 1 | ||||
if name != 'border_style' and self.border_style == '': | ||||
self.border_style = 'solid' | ||||
self.on_trait_change(_validate_border, ['border_width', 'border_style', 'border_color']) | ||||