rename widget to comm

IPython/kernel/comm/comm.py

@@ -0,0 +1,152
+"""Base class for a Comm"""
+
+#-----------------------------------------------------------------------------
+#  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
+#-----------------------------------------------------------------------------
+
+import uuid
+
+from IPython.config import LoggingConfigurable
+from IPython.core.getipython import get_ipython
+
+from IPython.utils.traitlets import Instance, Unicode, Bytes, Bool, Dict, Any
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+class Comm(LoggingConfigurable):
+    
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
+    def _shell_default(self):
+        return get_ipython()
+    iopub_socket = Any()
+    def _iopub_socket_default(self):
+        return self.shell.parent.iopub_socket
+    session = Instance('IPython.kernel.zmq.session.Session')
+    def _session_default(self):
+        if self.shell is None:
+            return
+        return self.shell.parent.session
+    
+    target = Unicode('comm')
+    
+    topic = Bytes()
+    def _topic_default(self):
+        return ('comm-%s' % self.comm_id).encode('ascii')
+    
+    _open_data = Dict(help="data dict, if any, to be included in comm_close")
+    _close_data = Dict(help="data dict, if any, to be included in comm_close")
+    
+    _open_callback = Any()
+    _msg_callback = Any()
+    _close_callback = Any()
+    
+    _closed = Bool(False)
+    comm_id = Unicode()
+    def _comm_id_default(self):
+        return uuid.uuid4().hex
+    
+    primary = Bool(True, help="Am I the primary or secondary Comm?")
+    
+    def __init__(self, **kwargs):
+        super(Comm, self).__init__(**kwargs)
+        get_ipython().comm_manager.register_comm(self)
+        if self.primary:
+            # I am primary, open my peer
+            self.open()
+        else:
+            # I am secondary, handle creation
+            self.handle_open(self._open_data)
+    
+    def _publish_msg(self, msg_type, data=None, **keys):
+        """Helper for sending a comm message on IOPub"""
+        data = {} if data is None else data
+        self.session.send(self.iopub_socket, msg_type,
+            dict(data=data, comm_id=self.comm_id, **keys),
+            ident=self.topic,
+        )
+    
+    def __del__(self):
+        """trigger close on gc"""
+        self.close()
+    
+    # publishing messages
+    
+    def open(self, data=None):
+        """Open the frontend-side version of this comm"""
+        if data is None:
+            data = self._open_data
+        self._publish_msg('comm_open', data, target=self.target)
+    
+    def close(self, data=None):
+        """Close the frontend-side version of this comm"""
+        if self._closed:
+            # only close once
+            return
+        if data is None:
+            data = self._close_data
+        self._publish_msg('comm_close', data)
+        self._closed = True
+    
+    def send(self, data=None):
+        """Update the frontend-side version of this comm"""
+        self._publish_msg('comm_msg', data)
+    
+    # registering callbacks
+    def on_open(self, callback):
+        """Register a callback for comm_open
+        
+        Will be called with the `data` of the open message.
+        
+        Call `on_open(None)` to disable an existing callback.
+        """
+        self._open_callback = callback
+    
+    def on_close(self, callback):
+        """Register a callback for comm_close
+        
+        Will be called with the `data` of the close message.
+        
+        Call `on_close(None)` to disable an existing callback.
+        """
+        self._close_callback = callback
+    
+    def on_msg(self, callback):
+        """Register a callback for comm_msg
+        
+        Will be called with the `data` of any comm_msg messages.
+        
+        Call `on_msg(None)` to disable an existing callback.
+        """
+        self._msg_callback = callback
+    
+    # handling of incoming messages
+    
+    def handle_open(self, data):
+        """Handle a comm_open message"""
+        self.log.debug("handle_open[%s](%s)", self.comm_id, data)
+        if self._open_callback:
+            self._open_callback(data)
+    
+    def handle_close(self, data):
+        """Handle a comm_close message"""
+        self.log.debug("handle_close[%s](%s)", self.comm_id, data)
+        if self._close_callback:
+            self._close_callback(data)
+    
+    def handle_msg(self, data):
+        """Handle a comm_msg message"""
+        self.log.debug("handle_msg[%s](%s)", self.comm_id, data)
+        if self._msg_callback:
+            self._msg_callback(data)
+
+
+__all__ = ['Comm']

IPython/kernel/comm/manager.py

@@ -0,0 +1,142
+"""Base class to manage comms"""
+
+#-----------------------------------------------------------------------------
+#  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 IPython.config import LoggingConfigurable
+from IPython.core.prompts import LazyEvaluate
+from IPython.core.getipython import get_ipython
+
+from IPython.utils.importstring import import_item
+from IPython.utils.traitlets import Instance, Unicode, Dict, Any
+
+from .comm import Comm
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+def lazy_keys(dikt):
+    """Return lazy-evaluated string representation of a dictionary's keys
+    
+    Key list is only constructed if it will actually be used.
+    Used for debug-logging.
+    """
+    return LazyEvaluate(lambda d: list(d.keys()))
+
+
+class CommManager(LoggingConfigurable):
+    """Manager for Comms in the Kernel"""
+    
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
+    def _shell_default(self):
+        return get_ipython()
+    iopub_socket = Any()
+    def _iopub_socket_default(self):
+        return self.shell.parent.iopub_socket
+    session = Instance('IPython.kernel.zmq.session.Session')
+    def _session_default(self):
+        if self.shell is None:
+            return
+        return self.shell.parent.session
+    
+    comms = Dict()
+    targets = Dict()
+    
+    # Public APIs
+    
+    def register_target(self, target, f):
+        """Register a callable f for a given target
+        
+        f will be called with a Comm object as its only argument
+        when a comm_open message is received with `target`.
+        
+        f can be a Python callable or an import string for one.
+        """
+        if isinstance(f, basestring):
+            f = import_item(f)
+        
+        self.targets[target] = f
+    
+    def register_comm(self, comm):
+        """Register a new comm"""
+        comm_id = comm.comm_id
+        comm.shell = self.shell
+        comm.iopub_socket = self.iopub_socket
+        self.comms[comm_id] = comm
+        return comm_id
+    
+    def unregister_comm(self, comm_id):
+        """Unregister a comm, and close its counterpart"""
+        # unlike get_comm, this should raise a KeyError
+        comm = self.comms.pop(comm_id)
+        comm.close()
+    
+    def get_comm(self, comm_id):
+        """Get a comm with a particular id
+        
+        Returns the comm if found, otherwise None.
+        
+        This will not raise an error,
+        it will log messages if the comm cannot be found.
+        """
+        if comm_id not in self.comms:
+            self.log.error("No such comm: %s", comm_id)
+            self.log.debug("Current comms: %s", lazy_keys(self.comms))
+            return
+        # call, because we store weakrefs
+        comm = self.comms[comm_id]
+        return comm
+    
+    # Message handlers
+    
+    def comm_open(self, stream, ident, msg):
+        """Handler for comm_open messages"""
+        content = msg['content']
+        comm_id = content['comm_id']
+        target = content['target']
+        callback = self.targets.get(target, None)
+        comm = Comm(comm_id=comm_id,
+                    shell=self.shell,
+                    iopub_socket=self.iopub_socket,
+                    _open_data=content['data'],
+                    primary=False,
+        )
+        if callback is None:
+            self.log.error("No such comm target registered: %s", target)
+            comm.destroy()
+            return
+        callback(comm)
+        self.register_comm(comm)
+    
+    def comm_msg(self, stream, ident, msg):
+        """Handler for comm_msg messages"""
+        content = msg['content']
+        comm_id = content['comm_id']
+        comm = self.get_comm(comm_id)
+        if comm is None:
+            # no such comm
+            return
+        comm.handle_msg(content['data'])
+    
+    def comm_close(self, stream, ident, msg):
+        """Handler for comm_close messages"""
+        content = msg['content']
+        comm_id = content['comm_id']
+        comm = self.get_comm(comm_id)
+        if comm is None:
+            # no such comm
+            return
+        comm.handle_close(content['data'])
+        del self.comms[comm_id]
+
+
+__all__ = ['CommManager']

IPython/html/static/notebook/js/comm.js

@@ -6,141 +6,143
 //----------------------------------------------------------------------------
 
 //============================================================================
-// Widget and WidgetManager bases
+// Comm and CommManager bases
 //============================================================================
 /**
- * Base Widget classes
+ * Base Comm classes
  * @module IPython
  * @namespace IPython
- * @submodule widget
+ * @submodule comm
  */
 
 var IPython = (function (IPython) {
     "use strict";
 
     //-----------------------------------------------------------------------
-    // WidgetManager class
+    // CommManager class
     //-----------------------------------------------------------------------
     
-    var WidgetManager = function (kernel) {
-        this.widgets = {};
-        this.widget_types = {widget : Widget};
+    var CommManager = function (kernel) {
+        this.comms = {};
+        this.targets = {comm : Comm};
         if (kernel !== undefined) {
             this.init_kernel(kernel);
         }
     };
     
-    WidgetManager.prototype.init_kernel = function (kernel) {
+    CommManager.prototype.init_kernel = function (kernel) {
         // connect the kernel, and register message handlers
         this.kernel = kernel;
-        var msg_types = ['widget_create', 'widget_destroy', 'widget_update'];
+        var msg_types = ['comm_open', 'comm_msg', 'comm_close'];
         for (var i = 0; i < msg_types.length; i++) {
             var msg_type = msg_types[i];
             kernel.register_iopub_handler(msg_type, $.proxy(this[msg_type], this));
         }
     };
     
-    WidgetManager.prototype.register_widget_type = function (widget_type, constructor) {
-        // Register a constructor for a given widget type name
-        this.widget_types[widget_type] = constructor;
+    CommManager.prototype.register_target = function (target, constructor) {
+        // Register a constructor for a given target key
+        this.targets[target] = constructor;
     };
     
-    WidgetManager.prototype.register_widget = function (widget) {
-        // Register a widget in the mapping
-        this.widgets[widget.widget_id] = widget;
-        widget.kernel = this.kernel;
-        return widget.widget_id;
+    CommManager.prototype.register_comm = function (comm) {
+        // Register a comm in the mapping
+        this.comms[comm.comm_id] = comm;
+        comm.kernel = this.kernel;
+        return comm.comm_id;
     };
     
-    WidgetManager.prototype.unregister_widget = function (widget_id) {
-        // Remove a widget from the mapping
-        delete this.widgets[widget_id];
+    CommManager.prototype.unregister_comm = function (comm_id) {
+        // Remove a comm from the mapping
+        delete this.comms[comm_id];
     };
     
-    // widget message handlers
+    // comm message handlers
     
-    WidgetManager.prototype.widget_create = function (msg) {
+    CommManager.prototype.comm_open = function (msg) {
         var content = msg.content;
-        var constructor = this.widget_types[content.widget_type];
-        if (constructor === undefined) {
-            console.log("No such widget type registered: ", content.widget_type);
-            console.log("Available widget types are: ", this.widget_types);
+        var callback = this.targets[content.target];
+        if (callback === undefined) {
+            console.log("No such target registered: ", content.target);
+            console.log("Available targets are: ", this.targets);
             return;
         }
-        var widget = new constructor(content.widget_id);
-        this.register_widget(widget);
-        widget.handle_create(content.data);
-        
-        this.widgets[content.widget_id] = widget;
+        var comm = new Comm(content.comm_id);
+        this.register_comm(comm);
+        callback(comm);
+        comm.handle_open(content.data);
     };
     
-    WidgetManager.prototype.widget_destroy = function (msg) {
+    CommManager.prototype.comm_close = function (msg) {
         var content = msg.content;
-        var widget = this.widgets[content.widget_id];
-        if (widget === undefined) {
+        var comm = this.comms[content.comm_id];
+        if (comm === undefined) {
             return;
         }
-        delete this.widgets[content.widget_id];
-        widget.handle_destroy(content.data);
+        delete this.comms[content.comm_id];
+        comm.handle_close(content.data);
     };
     
-    WidgetManager.prototype.widget_update = function (msg) {
+    CommManager.prototype.comm_msg = function (msg) {
         var content = msg.content;
-        var widget = this.widgets[content.widget_id];
-        if (widget === undefined) {
+        var comm = this.comms[content.comm_id];
+        if (comm === undefined) {
             return;
         }
-        widget.handle_update(content.data);
+        comm.handle_msg(content.data);
     };
     
     //-----------------------------------------------------------------------
-    // Widget base class
+    // Comm base class
     //-----------------------------------------------------------------------
     
-    var Widget = function (widget_id) {
-        this.widget_id = widget_id;
-        this.widget_type = 'widget';
+    var Comm = function (comm_id) {
+        this.comm_id = comm_id;
+        this.target = 'comm';
     };
     
     // methods for sending messages
-    Widget.prototype.create = function (data) {
+    Comm.prototype.open = function (data) {
         var content = {
-            widget_id : this.widget_id,
-            widget_type : this.widget_type,
+            comm_id : this.comm_id,
+            target : this.target,
             data : data || {},
         };
-        this.kernel.send_shell_message("widget_create", content);
+        this.kernel.send_shell_message("comm_open", content);
     };
     
-    Widget.prototype.update = function (data) {
+    Comm.prototype.send = function (data) {
         var content = {
-            widget_id : this.widget_id,
+            comm_id : this.comm_id,
             data : data || {},
         };
-        this.kernel.send_shell_message("widget_update", content);
+        return this.kernel.send_shell_message("comm_msg", content);
     };
     
-    Widget.prototype.destroy = function (data) {
+    Comm.prototype.close = function (data) {
         var content = {
-            widget_id : this.widget_id,
+            comm_id : this.comm_id,
             data : data || {},
         };
-        this.kernel.send_shell_message("widget_destroy", content);
+        return this.kernel.send_shell_message("comm_close", content);
     };
     
     // methods for handling incoming messages
     
-    Widget.prototype.handle_create = function (data) {
+    Comm.prototype.handle_open = function (data) {
+        $([this]).trigger("comm_open", data);
     };
     
-    Widget.prototype.handle_update = function (data) {
+    Comm.prototype.handle_msg = function (data) {
+        $([this]).trigger("comm_msg", data);
     };
     
-    Widget.prototype.handle_destroy = function (data) {
+    Comm.prototype.handle_close = function (data) {
+        $([this]).trigger("comm_close", data);
     };
     
-    IPython.WidgetManager = WidgetManager;
-    IPython.Widget = Widget;
+    IPython.CommManager = CommManager;
+    IPython.Comm = Comm;
 
     return IPython;
 

IPython/html/static/notebook/js/main.js

@@ -68,7 +68,7 function (marked) {
     IPython.tooltip = new IPython.Tooltip()
     IPython.notification_area = new IPython.NotificationArea('#notification_area')
     IPython.notification_area.init_notification_widgets();
-    IPython.widget_manager = new IPython.WidgetManager();
+    IPython.comm_manager = new IPython.CommManager();
 
     IPython.layout_manager.do_resize();
 
@@ -95,7 +95,7 function (marked) {
         }
         IPython.notebook.set_autosave_interval(IPython.notebook.minimum_autosave_interval);
         // only do this once
-        IPython.widget_manager.init_kernel(IPython.notebook.kernel);
+        IPython.comm_manager.init_kernel(IPython.notebook.kernel);
         $([IPython.events]).off('notebook_loaded.Notebook', first_load);
     };
     

IPython/html/templates/notebook.html

@@ -253,7 +253,7 class="notebook_app"
 <script src="{{ static_url("notebook/js/notificationarea.js") }}" type="text/javascript" charset="utf-8"></script>
 <script src="{{ static_url("notebook/js/tooltip.js") }}" type="text/javascript" charset="utf-8"></script>
 <script src="{{ static_url("notebook/js/config.js") }}" type="text/javascript" charset="utf-8"></script>
-<script src="{{ static_url("notebook/js/widget.js") }}" type="text/javascript" charset="utf-8"></script>
+<script src="{{ static_url("notebook/js/comm.js") }}" type="text/javascript" charset="utf-8"></script>
 <script src="{{ static_url("notebook/js/main.js") }}" type="text/javascript" charset="utf-8"></script>
 
 <script src="{{ static_url("notebook/js/contexthint.js") }}" charset="utf-8"></script>

IPython/kernel/comm/__init__.py

@@ -1,2 +1,2
 from .manager import *
-from .widget import *
+from .comm import *

IPython/kernel/zmq/ipkernel.py

@@ -168,10 +168,10 class Kernel(Configurable):
         for msg_type in msg_types:
             self.shell_handlers[msg_type] = getattr(self, msg_type)
         
-        widget_msg_types = [ 'widget_create', 'widget_update', 'widget_destroy' ]
-        widget_manager = self.shell.widget_manager
-        for msg_type in widget_msg_types:
-            self.shell_handlers[msg_type] = getattr(widget_manager, msg_type)
+        comm_msg_types = [ 'comm_open', 'comm_msg', 'comm_close' ]
+        comm_manager = self.shell.comm_manager
+        for msg_type in comm_msg_types:
+            self.shell_handlers[msg_type] = getattr(comm_manager, msg_type)
         
         control_msg_types = msg_types + [ 'clear_request', 'abort_request' ]
         self.control_handlers = {}

IPython/kernel/zmq/zmqshell.py

@@ -49,7 +49,7 from IPython.utils.warn import error
 from IPython.kernel.zmq.displayhook import ZMQShellDisplayHook
 from IPython.kernel.zmq.datapub import ZMQDataPublisher
 from IPython.kernel.zmq.session import extract_header
-from IPython.kernel.widgets import WidgetManager
+from IPython.kernel.comm import CommManager
 from session import Session
 
 #-----------------------------------------------------------------------------
@@ -596,8 +596,8 class ZMQInteractiveShell(InteractiveShell):
         self.magics_manager.register_alias('ed', 'edit')
     
     def init_widgets(self):
-        self.widget_manager = WidgetManager(shell=self, parent=self)
-        self.configurables.append(self.widget_manager)
+        self.comm_manager = CommManager(shell=self, parent=self)
+        self.configurables.append(self.comm_manager)
 
 
 InteractiveShellABC.register(ZMQInteractiveShell)