Merge pull request #6945 from minrk/kernel-info-lang

fix loading of language name from kernel_info

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

@@ -1,2510 +1,2508
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
     'notebook/js/cell',
     'notebook/js/textcell',
     'notebook/js/codecell',
     'services/sessions/session',
     'notebook/js/celltoolbar',
     'components/marked/lib/marked',
     'codemirror/lib/codemirror',
     'codemirror/addon/runmode/runmode',
     'notebook/js/mathjaxutils',
     'base/js/keyboard',
     'notebook/js/tooltip',
     'notebook/js/celltoolbarpresets/default',
     'notebook/js/celltoolbarpresets/rawcell',
     'notebook/js/celltoolbarpresets/slideshow',
     'notebook/js/scrollmanager'
 ], function (
     IPython, 
     $,
     utils,
     dialog,
     cellmod,
     textcell,
     codecell,
     session, 
     celltoolbar,
     marked,
     CodeMirror,
     runMode,
     mathjaxutils,
     keyboard,
     tooltip,
     default_celltoolbar,
     rawcell_celltoolbar,
     slideshow_celltoolbar,
     scrollmanager
     ) {
     "use strict";
 
     var Notebook = function (selector, options) {
         // Constructor
         //
         // A notebook contains and manages cells.
         //
         // Parameters:
         //  selector: string
         //  options: dictionary
         //      Dictionary of keyword arguments.
         //          events: $(Events) instance
         //          keyboard_manager: KeyboardManager instance
         //          contents: Contents instance
         //          save_widget: SaveWidget instance
         //          config: dictionary
         //          base_url : string
         //          notebook_path : string
         //          notebook_name : string
         this.config = utils.mergeopt(Notebook, options.config);
         this.base_url = options.base_url;
         this.notebook_path = options.notebook_path;
         this.notebook_name = options.notebook_name;
         this.events = options.events;
         this.keyboard_manager = options.keyboard_manager;
         this.contents = options.contents;
         this.save_widget = options.save_widget;
         this.tooltip = new tooltip.Tooltip(this.events);
         this.ws_url = options.ws_url;
         this._session_starting = false;
         this.default_cell_type = this.config.default_cell_type || 'code';
 
         //  Create default scroll manager.
         this.scroll_manager = new scrollmanager.ScrollManager(this);
 
         // TODO: This code smells (and the other `= this` line a couple lines down)
         // We need a better way to deal with circular instance references.
         this.keyboard_manager.notebook = this;
         this.save_widget.notebook = this;
         
         mathjaxutils.init();
 
         if (marked) {
             marked.setOptions({
                 gfm : true,
                 tables: true,
                 // FIXME: probably want central config for CodeMirror theme when we have js config
                 langPrefix: "cm-s-ipython language-",
                 highlight: function(code, lang, callback) {
                     if (!lang) {
                         // no language, no highlight
                         if (callback) {
                             callback(null, code);
                             return;
                         } else {
                             return code;
                         }
                     }
                     utils.requireCodeMirrorMode(lang, function () {
                         var el = document.createElement("div");
                         var mode = CodeMirror.getMode({}, lang);
                         if (!mode) {
                             console.log("No CodeMirror mode: " + lang);
                             callback(null, code);
                             return;
                         }
                         try {
                             CodeMirror.runMode(code, mode, el);
                             callback(null, el.innerHTML);
                         } catch (err) {
                             console.log("Failed to highlight " + lang + " code", err);
                             callback(err, code);
                         }
                     }, function (err) {
                         console.log("No CodeMirror mode: " + lang);
                         callback(err, code);
                     });
                 }
             });
         }
 
         this.element = $(selector);
         this.element.scroll();
         this.element.data("notebook", this);
         this.next_prompt_number = 1;
         this.session = null;
         this.kernel = null;
         this.clipboard = null;
         this.undelete_backup = null;
         this.undelete_index = null;
         this.undelete_below = false;
         this.paste_enabled = false;
         this.writable = false;
         // It is important to start out in command mode to match the intial mode
         // of the KeyboardManager.
         this.mode = 'command';
         this.set_dirty(false);
         this.metadata = {};
         this._checkpoint_after_save = false;
         this.last_checkpoint = null;
         this.checkpoints = [];
         this.autosave_interval = 0;
         this.autosave_timer = null;
         // autosave *at most* every two minutes
         this.minimum_autosave_interval = 120000;
         this.notebook_name_blacklist_re = /[\/\\:]/;
         this.nbformat = 4; // Increment this when changing the nbformat
         this.nbformat_minor = this.current_nbformat_minor = 0; // Increment this when changing the nbformat
         this.codemirror_mode = 'ipython';
         this.create_elements();
         this.bind_events();
         this.kernel_selector = null;
         this.dirty = null;
         this.trusted = null;
         this._fully_loaded = false;
 
         // Trigger cell toolbar registration.
         default_celltoolbar.register(this);
         rawcell_celltoolbar.register(this);
         slideshow_celltoolbar.register(this);
 
         // prevent assign to miss-typed properties.
         Object.seal(this);
     };
 
     Notebook.options_default = {
         // can be any cell type, or the special values of
         // 'above', 'below', or 'selected' to get the value from another cell.
         Notebook: {
             default_cell_type: 'code'
         }
     };
 
 
     /**
      * Create an HTML and CSS representation of the notebook.
      * 
      * @method create_elements
      */
     Notebook.prototype.create_elements = function () {
         var that = this;
         this.element.attr('tabindex','-1');
         this.container = $("<div/>").addClass("container").attr("id", "notebook-container");
         // We add this end_space div to the end of the notebook div to:
         // i) provide a margin between the last cell and the end of the notebook
         // ii) to prevent the div from scrolling up when the last cell is being
         // edited, but is too low on the page, which browsers will do automatically.
         var end_space = $('<div/>').addClass('end_space');
         end_space.dblclick(function (e) {
             var ncells = that.ncells();
             that.insert_cell_below('code',ncells-1);
         });
         this.element.append(this.container);
         this.container.append(end_space);
     };
 
     /**
      * Bind JavaScript events: key presses and custom IPython events.
      * 
      * @method bind_events
      */
     Notebook.prototype.bind_events = function () {
         var that = this;
 
         this.events.on('set_next_input.Notebook', function (event, data) {
             var index = that.find_cell_index(data.cell);
             var new_cell = that.insert_cell_below('code',index);
             new_cell.set_text(data.text);
             that.dirty = true;
         });
 
         this.events.on('unrecognized_cell.Cell', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('unrecognized_output.OutputArea', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('set_dirty.Notebook', function (event, data) {
             that.dirty = data.value;
         });
 
         this.events.on('trust_changed.Notebook', function (event, trusted) {
             that.trusted = trusted;
         });
 
         this.events.on('select.Cell', function (event, data) {
             var index = that.find_cell_index(data.cell);
             that.select(index);
         });
 
         this.events.on('edit_mode.Cell', function (event, data) {
             that.handle_edit_mode(data.cell);
         });
 
         this.events.on('command_mode.Cell', function (event, data) {
             that.handle_command_mode(data.cell);
         });
         
         this.events.on('spec_changed.Kernel', function(event, data) {
             that.metadata.kernelspec = 
                 {name: data.name, display_name: data.display_name};
         });
 
         this.events.on('kernel_ready.Kernel', function(event, data) {
             var kinfo = data.kernel.info_reply;
             var langinfo = kinfo.language_info || {};
-            if (!langinfo.name)  langinfo.name = kinfo.language;
-                
             that.metadata.language_info = langinfo;
             // Mode 'null' should be plain, unhighlighted text.
-            var cm_mode = langinfo.codemirror_mode || langinfo.language || 'null';
+            var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             that.set_codemirror_mode(cm_mode);
         });
 
         var collapse_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var new_height = app_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('collapse_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             collapse_time(time);
         });
 
         var expand_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var pager_height = $('div#pager').outerHeight(true);
             var new_height = app_height - pager_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('expand_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             expand_time(time);
         });
         
         // Firefox 22 broke $(window).on("beforeunload")
         // I'm not sure why or how.
         window.onbeforeunload = function (e) {
             // TODO: Make killing the kernel configurable.
             var kill_kernel = false;
             if (kill_kernel) {
                 that.session.delete();
             }
             // if we are autosaving, trigger an autosave on nav-away.
             // still warn, because if we don't the autosave may fail.
             if (that.dirty) {
                 if ( that.autosave_interval ) {
                     // schedule autosave in a timeout
                     // this gives you a chance to forcefully discard changes
                     // by reloading the page if you *really* want to.
                     // the timer doesn't start until you *dismiss* the dialog.
                     setTimeout(function () {
                         if (that.dirty) {
                             that.save_notebook();
                         }
                     }, 1000);
                     return "Autosave in progress, latest changes may be lost.";
                 } else {
                     return "Unsaved changes will be lost.";
                 }
             }
             // Null is the *only* return value that will make the browser not
             // pop up the "don't leave" dialog.
             return null;
         };
     };
     
     Notebook.prototype.warn_nbformat_minor = function (event) {
         // trigger a warning dialog about missing functionality from newer minor versions
         var v = 'v' + this.nbformat + '.';
         var orig_vs = v + this.nbformat_minor;
         var this_vs = v + this.current_nbformat_minor;
         var msg = "This notebook is version " + orig_vs + ", but we only fully support up to " +
         this_vs + ".  You can still work with this notebook, but cell and output types " +
         "introduced in later notebook versions will not be available.";
 
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Newer Notebook",
             body : msg,
             buttons : {
                 OK : {
                     "class" : "btn-danger"
                 }
             }
         });
     }
 
     /**
      * Set the dirty flag, and trigger the set_dirty.Notebook event
      * 
      * @method set_dirty
      */
     Notebook.prototype.set_dirty = function (value) {
         if (value === undefined) {
             value = true;
         }
         if (this.dirty == value) {
             return;
         }
         this.events.trigger('set_dirty.Notebook', {value: value});
     };
 
     /**
      * Scroll the top of the page to a given cell.
      * 
      * @method scroll_to_cell
      * @param {Number} cell_number An index of the cell to view
      * @param {Number} time Animation time in milliseconds
      * @return {Number} Pixel offset from the top of the container
      */
     Notebook.prototype.scroll_to_cell = function (cell_number, time) {
         var cells = this.get_cells();
         time = time || 0;
         cell_number = Math.min(cells.length-1,cell_number);
         cell_number = Math.max(0             ,cell_number);
         var scroll_value = cells[cell_number].element.position().top-cells[0].element.position().top ;
         this.element.animate({scrollTop:scroll_value}, time);
         return scroll_value;
     };
 
     /**
      * Scroll to the bottom of the page.
      * 
      * @method scroll_to_bottom
      */
     Notebook.prototype.scroll_to_bottom = function () {
         this.element.animate({scrollTop:this.element.get(0).scrollHeight}, 0);
     };
 
     /**
      * Scroll to the top of the page.
      * 
      * @method scroll_to_top
      */
     Notebook.prototype.scroll_to_top = function () {
         this.element.animate({scrollTop:0}, 0);
     };
 
     // Edit Notebook metadata
 
     Notebook.prototype.edit_metadata = function () {
         var that = this;
         dialog.edit_metadata({
             md: this.metadata, 
             callback: function (md) {
                 that.metadata = md;
             },
             name: 'Notebook',
             notebook: this,
             keyboard_manager: this.keyboard_manager});
     };
 
     // Cell indexing, retrieval, etc.
 
     /**
      * Get all cell elements in the notebook.
      * 
      * @method get_cell_elements
      * @return {jQuery} A selector of all cell elements
      */
     Notebook.prototype.get_cell_elements = function () {
         return this.container.find(".cell").not('.cell .cell');
     };
 
     /**
      * Get a particular cell element.
      * 
      * @method get_cell_element
      * @param {Number} index An index of a cell to select
      * @return {jQuery} A selector of the given cell.
      */
     Notebook.prototype.get_cell_element = function (index) {
         var result = null;
         var e = this.get_cell_elements().eq(index);
         if (e.length !== 0) {
             result = e;
         }
         return result;
     };
 
     /**
      * Try to get a particular cell by msg_id.
      * 
      * @method get_msg_cell
      * @param {String} msg_id A message UUID
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_msg_cell = function (msg_id) {
         return codecell.CodeCell.msg_cells[msg_id] || null;
     };
 
     /**
      * Count the cells in this notebook.
      * 
      * @method ncells
      * @return {Number} The number of cells in this notebook
      */
     Notebook.prototype.ncells = function () {
         return this.get_cell_elements().length;
     };
 
     /**
      * Get all Cell objects in this notebook.
      * 
      * @method get_cells
      * @return {Array} This notebook's Cell objects
      */
     // TODO: we are often calling cells as cells()[i], which we should optimize
     // to cells(i) or a new method.
     Notebook.prototype.get_cells = function () {
         return this.get_cell_elements().toArray().map(function (e) {
             return $(e).data("cell");
         });
     };
 
     /**
      * Get a Cell object from this notebook.
      * 
      * @method get_cell
      * @param {Number} index An index of a cell to retrieve
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_cell = function (index) {
         var result = null;
         var ce = this.get_cell_element(index);
         if (ce !== null) {
             result = ce.data('cell');
         }
         return result;
     };
 
     /**
      * Get the cell below a given cell.
      * 
      * @method get_next_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} the next cell or null if no cell was found.
      */
     Notebook.prototype.get_next_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (this.is_valid_cell_index(index+1)) {
             result = this.get_cell(index+1);
         }
         return result;
     };
 
     /**
      * Get the cell above a given cell.
      * 
      * @method get_prev_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} The previous cell or null if no cell was found.
      */
     Notebook.prototype.get_prev_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (index !== null && index > 0) {
             result = this.get_cell(index-1);
         }
         return result;
     };
     
     /**
      * Get the numeric index of a given cell.
      * 
      * @method find_cell_index
      * @param {Cell} cell The provided cell
      * @return {Number} The cell's numeric index or null if no cell was found.
      */
     Notebook.prototype.find_cell_index = function (cell) {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell") === cell) {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Get a given index , or the selected index if none is provided.
      * 
      * @method index_or_selected
      * @param {Number} index A cell's index
      * @return {Number} The given index, or selected index if none is provided.
      */
     Notebook.prototype.index_or_selected = function (index) {
         var i;
         if (index === undefined || index === null) {
             i = this.get_selected_index();
             if (i === null) {
                 i = 0;
             }
         } else {
             i = index;
         }
         return i;
     };
 
     /**
      * Get the currently selected cell.
      * @method get_selected_cell
      * @return {Cell} The selected cell
      */
     Notebook.prototype.get_selected_cell = function () {
         var index = this.get_selected_index();
         return this.get_cell(index);
     };
 
     /**
      * Check whether a cell index is valid.
      * 
      * @method is_valid_cell_index
      * @param {Number} index A cell index
      * @return True if the index is valid, false otherwise
      */
     Notebook.prototype.is_valid_cell_index = function (index) {
         if (index !== null && index >= 0 && index < this.ncells()) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Get the index of the currently selected cell.
      
      * @method get_selected_index
      * @return {Number} The selected cell's numeric index
      */
     Notebook.prototype.get_selected_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").selected === true) {
                 result = index;
             }
         });
         return result;
     };
 
 
     // Cell selection.
 
     /**
      * Programmatically select a cell.
      * 
      * @method select
      * @param {Number} index A cell's index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select = function (index) {
         if (this.is_valid_cell_index(index)) {
             var sindex = this.get_selected_index();
             if (sindex !== null && index !== sindex) {
                 // If we are about to select a different cell, make sure we are
                 // first in command mode.
                 if (this.mode !== 'command') {
                     this.command_mode();
                 }
                 this.get_cell(sindex).unselect();
             }
             var cell = this.get_cell(index);
             cell.select();
             if (cell.cell_type === 'heading') {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type,level:cell.level}
                 );
             } else {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type}
                 );
             }
         }
         return this;
     };
 
     /**
      * Programmatically select the next cell.
      *
      * @method select_next
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_next = function () {
         var index = this.get_selected_index();
         this.select(index+1);
         return this;
     };
 
     /**
      * Programmatically select the previous cell.
      *
      * @method select_prev
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_prev = function () {
         var index = this.get_selected_index();
         this.select(index-1);
         return this;
     };
 
 
     // Edit/Command mode
 
     /**
      * Gets the index of the cell that is in edit mode.
      *
      * @method get_edit_index
      *
      * @return index {int}
      **/
     Notebook.prototype.get_edit_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").mode === 'edit') {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Handle when a a cell blurs and the notebook should enter command mode.
      *
      * @method handle_command_mode
      * @param [cell] {Cell} Cell to enter command mode on.
      **/
     Notebook.prototype.handle_command_mode = function (cell) {
         if (this.mode !== 'command') {
             cell.command_mode();
             this.mode = 'command';
             this.events.trigger('command_mode.Notebook');
             this.keyboard_manager.command_mode();
         }
     };
 
     /**
      * Make the notebook enter command mode.
      *
      * @method command_mode
      **/
     Notebook.prototype.command_mode = function () {
         var cell = this.get_cell(this.get_edit_index());
         if (cell && this.mode !== 'command') {
             // We don't call cell.command_mode, but rather call cell.focus_cell()
             // which will blur and CM editor and trigger the call to
             // handle_command_mode.
             cell.focus_cell();
         }
     };
 
     /**
      * Handle when a cell fires it's edit_mode event.
      *
      * @method handle_edit_mode
      * @param [cell] {Cell} Cell to enter edit mode on.
      **/
     Notebook.prototype.handle_edit_mode = function (cell) {
         if (cell && this.mode !== 'edit') {
             cell.edit_mode();
             this.mode = 'edit';
             this.events.trigger('edit_mode.Notebook');
             this.keyboard_manager.edit_mode();
         }
     };
 
     /**
      * Make a cell enter edit mode.
      *
      * @method edit_mode
      **/
     Notebook.prototype.edit_mode = function () {
         var cell = this.get_selected_cell();
         if (cell && this.mode !== 'edit') {
             cell.unrender();
             cell.focus_editor();
         }
     };
 
     /**
      * Focus the currently selected cell.
      *
      * @method focus_cell
      **/
     Notebook.prototype.focus_cell = function () {
         var cell = this.get_selected_cell();
         if (cell === null) {return;}  // No cell is selected
         cell.focus_cell();
     };
 
     // Cell movement
 
     /**
      * Move given (or selected) cell up and select it.
      * 
      * @method move_cell_up
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_up = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && i > 0) {
             var pivot = this.get_cell_element(i-1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.before(tomove);
                 this.select(i-1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
             this.set_dirty(true);
         }
         return this;
     };
 
 
     /**
      * Move given (or selected) cell down and select it
      * 
      * @method move_cell_down
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_down = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && this.is_valid_cell_index(i+1)) {
             var pivot = this.get_cell_element(i+1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.after(tomove);
                 this.select(i+1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
         }
         this.set_dirty();
         return this;
     };
 
 
     // Insertion, deletion.
 
     /**
      * Delete a cell from the notebook.
      * 
      * @method delete_cell
      * @param [index] A cell's numeric index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.delete_cell = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (!cell.is_deletable()) {
             return this;
         }
 
         this.undelete_backup = cell.toJSON();
         $('#undelete_cell').removeClass('disabled');
         if (this.is_valid_cell_index(i)) {
             var old_ncells = this.ncells();
             var ce = this.get_cell_element(i);
             ce.remove();
             if (i === 0) {
                 // Always make sure we have at least one cell.
                 if (old_ncells === 1) {
                     this.insert_cell_below('code');
                 }
                 this.select(0);
                 this.undelete_index = 0;
                 this.undelete_below = false;
             } else if (i === old_ncells-1 && i !== 0) {
                 this.select(i-1);
                 this.undelete_index = i - 1;
                 this.undelete_below = true;
             } else {
                 this.select(i);
                 this.undelete_index = i;
                 this.undelete_below = false;
             }
             this.events.trigger('delete.Cell', {'cell': cell, 'index': i});
             this.set_dirty(true);
         }
         return this;
     };
 
     /**
      * Restore the most recently deleted cell.
      * 
      * @method undelete
      */
     Notebook.prototype.undelete_cell = function() {
         if (this.undelete_backup !== null && this.undelete_index !== null) {
             var current_index = this.get_selected_index();
             if (this.undelete_index < current_index) {
                 current_index = current_index + 1;
             }
             if (this.undelete_index >= this.ncells()) {
                 this.select(this.ncells() - 1);
             }
             else {
                 this.select(this.undelete_index);
             }
             var cell_data = this.undelete_backup;
             var new_cell = null;
             if (this.undelete_below) {
                 new_cell = this.insert_cell_below(cell_data.cell_type);
             } else {
                 new_cell = this.insert_cell_above(cell_data.cell_type);
             }
             new_cell.fromJSON(cell_data);
             if (this.undelete_below) {
                 this.select(current_index+1);
             } else {
                 this.select(current_index);
             }
             this.undelete_backup = null;
             this.undelete_index = null;
         }
         $('#undelete_cell').addClass('disabled');
     };
 
     /**
      * Insert a cell so that after insertion the cell is at given index.
      *
      * If cell type is not provided, it will default to the type of the
      * currently active cell.
      *
      * Similar to insert_above, but index parameter is mandatory
      *
      * Index will be brought back into the accessible range [0,n]
      *
      * @method insert_cell_at_index
      * @param [type] {string} in ['code','markdown', 'raw'], defaults to 'code'
      * @param [index] {int} a valid index where to insert cell
      *
      * @return cell {cell|null} created cell or null
      **/
     Notebook.prototype.insert_cell_at_index = function(type, index){
 
         var ncells = this.ncells();
         index = Math.min(index, ncells);
         index = Math.max(index, 0);
         var cell = null;
         type = type || this.default_cell_type;
         if (type === 'above') {
             if (index > 0) {
                 type = this.get_cell(index-1).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'below') {
             if (index < ncells) {
                 type = this.get_cell(index).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'selected') {
             type = this.get_selected_cell().cell_type;
         }
 
         if (ncells === 0 || this.is_valid_cell_index(index) || index === ncells) {
             var cell_options = {
                 events: this.events, 
                 config: this.config, 
                 keyboard_manager: this.keyboard_manager, 
                 notebook: this,
                 tooltip: this.tooltip
             };
             switch(type) {
             case 'code':
                 cell = new codecell.CodeCell(this.kernel, cell_options);
                 cell.set_input_prompt();
                 break;
             case 'markdown':
                 cell = new textcell.MarkdownCell(cell_options);
                 break;
             case 'raw':
                 cell = new textcell.RawCell(cell_options);
                 break;
             default:
                 console.log("Unrecognized cell type: ", type, cellmod);
                 cell = new cellmod.UnrecognizedCell(cell_options);
             }
 
             if(this._insert_element_at_index(cell.element,index)) {
                 cell.render();
                 this.events.trigger('create.Cell', {'cell': cell, 'index': index});
                 cell.refresh();
                 // We used to select the cell after we refresh it, but there
                 // are now cases were this method is called where select is
                 // not appropriate. The selection logic should be handled by the
                 // caller of the the top level insert_cell methods.
                 this.set_dirty(true);
             }
         }
         return cell;
 
     };
 
     /**
      * Insert an element at given cell index.
      *
      * @method _insert_element_at_index
      * @param element {dom_element} a cell element
      * @param [index] {int} a valid index where to inser cell
      * @private
      *
      * return true if everything whent fine.
      **/
     Notebook.prototype._insert_element_at_index = function(element, index){
         if (element === undefined){
             return false;
         }
 
         var ncells = this.ncells();
 
         if (ncells === 0) {
             // special case append if empty
             this.element.find('div.end_space').before(element);
         } else if ( ncells === index ) {
             // special case append it the end, but not empty
             this.get_cell_element(index-1).after(element);
         } else if (this.is_valid_cell_index(index)) {
             // otherwise always somewhere to append to
             this.get_cell_element(index).before(element);
         } else {
             return false;
         }
 
         if (this.undelete_index !== null && index <= this.undelete_index) {
             this.undelete_index = this.undelete_index + 1;
             this.set_dirty(true);
         }
         return true;
     };
 
     /**
      * Insert a cell of given type above given index, or at top
      * of notebook if index smaller than 0.
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_above
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      **/
     Notebook.prototype.insert_cell_above = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index);
     };
 
     /**
      * Insert a cell of given type below given index, or at bottom
      * of notebook if index greater than number of cells
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_below
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      *
      **/
     Notebook.prototype.insert_cell_below = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index+1);
     };
 
 
     /**
      * Insert cell at end of notebook
      *
      * @method insert_cell_at_bottom
      * @param {String} type cell type
      *
      * @return the added cell; or null
      **/
     Notebook.prototype.insert_cell_at_bottom = function (type){
         var len = this.ncells();
         return this.insert_cell_below(type,len-1);
     };
 
     /**
      * Turn a cell into a code cell.
      * 
      * @method to_code
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_code = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
             if (!(source_cell instanceof codecell.CodeCell)) {
                 var target_cell = this.insert_cell_below('code',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
 
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a Markdown cell.
      * 
      * @method to_markdown
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_markdown = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.MarkdownCell)) {
                 var target_cell = this.insert_cell_below('markdown',i);
                 var text = source_cell.get_text();
 
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 // metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
                     target_cell.render();
                 }
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a raw text cell.
      * 
      * @method to_raw
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_raw = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var target_cell = null;
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.RawCell)) {
                 target_cell = this.insert_cell_below('raw',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
     
     Notebook.prototype._warn_heading = function () {
         // warn about heading cells being removed
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Use markdown headings",
             body : $("<p/>").text(
                 'IPython no longer uses special heading cells. ' + 
                 'Instead, write your headings in Markdown cells using # characters:'
             ).append($('<pre/>').text(
                 '## This is a level 2 heading'
             )),
             buttons : {
                 "OK" : {}
             }
         });
     };
     
     /**
      * Turn a cell into a markdown cell with a heading.
      * 
      * @method to_heading
      * @param {Number} [index] A cell's index
      * @param {Number} [level] A heading level (e.g., 1 for h1)
      */
     Notebook.prototype.to_heading = function (index, level) {
         this.to_markdown(index);
         level = level || 1;
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var cell = this.get_cell(i);
             cell.set_heading_level(level);
             this.set_dirty(true);
         }
     };
 
 
     // Cut/Copy/Paste
 
     /**
      * Enable UI elements for pasting cells.
      * 
      * @method enable_paste
      */
     Notebook.prototype.enable_paste = function () {
         var that = this;
         if (!this.paste_enabled) {
             $('#paste_cell_replace').removeClass('disabled')
                 .on('click', function () {that.paste_cell_replace();});
             $('#paste_cell_above').removeClass('disabled')
                 .on('click', function () {that.paste_cell_above();});
             $('#paste_cell_below').removeClass('disabled')
                 .on('click', function () {that.paste_cell_below();});
             this.paste_enabled = true;
         }
     };
 
     /**
      * Disable UI elements for pasting cells.
      * 
      * @method disable_paste
      */
     Notebook.prototype.disable_paste = function () {
         if (this.paste_enabled) {
             $('#paste_cell_replace').addClass('disabled').off('click');
             $('#paste_cell_above').addClass('disabled').off('click');
             $('#paste_cell_below').addClass('disabled').off('click');
             this.paste_enabled = false;
         }
     };
 
     /**
      * Cut a cell.
      * 
      * @method cut_cell
      */
     Notebook.prototype.cut_cell = function () {
         this.copy_cell();
         this.delete_cell();
     };
 
     /**
      * Copy a cell.
      * 
      * @method copy_cell
      */
     Notebook.prototype.copy_cell = function () {
         var cell = this.get_selected_cell();
         this.clipboard = cell.toJSON();
         // remove undeletable status from the copied cell
         if (this.clipboard.metadata.deletable !== undefined) {
             delete this.clipboard.metadata.deletable;
         }
         this.enable_paste();
     };
 
     /**
      * Replace the selected cell with a cell in the clipboard.
      * 
      * @method paste_cell_replace
      */
     Notebook.prototype.paste_cell_replace = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             var old_cell = this.get_next_cell(new_cell);
             this.delete_cell(this.find_cell_index(old_cell));
             this.select(this.find_cell_index(new_cell));
         }
     };
 
     /**
      * Paste a cell from the clipboard above the selected cell.
      * 
      * @method paste_cell_above
      */
     Notebook.prototype.paste_cell_above = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     /**
      * Paste a cell from the clipboard below the selected cell.
      * 
      * @method paste_cell_below
      */
     Notebook.prototype.paste_cell_below = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_below(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     // Split/merge
 
     /**
      * Split the selected cell into two, at the cursor.
      * 
      * @method split_cell
      */
     Notebook.prototype.split_cell = function () {
         var cell = this.get_selected_cell();
         if (cell.is_splittable()) {
             var texta = cell.get_pre_cursor();
             var textb = cell.get_post_cursor();
             cell.set_text(textb);
             var new_cell = this.insert_cell_above(cell.cell_type);
             // Unrender the new cell so we can call set_text.
             new_cell.unrender();
             new_cell.set_text(texta);
         }
     };
 
     /**
      * Combine the selected cell into the cell above it.
      * 
      * @method merge_cell_above
      */
     Notebook.prototype.merge_cell_above = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index > 0) {
             var upper_cell = this.get_cell(index-1);
             if (!upper_cell.is_mergeable()) {
                 return;
             }
             var upper_text = upper_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(upper_text+'\n'+text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(upper_text+'\n\n'+text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index-1);
             this.select(this.find_cell_index(cell));
         }
     };
 
     /**
      * Combine the selected cell into the cell below it.
      * 
      * @method merge_cell_below
      */
     Notebook.prototype.merge_cell_below = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index < this.ncells()-1) {
             var lower_cell = this.get_cell(index+1);
             if (!lower_cell.is_mergeable()) {
                 return;
             }
             var lower_text = lower_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(text+'\n'+lower_text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(text+'\n\n'+lower_text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index+1);
             this.select(this.find_cell_index(cell));
         }
     };
 
 
     // Cell collapsing and output clearing
 
     /**
      * Hide a cell's output.
      * 
      * @method collapse_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.collapse_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.collapse_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide each code cell's output area.
      * 
      * @method collapse_all_output
      */
     Notebook.prototype.collapse_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.collapse_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Show a cell's output.
      * 
      * @method expand_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.expand_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.expand_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and remove scrollbars.
      * 
      * @method expand_all_output
      */
     Notebook.prototype.expand_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.expand_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Clear the selected CodeCell's output area.
      * 
      * @method clear_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.clear_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.clear_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Clear each code cell's output area.
      * 
      * @method clear_all_output
      */
     Notebook.prototype.clear_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.clear_output();
             }
         });
         this.set_dirty(true);
     };
 
     /**
      * Scroll the selected CodeCell's output area.
      * 
      * @method scroll_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.scroll_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.scroll_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and add a scrollbar for long output.
      * 
      * @method scroll_all_output
      */
     Notebook.prototype.scroll_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.scroll_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /** Toggle whether a cell's output is collapsed or expanded.
      * 
      * @method toggle_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide/show the output of all cells.
      * 
      * @method toggle_all_output
      */
     Notebook.prototype.toggle_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Toggle a scrollbar for long cell outputs.
      * 
      * @method toggle_output_scroll
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output_scroll = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output_scroll();
             this.set_dirty(true);
         }
     };
 
     /**
      * Toggle the scrolling of long output on all cells.
      * 
      * @method toggle_all_output_scrolling
      */
     Notebook.prototype.toggle_all_output_scroll = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output_scroll();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     // Other cell functions: line numbers, ...
 
     /**
      * Toggle line numbers in the selected cell's input area.
      * 
      * @method cell_toggle_line_numbers
      */
     Notebook.prototype.cell_toggle_line_numbers = function() {
         this.get_selected_cell().toggle_line_numbers();
     };
     
     /**
      * Set the codemirror mode for all code cells, including the default for
      * new code cells.
      * 
      * @method set_codemirror_mode
      */
     Notebook.prototype.set_codemirror_mode = function(newmode){
         if (newmode === this.codemirror_mode) {
             return;
         }
         this.codemirror_mode = newmode;
         codecell.CodeCell.options_default.cm_config.mode = newmode;
         var modename = newmode.mode || newmode.name || newmode;
         
         var that = this;
         utils.requireCodeMirrorMode(modename, function () {
             that.get_cells().map(function(cell, i) {
                 if (cell.cell_type === 'code'){
                     cell.code_mirror.setOption('mode', newmode);
                     // This is currently redundant, because cm_config ends up as
                     // codemirror's own .options object, but I don't want to
                     // rely on that.
                     cell.cm_config.mode = newmode;
                 }
             });
         });
     };
 
     // Session related things
 
     /**
      * Start a new session and set it on each code cell.
      * 
      * @method start_session
      */
     Notebook.prototype.start_session = function (kernel_name) {
         if (this._session_starting) {
             throw new session.SessionAlreadyStarting();
         }
         this._session_starting = true;
 
         var options = {
             base_url: this.base_url,
             ws_url: this.ws_url,
             notebook_path: this.notebook_path,
             notebook_name: this.notebook_name,
             kernel_name: kernel_name,
             notebook: this
         };
 
         var success = $.proxy(this._session_started, this);
         var failure = $.proxy(this._session_start_failed, this);
 
         if (this.session !== null) {
             this.session.restart(options, success, failure);
         } else {
             this.session = new session.Session(options);
             this.session.start(success, failure);
         }
     };
 
 
     /**
      * Once a session is started, link the code cells to the kernel and pass the 
      * comm manager to the widget manager
      *
      */
     Notebook.prototype._session_started = function (){
         this._session_starting = false;
         this.kernel = this.session.kernel;
         var ncells = this.ncells();
         for (var i=0; i<ncells; i++) {
             var cell = this.get_cell(i);
             if (cell instanceof codecell.CodeCell) {
                 cell.set_kernel(this.session.kernel);
             }
         }
     };
     Notebook.prototype._session_start_failed = function (jqxhr, status, error){
         this._session_starting = false;
         utils.log_ajax_error(jqxhr, status, error);
     };
     
     /**
      * Prompt the user to restart the IPython kernel.
      * 
      * @method restart_kernel
      */
     Notebook.prototype.restart_kernel = function () {
         var that = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Restart kernel or continue running?",
             body : $("<p/>").text(
                 'Do you want to restart the current kernel?  You will lose all variables defined in it.'
             ),
             buttons : {
                 "Continue running" : {},
                 "Restart" : {
                     "class" : "btn-danger",
                     "click" : function() {
                         that.kernel.restart();
                     }
                 }
             }
         });
     };
     
     /**
      * Execute or render cell outputs and go into command mode.
      * 
      * @method execute_cell
      */
     Notebook.prototype.execute_cell = function () {
         // mode = shift, ctrl, alt
         var cell = this.get_selected_cell();
         
         cell.execute();
         this.command_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and insert a new cell below.
      * 
      * @method execute_cell_and_insert_below
      */
     Notebook.prototype.execute_cell_and_insert_below = function () {
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.insert_cell_below();
         this.select(cell_index+1);
         this.edit_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and select the next cell.
      * 
      * @method execute_cell_and_select_below
      */
     Notebook.prototype.execute_cell_and_select_below = function () {
 
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.select(cell_index+1);
         this.focus_cell();
         this.set_dirty(true);
     };
 
     /**
      * Execute all cells below the selected cell.
      * 
      * @method execute_cells_below
      */
     Notebook.prototype.execute_cells_below = function () {
         this.execute_cell_range(this.get_selected_index(), this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute all cells above the selected cell.
      * 
      * @method execute_cells_above
      */
     Notebook.prototype.execute_cells_above = function () {
         this.execute_cell_range(0, this.get_selected_index());
     };
 
     /**
      * Execute all cells.
      * 
      * @method execute_all_cells
      */
     Notebook.prototype.execute_all_cells = function () {
         this.execute_cell_range(0, this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute a contiguous range of cells.
      * 
      * @method execute_cell_range
      * @param {Number} start Index of the first cell to execute (inclusive)
      * @param {Number} end Index of the last cell to execute (exclusive)
      */
     Notebook.prototype.execute_cell_range = function (start, end) {
         this.command_mode();
         for (var i=start; i<end; i++) {
             this.select(i);
             this.execute_cell();
         }
     };
 
     // Persistance and loading
 
     /**
      * Getter method for this notebook's name.
      * 
      * @method get_notebook_name
      * @return {String} This notebook's name (excluding file extension)
      */
     Notebook.prototype.get_notebook_name = function () {
         var nbname = this.notebook_name.substring(0,this.notebook_name.length-6);
         return nbname;
     };
 
     /**
      * Setter method for this notebook's name.
      *
      * @method set_notebook_name
      * @param {String} name A new name for this notebook
      */
     Notebook.prototype.set_notebook_name = function (name) {
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.notebook_name = name;
         this.notebook_path = utils.url_path_join(parent, name);
     };
 
     /**
      * Check that a notebook's name is valid.
      * 
      * @method test_notebook_name
      * @param {String} nbname A name for this notebook
      * @return {Boolean} True if the name is valid, false if invalid
      */
     Notebook.prototype.test_notebook_name = function (nbname) {
         nbname = nbname || '';
         if (nbname.length>0 && !this.notebook_name_blacklist_re.test(nbname)) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Load a notebook from JSON (.ipynb).
      * 
      * @method fromJSON
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.fromJSON = function (data) {
 
         var content = data.content;
         var ncells = this.ncells();
         var i;
         for (i=0; i<ncells; i++) {
             // Always delete cell 0 as they get renumbered as they are deleted.
             this.delete_cell(0);
         }
         // Save the metadata and name.
         this.metadata = content.metadata;
         this.notebook_name = data.name;
         this.notebook_path = data.path;
         var trusted = true;
         
         // Trigger an event changing the kernel spec - this will set the default
         // codemirror mode
         if (this.metadata.kernelspec !== undefined) {
             this.events.trigger('spec_changed.Kernel', this.metadata.kernelspec);
         }
         
         // Set the codemirror mode from language_info metadata
         if (this.metadata.language_info !== undefined) {
             var langinfo = this.metadata.language_info;
             // Mode 'null' should be plain, unhighlighted text.
-            var cm_mode = langinfo.codemirror_mode || langinfo.language || 'null';
+            var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             this.set_codemirror_mode(cm_mode);
         }
         
         var new_cells = content.cells;
         ncells = new_cells.length;
         var cell_data = null;
         var new_cell = null;
         for (i=0; i<ncells; i++) {
             cell_data = new_cells[i];
             new_cell = this.insert_cell_at_index(cell_data.cell_type, i);
             new_cell.fromJSON(cell_data);
             if (new_cell.cell_type == 'code' && !new_cell.output_area.trusted) {
                 trusted = false;
             }
         }
         if (trusted !== this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
     };
 
     /**
      * Dump this notebook into a JSON-friendly object.
      * 
      * @method toJSON
      * @return {Object} A JSON-friendly representation of this notebook.
      */
     Notebook.prototype.toJSON = function () {
         // remove the conversion indicator, which only belongs in-memory
         delete this.metadata.orig_nbformat;
         delete this.metadata.orig_nbformat_minor;
 
         var cells = this.get_cells();
         var ncells = cells.length;
         var cell_array = new Array(ncells);
         var trusted = true;
         for (var i=0; i<ncells; i++) {
             var cell = cells[i];
             if (cell.cell_type == 'code' && !cell.output_area.trusted) {
                 trusted = false;
             }
             cell_array[i] = cell.toJSON();
         }
         var data = {
             cells: cell_array,
             metadata: this.metadata,
             nbformat: this.nbformat,
             nbformat_minor: this.nbformat_minor
         };
         if (trusted != this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
         return data;
     };
 
     /**
      * Start an autosave timer, for periodically saving the notebook.
      * 
      * @method set_autosave_interval
      * @param {Integer} interval the autosave interval in milliseconds
      */
     Notebook.prototype.set_autosave_interval = function (interval) {
         var that = this;
         // clear previous interval, so we don't get simultaneous timers
         if (this.autosave_timer) {
             clearInterval(this.autosave_timer);
         }
         if (!this.writable) {
             // disable autosave if not writable
             interval = 0;
         }
         
         this.autosave_interval = this.minimum_autosave_interval = interval;
         if (interval) {
             this.autosave_timer = setInterval(function() {
                 if (that.dirty) {
                     that.save_notebook();
                 }
             }, interval);
             this.events.trigger("autosave_enabled.Notebook", interval);
         } else {
             this.autosave_timer = null;
             this.events.trigger("autosave_disabled.Notebook");
         }
     };
     
     /**
      * Save this notebook on the server. This becomes a notebook instance's
      * .save_notebook method *after* the entire notebook has been loaded.
      * 
      * @method save_notebook
      */
     Notebook.prototype.save_notebook = function () {
         if (!this._fully_loaded) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Load failed, save is disabled")
             );
             return;
         } else if (!this.writable) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Notebook is read-only")
             );
             return;
         }
 
         // Create a JSON model to be sent to the server.
         var model = {
             type : "notebook",
             content : this.toJSON()
         };
         // time the ajax call for autosave tuning purposes.
         var start =  new Date().getTime();
 
         var that = this;
         return this.contents.save(this.notebook_path, model).then(
                 $.proxy(this.save_notebook_success, this, start),
                 function (error) {
                     that.events.trigger('notebook_save_failed.Notebook', error);
                 }
             );
     };
     
     /**
      * Success callback for saving a notebook.
      * 
      * @method save_notebook_success
      * @param {Integer} start Time when the save request start
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.save_notebook_success = function (start, data) {
         this.set_dirty(false);
         if (data.message) {
             // save succeeded, but validation failed.
             var body = $("<div>");
             var title = "Notebook validation failed";
 
             body.append($("<p>").text(
                 "The save operation succeeded," +
                 " but the notebook does not appear to be valid." +
                 " The validation error was:"
             )).append($("<div>").addClass("validation-error").append(
                 $("<pre>").text(data.message)
             ));
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         this.events.trigger('notebook_saved.Notebook');
         this._update_autosave_interval(start);
         if (this._checkpoint_after_save) {
             this.create_checkpoint();
             this._checkpoint_after_save = false;
         }
     };
     
     /**
      * update the autosave interval based on how long the last save took
      * 
      * @method _update_autosave_interval
      * @param {Integer} timestamp when the save request started
      */
     Notebook.prototype._update_autosave_interval = function (start) {
         var duration = (new Date().getTime() - start);
         if (this.autosave_interval) {
             // new save interval: higher of 10x save duration or parameter (default 30 seconds)
             var interval = Math.max(10 * duration, this.minimum_autosave_interval);
             // round to 10 seconds, otherwise we will be setting a new interval too often
             interval = 10000 * Math.round(interval / 10000);
             // set new interval, if it's changed
             if (interval != this.autosave_interval) {
                 this.set_autosave_interval(interval);
             }
         }
     };
 
     /**
      * Explicitly trust the output of this notebook.
      *
      * @method trust_notebook
      */
     Notebook.prototype.trust_notebook = function () {
         var body = $("<div>").append($("<p>")
             .text("A trusted IPython notebook may execute hidden malicious code ")
             .append($("<strong>")
                 .append(
                     $("<em>").text("when you open it")
                 )
             ).append(".").append(
                 " Selecting trust will immediately reload this notebook in a trusted state."
             ).append(
                 " For more information, see the "
             ).append($("<a>").attr("href", "http://ipython.org/ipython-doc/2/notebook/security.html")
                 .text("IPython security documentation")
             ).append(".")
         );
 
         var nb = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Trust this notebook?",
             body: body,
 
             buttons: {
                 Cancel : {},
                 Trust : {
                     class : "btn-danger",
                     click : function () {
                         var cells = nb.get_cells();
                         for (var i = 0; i < cells.length; i++) {
                             var cell = cells[i];
                             if (cell.cell_type == 'code') {
                                 cell.output_area.trusted = true;
                             }
                         }
                         nb.events.on('notebook_saved.Notebook', function () {
                             window.location.reload();
                         });
                         nb.save_notebook();
                     }
                 }
             }
         });
     };
 
     Notebook.prototype.copy_notebook = function () {
         var that = this;
         var base_url = this.base_url;
         var w = window.open();
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.contents.copy(this.notebook_path, parent).then(
             function (data) {
                 w.location = utils.url_join_encode(
                     base_url, 'notebooks', data.path
                 );
             },
             function(error) {
                 w.close();
                 that.events.trigger('notebook_copy_failed', error);
             }
         );
     };
 
     Notebook.prototype.rename = function (new_name) {
         if (!new_name.match(/\.ipynb$/)) {
             new_name = new_name + ".ipynb";
         }
 
         var that = this;
         var parent = utils.url_path_split(this.notebook_path)[0];
         var new_path = utils.url_path_join(parent, new_name);
         return this.contents.rename(this.notebook_path, new_path).then(
             function (json) {
                 that.notebook_name = json.name;
                 that.notebook_path = json.path;
                 that.session.rename_notebook(json.path);
                 that.events.trigger('notebook_renamed.Notebook', json);
             }
         );
     };
 
     Notebook.prototype.delete = function () {
         this.contents.delete(this.notebook_path);
     };
 
     /**
      * Request a notebook's data from the server.
      * 
      * @method load_notebook
      * @param {String} notebook_path A notebook to load
      */
     Notebook.prototype.load_notebook = function (notebook_path) {
         this.notebook_path = notebook_path;
         this.notebook_name = utils.url_path_split(this.notebook_path)[1];
         this.events.trigger('notebook_loading.Notebook');
         this.contents.get(notebook_path, {type: 'notebook'}).then(
             $.proxy(this.load_notebook_success, this),
             $.proxy(this.load_notebook_error, this)
         );
     };
 
     /**
      * Success callback for loading a notebook from the server.
      * 
      * Load notebook data from the JSON response.
      * 
      * @method load_notebook_success
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.load_notebook_success = function (data) {
         var failed, msg;
         try {
             this.fromJSON(data);
         } catch (e) {
             failed = e;
             console.log("Notebook failed to load from JSON:", e);
         }
         if (failed || data.message) {
             // *either* fromJSON failed or validation failed
             var body = $("<div>");
             var title;
             if (failed) {
                 title = "Notebook failed to load";
                 body.append($("<p>").text(
                     "The error was: "
                 )).append($("<div>").addClass("js-error").text(
                     failed.toString()
                 )).append($("<p>").text(
                     "See the error console for details."
                 ));
             } else {
                 title = "Notebook validation failed";
             }
 
             if (data.message) {
                 if (failed) {
                     msg = "The notebook also failed validation:";
                 } else {
                     msg = "An invalid notebook may not function properly." +
                     " The validation error was:";
                 }
                 body.append($("<p>").text(
                     msg
                 )).append($("<div>").addClass("validation-error").append(
                     $("<pre>").text(data.message)
                 ));
             }
 
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         if (this.ncells() === 0) {
             this.insert_cell_below('code');
             this.edit_mode(0);
         } else {
             this.select(0);
             this.handle_command_mode(this.get_cell(0));
         }
         this.set_dirty(false);
         this.scroll_to_top();
         this.writable = data.writable || false;
         var nbmodel = data.content;
         var orig_nbformat = nbmodel.metadata.orig_nbformat;
         var orig_nbformat_minor = nbmodel.metadata.orig_nbformat_minor;
         if (orig_nbformat !== undefined && nbmodel.nbformat !== orig_nbformat) {
             var src;
             if (nbmodel.nbformat > orig_nbformat) {
                 src = " an older notebook format ";
             } else {
                 src = " a newer notebook format ";
             }
             
             msg = "This notebook has been converted from" + src +
             "(v"+orig_nbformat+") to the current notebook " +
             "format (v"+nbmodel.nbformat+"). The next time you save this notebook, the " +
             "current notebook format will be used.";
             
             if (nbmodel.nbformat > orig_nbformat) {
                 msg += " Older versions of IPython may not be able to read the new format.";
             } else {
                 msg += " Some features of the original notebook may not be available.";
             }
             msg += " To preserve the original version, close the " +
                 "notebook without saving it.";
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title : "Notebook converted",
                 body : msg,
                 buttons : {
                     OK : {
                         class : "btn-primary"
                     }
                 }
             });
         } else if (this.nbformat_minor < nbmodel.nbformat_minor) {
             this.nbformat_minor = nbmodel.nbformat_minor;
         }
         
         // Create the session after the notebook is completely loaded to prevent
         // code execution upon loading, which is a security risk.
         if (this.session === null) {
             var kernelspec = this.metadata.kernelspec || {};
             var kernel_name = kernelspec.name;
 
             this.start_session(kernel_name);
         }
         // load our checkpoint list
         this.list_checkpoints();
         
         // load toolbar state
         if (this.metadata.celltoolbar) {
             celltoolbar.CellToolbar.global_show();
             celltoolbar.CellToolbar.activate_preset(this.metadata.celltoolbar);
         } else {
             celltoolbar.CellToolbar.global_hide();
         }
         
         if (!this.writable) {
             this.set_autosave_interval(0);
             this.events.trigger('notebook_read_only.Notebook');
         }
         
         // now that we're fully loaded, it is safe to restore save functionality
         this._fully_loaded = true;
         this.events.trigger('notebook_loaded.Notebook');
     };
 
     /**
      * Failure callback for loading a notebook from the server.
      * 
      * @method load_notebook_error
      * @param {Error} error
      */
     Notebook.prototype.load_notebook_error = function (error) {
         this.events.trigger('notebook_load_failed.Notebook', error);
         var msg;
         if (error.name === utils.XHR_ERROR && error.xhr.status === 500) {
             utils.log_ajax_error(error.xhr, error.xhr_status, error.xhr_error);
             msg = "An unknown error occurred while loading this notebook. " +
             "This version can load notebook formats " +
             "v" + this.nbformat + " or earlier. See the server log for details.";
         } else {
             msg = error.message;
         }
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Error loading notebook",
             body : msg,
             buttons : {
                 "OK": {}
             }
         });
     };
 
     /*********************  checkpoint-related  *********************/
     
     /**
      * Save the notebook then immediately create a checkpoint.
      * 
      * @method save_checkpoint
      */
     Notebook.prototype.save_checkpoint = function () {
         this._checkpoint_after_save = true;
         this.save_notebook();
     };
     
     /**
      * Add a checkpoint for this notebook.
      * for use as a callback from checkpoint creation.
      * 
      * @method add_checkpoint
      */
     Notebook.prototype.add_checkpoint = function (checkpoint) {
         var found = false;
         for (var i = 0; i < this.checkpoints.length; i++) {
             var existing = this.checkpoints[i];
             if (existing.id == checkpoint.id) {
                 found = true;
                 this.checkpoints[i] = checkpoint;
                 break;
             }
         }
         if (!found) {
             this.checkpoints.push(checkpoint);
         }
         this.last_checkpoint = this.checkpoints[this.checkpoints.length - 1];
     };
     
     /**
      * List checkpoints for this notebook.
      * 
      * @method list_checkpoints
      */
     Notebook.prototype.list_checkpoints = function () {
         var that = this;
         this.contents.list_checkpoints(this.notebook_path).then(
             $.proxy(this.list_checkpoints_success, this),
             function(error) {
                 that.events.trigger('list_checkpoints_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for listing checkpoints.
      * 
      * @method list_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.list_checkpoints_success = function (data) {
         this.checkpoints = data;
         if (data.length) {
             this.last_checkpoint = data[data.length - 1];
         } else {
             this.last_checkpoint = null;
         }
         this.events.trigger('checkpoints_listed.Notebook', [data]);
     };
 
     /**
      * Create a checkpoint of this notebook on the server from the most recent save.
      * 
      * @method create_checkpoint
      */
     Notebook.prototype.create_checkpoint = function () {
         var that = this;
         this.contents.create_checkpoint(this.notebook_path).then(
             $.proxy(this.create_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for creating a checkpoint.
      * 
      * @method create_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.create_checkpoint_success = function (data) {
         this.add_checkpoint(data);
         this.events.trigger('checkpoint_created.Notebook', data);
     };
 
     Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) {
         var that = this;
         checkpoint = checkpoint || this.last_checkpoint;
         if ( ! checkpoint ) {
             console.log("restore dialog, but no checkpoint to restore to!");
             return;
         }
         var body = $('<div/>').append(
             $('<p/>').addClass("p-space").text(
                 "Are you sure you want to revert the notebook to " +
                 "the latest checkpoint?"
             ).append(
                 $("<strong/>").text(
                     " This cannot be undone."
                 )
             )
         ).append(
             $('<p/>').addClass("p-space").text("The checkpoint was last updated at:")
         ).append(
             $('<p/>').addClass("p-space").text(
                 Date(checkpoint.last_modified)
             ).css("text-align", "center")
         );
         
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Revert notebook to checkpoint",
             body : body,
             buttons : {
                 Revert : {
                     class : "btn-danger",
                     click : function () {
                         that.restore_checkpoint(checkpoint.id);
                     }
                 },
                 Cancel : {}
                 }
         });
     };
     
     /**
      * Restore the notebook to a checkpoint state.
      * 
      * @method restore_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.restore_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.restore_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.restore_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_restore_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for restoring a notebook to a checkpoint.
      * 
      * @method restore_checkpoint_success
      */
     Notebook.prototype.restore_checkpoint_success = function () {
         this.events.trigger('checkpoint_restored.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
     /**
      * Delete a notebook checkpoint.
      * 
      * @method delete_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.delete_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.delete_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.delete_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_delete_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for deleting a notebook checkpoint
      * 
      * @method delete_checkpoint_success
      */
     Notebook.prototype.delete_checkpoint_success = function () {
         this.events.trigger('checkpoint_deleted.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
 
     // For backwards compatability.
     IPython.Notebook = Notebook;
 
     return {'Notebook': Notebook};
 });

IPython/kernel/adapter.py

@@ -1,356 +1,369
 """Adapters for IPython msg spec versions."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import json
 
 from IPython.core.release import kernel_protocol_version_info
 from IPython.utils.tokenutil import token_at_cursor
 
 
 def code_to_line(code, cursor_pos):
     """Turn a multiline code block and cursor position into a single line
     and new cursor position.
     
     For adapting ``complete_`` and ``object_info_request``.
     """
     if not code:
         return "", 0
     for line in code.splitlines(True):
         n = len(line)
         if cursor_pos > n:
             cursor_pos -= n
         else:
             break
     return line, cursor_pos
 
 
 class Adapter(object):
     """Base class for adapting messages
     
     Override message_type(msg) methods to create adapters.
     """
     
     msg_type_map = {}
     
     def update_header(self, msg):
         return msg
     
     def update_metadata(self, msg):
         return msg
     
     def update_msg_type(self, msg):
         header = msg['header']
         msg_type = header['msg_type']
         if msg_type in self.msg_type_map:
             msg['msg_type'] = header['msg_type'] = self.msg_type_map[msg_type]
         return msg
     
     def handle_reply_status_error(self, msg):
         """This will be called *instead of* the regular handler
         
         on any reply with status != ok
         """
         return msg
     
     def __call__(self, msg):
         msg = self.update_header(msg)
         msg = self.update_metadata(msg)
         msg = self.update_msg_type(msg)
         header = msg['header']
         
         handler = getattr(self, header['msg_type'], None)
         if handler is None:
             return msg
         
         # handle status=error replies separately (no change, at present)
         if msg['content'].get('status', None) in {'error', 'aborted'}:
             return self.handle_reply_status_error(msg)
         return handler(msg)
 
 def _version_str_to_list(version):
     """convert a version string to a list of ints
     
     non-int segments are excluded
     """
     v = []
     for part in version.split('.'):
         try:
             v.append(int(part))
         except ValueError:
             pass
     return v
 
 class V5toV4(Adapter):
     """Adapt msg protocol v5 to v4"""
     
     version = '4.1'
     
     msg_type_map = {
         'execute_result' : 'pyout',
         'execute_input' : 'pyin',
         'error' : 'pyerr',
         'inspect_request' : 'object_info_request',
         'inspect_reply' : 'object_info_reply',
     }
     
     def update_header(self, msg):
         msg['header'].pop('version', None)
         return msg
     
     # shell channel
     
     def kernel_info_reply(self, msg):
+        v4c = {}
         content = msg['content']
-        content.pop('banner', None)
         for key in ('language_version', 'protocol_version'):
             if key in content:
-                content[key] = _version_str_to_list(content[key])
-        if content.pop('implementation', '') == 'ipython' \
+                v4c[key] = _version_str_to_list(content[key])
+        if content.get('implementation', '') == 'ipython' \
             and 'implementation_version' in content:
-            content['ipython_version'] = content.pop('implmentation_version')
-        content.pop('implementation_version', None)
-        content.setdefault("implmentation", content['language'])
+            v4c['ipython_version'] = _version_str_to_list(content['implementation_version'])
+        language_info = content.get('language_info', {})
+        language = language_info.get('name', '')
+        v4c.setdefault('language', language)
+        if 'version' in language_info:
+            v4c.setdefault('language_version', _version_str_to_list(language_info['version']))
+        msg['content'] = v4c
         return msg
     
     def execute_request(self, msg):
         content = msg['content']
         content.setdefault('user_variables', [])
         return msg
     
     def execute_reply(self, msg):
         content = msg['content']
         content.setdefault('user_variables', {})
         # TODO: handle payloads
         return msg
     
     def complete_request(self, msg):
         content = msg['content']
         code = content['code']
         cursor_pos = content['cursor_pos']
         line, cursor_pos = code_to_line(code, cursor_pos)
         
         new_content = msg['content'] = {}
         new_content['text'] = ''
         new_content['line'] = line
         new_content['block'] = None
         new_content['cursor_pos'] = cursor_pos
         return msg
     
     def complete_reply(self, msg):
         content = msg['content']
         cursor_start = content.pop('cursor_start')
         cursor_end = content.pop('cursor_end')
         match_len = cursor_end - cursor_start
         content['matched_text'] = content['matches'][0][:match_len]
         content.pop('metadata', None)
         return msg
     
     def object_info_request(self, msg):
         content = msg['content']
         code = content['code']
         cursor_pos = content['cursor_pos']
         line, _ = code_to_line(code, cursor_pos)
         
         new_content = msg['content'] = {}
         new_content['oname'] = token_at_cursor(code, cursor_pos)
         new_content['detail_level'] = content['detail_level']
         return msg
     
     def object_info_reply(self, msg):
         """inspect_reply can't be easily backward compatible"""
         msg['content'] = {'found' : False, 'oname' : 'unknown'}
         return msg
     
     # iopub channel
     
     def stream(self, msg):
         content = msg['content']
         content['data'] = content.pop('text')
         return msg
 
     def display_data(self, msg):
         content = msg['content']
         content.setdefault("source", "display")
         data = content['data']
         if 'application/json' in data:
             try:
                 data['application/json'] = json.dumps(data['application/json'])
             except Exception:
                 # warn?
                 pass
         return msg
     
     # stdin channel
     
     def input_request(self, msg):
         msg['content'].pop('password', None)
         return msg
 
 
 class V4toV5(Adapter):
     """Convert msg spec V4 to V5"""
     version = '5.0'
     
     # invert message renames above
     msg_type_map = {v:k for k,v in V5toV4.msg_type_map.items()}
     
     def update_header(self, msg):
         msg['header']['version'] = self.version
         return msg
     
     # shell channel
     
     def kernel_info_reply(self, msg):
         content = msg['content']
-        for key in ('language_version', 'protocol_version', 'ipython_version'):
+        for key in ('protocol_version', 'ipython_version'):
             if key in content:
-                content[key] = ".".join(map(str, content[key]))
+                content[key] = '.'.join(map(str, content[key]))
+        
+        content.setdefault('protocol_version', '4.1')
         
         if content['language'].startswith('python') and 'ipython_version' in content:
             content['implementation'] = 'ipython'
             content['implementation_version'] = content.pop('ipython_version')
         
+        language = content.pop('language')
+        language_info = content.setdefault('language_info', {})
+        language_info.setdefault('name', language)
+        if 'language_version' in content:
+            language_version = '.'.join(map(str, content.pop('language_version')))
+            language_info.setdefault('version', language_version)
+        
         content['banner'] = ''
         return msg
     
     def execute_request(self, msg):
         content = msg['content']
         user_variables = content.pop('user_variables', [])
         user_expressions = content.setdefault('user_expressions', {})
         for v in user_variables:
             user_expressions[v] = v
         return msg
     
     def execute_reply(self, msg):
         content = msg['content']
         user_expressions = content.setdefault('user_expressions', {})
         user_variables = content.pop('user_variables', {})
         if user_variables:
             user_expressions.update(user_variables)
 
         # Pager payloads became a mime bundle
         for payload in content.get('payload', []):
             if payload.get('source', None) == 'page' and ('text' in payload):
                 if 'data' not in payload:
                     payload['data'] = {}
                 payload['data']['text/plain'] = payload.pop('text')
 
         return msg
     
     def complete_request(self, msg):
         old_content = msg['content']
         
         new_content = msg['content'] = {}
         new_content['code'] = old_content['line']
         new_content['cursor_pos'] = old_content['cursor_pos']
         return msg
     
     def complete_reply(self, msg):
         # complete_reply needs more context than we have to get cursor_start and end.
         # use special value of `-1` to indicate to frontend that it should be at
         # the current cursor position.
         content = msg['content']
         new_content = msg['content'] = {'status' : 'ok'}
         new_content['matches'] = content['matches']
         new_content['cursor_start'] = -len(content['matched_text'])
         new_content['cursor_end'] = None
         new_content['metadata'] = {}
         return msg
     
     def inspect_request(self, msg):
         content = msg['content']
         name = content['oname']
         
         new_content = msg['content'] = {}
         new_content['code'] = name
         new_content['cursor_pos'] = len(name)
         new_content['detail_level'] = content['detail_level']
         return msg
     
     def inspect_reply(self, msg):
         """inspect_reply can't be easily backward compatible"""
         content = msg['content']
         new_content = msg['content'] = {'status' : 'ok'}
         found = new_content['found'] = content['found']
         new_content['name'] = content['oname']
         new_content['data'] = data = {}
         new_content['metadata'] = {}
         if found:
             lines = []
             for key in ('call_def', 'init_definition', 'definition'):
                 if content.get(key, False):
                     lines.append(content[key])
                     break
             for key in ('call_docstring', 'init_docstring', 'docstring'):
                 if content.get(key, False):
                     lines.append(content[key])
                     break
             if not lines:
                 lines.append("<empty docstring>")
             data['text/plain'] = '\n'.join(lines)
         return msg
     
     # iopub channel
     
     def stream(self, msg):
         content = msg['content']
         content['text'] = content.pop('data')
         return msg
 
     def display_data(self, msg):
         content = msg['content']
         content.pop("source", None)
         data = content['data']
         if 'application/json' in data:
             try:
                 data['application/json'] = json.loads(data['application/json'])
             except Exception:
                 # warn?
                 pass
         return msg
     
     # stdin channel
     
     def input_request(self, msg):
         msg['content'].setdefault('password', False)
         return msg
     
 
 
 def adapt(msg, to_version=kernel_protocol_version_info[0]):
     """Adapt a single message to a target version
     
     Parameters
     ----------
     
     msg : dict
         An IPython message.
     to_version : int, optional
         The target major version.
         If unspecified, adapt to the current version for IPython.
     
     Returns
     -------
     
     msg : dict
         An IPython message appropriate in the new version.
     """
     header = msg['header']
     if 'version' in header:
         from_version = int(header['version'].split('.')[0])
     else:
         # assume last version before adding the key to the header
         from_version = 4
     adapter = adapters.get((from_version, to_version), None)
     if adapter is None:
         return msg
     return adapter(msg)
 
 
 # one adapter per major version from,to
 adapters = {
     (5,4) : V5toV4(),
     (4,5) : V4toV5(),
 }

IPython/kernel/tests/test_adapter.py

@@ -1,334 +1,377
 """Tests for adapting IPython msg spec versions"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import copy
 import json
 from unittest import TestCase
 import nose.tools as nt
 
 from IPython.kernel.adapter import adapt, V4toV5, V5toV4, code_to_line
 from IPython.kernel.zmq.session import Session
 
 
 def test_default_version():
     s = Session()
     msg = s.msg("msg_type")
     msg['header'].pop('version')
     original = copy.deepcopy(msg)
     adapted = adapt(original)
     nt.assert_equal(adapted['header']['version'], V4toV5.version)
 
 def test_code_to_line_no_code():
     line, pos = code_to_line("", 0)
     nt.assert_equal(line, "")
     nt.assert_equal(pos, 0)
 
 class AdapterTest(TestCase):
     
     def setUp(self):
         self.session = Session()
     
     def adapt(self, msg, version=None):
         original = copy.deepcopy(msg)
         adapted = adapt(msg, version or self.to_version)
         return original, adapted
     
     def check_header(self, msg):
         pass
 
 
 class V4toV5TestCase(AdapterTest):
     from_version = 4
     to_version = 5
     
     def msg(self, msg_type, content):
         """Create a v4 msg (same as v5, minus version header)"""
         msg = self.session.msg(msg_type, content)
         msg['header'].pop('version')
         return msg
     
     def test_same_version(self):
         msg = self.msg("execute_result",
             content={'status' : 'ok'}
         )
         original, adapted = self.adapt(msg, self.from_version)
     
         self.assertEqual(original, adapted)
     
     def test_no_adapt(self):
         msg = self.msg("input_reply", {'value' : 'some text'})
         v4, v5 = self.adapt(msg)
         self.assertEqual(v5['header']['version'], V4toV5.version)
         v5['header'].pop('version')
         self.assertEqual(v4, v5)
     
     def test_rename_type(self):
         for v5_type, v4_type in [
                 ('execute_result', 'pyout'),
                 ('execute_input', 'pyin'),
                 ('error', 'pyerr'),
             ]:
             msg = self.msg(v4_type, {'key' : 'value'})
             v4, v5 = self.adapt(msg)
             self.assertEqual(v5['header']['version'], V4toV5.version)
             self.assertEqual(v5['header']['msg_type'], v5_type)
             self.assertEqual(v4['content'], v5['content'])
     
     def test_execute_request(self):
         msg = self.msg("execute_request", {
             'code' : 'a=5',
             'silent' : False,
             'user_expressions' : {'a' : 'apple'},
             'user_variables' : ['b'],
         })
         v4, v5 = self.adapt(msg)
         self.assertEqual(v4['header']['msg_type'], v5['header']['msg_type'])
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v5c['user_expressions'], {'a' : 'apple', 'b': 'b'})
         self.assertNotIn('user_variables', v5c)
         self.assertEqual(v5c['code'], v4c['code'])
 
     def test_execute_reply(self):
         msg = self.msg("execute_reply", {
             'status': 'ok',
             'execution_count': 7,
             'user_variables': {'a': 1},
             'user_expressions': {'a+a': 2},
             'payload': [{'source':'page', 'text':'blah'}]
         })
         v4, v5 = self.adapt(msg)
         v5c = v5['content']
         self.assertNotIn('user_variables', v5c)
         self.assertEqual(v5c['user_expressions'], {'a': 1, 'a+a': 2})
         self.assertEqual(v5c['payload'], [{'source': 'page',
                                            'data': {'text/plain': 'blah'}}
                                          ])
     
     def test_complete_request(self):
         msg = self.msg("complete_request", {
             'text' : 'a.is',
             'line' : 'foo = a.is',
             'block' : None,
             'cursor_pos' : 10,
         })
         v4, v5 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         for key in ('text', 'line', 'block'):
             self.assertNotIn(key, v5c)
         self.assertEqual(v5c['cursor_pos'], v4c['cursor_pos'])
         self.assertEqual(v5c['code'], v4c['line'])
     
     def test_complete_reply(self):
         msg = self.msg("complete_reply", {
             'matched_text' : 'a.is',
             'matches' : ['a.isalnum',
                         'a.isalpha',
                         'a.isdigit',
                         'a.islower',
                         ],
         })
         v4, v5 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         
         self.assertEqual(v5c['matches'], v4c['matches'])
         self.assertEqual(v5c['metadata'], {})
         self.assertEqual(v5c['cursor_start'], -4)
         self.assertEqual(v5c['cursor_end'], None)
     
     def test_object_info_request(self):
         msg = self.msg("object_info_request", {
             'oname' : 'foo',
             'detail_level' : 1,
         })
         v4, v5 = self.adapt(msg)
         self.assertEqual(v5['header']['msg_type'], 'inspect_request')
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v5c['code'], v4c['oname'])
         self.assertEqual(v5c['cursor_pos'], len(v4c['oname']))
         self.assertEqual(v5c['detail_level'], v4c['detail_level'])
     
     def test_object_info_reply(self):
         msg = self.msg("object_info_reply", {
             'oname' : 'foo',
             'found' : True,
             'status' : 'ok',
             'definition' : 'foo(a=5)',
             'docstring' : "the docstring",
         })
         v4, v5 = self.adapt(msg)
         self.assertEqual(v5['header']['msg_type'], 'inspect_reply')
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(sorted(v5c), [ 'data', 'found', 'metadata', 'name', 'status'])
         text = v5c['data']['text/plain']
         self.assertEqual(text, '\n'.join([v4c['definition'], v4c['docstring']]))
     
+    def test_kernel_info_reply(self):
+        msg = self.msg("kernel_info_reply", {
+            'language': 'python',
+            'language_version': [2,8,0],
+            'ipython_version': [1,2,3],
+        })
+        v4, v5 = self.adapt(msg)
+        v4c = v4['content']
+        v5c = v5['content']
+        self.assertEqual(v5c, {
+            'protocol_version': '4.1',
+            'implementation': 'ipython',
+            'implementation_version': '1.2.3',
+            'language_info': {
+                'name': 'python',
+                'version': '2.8.0',
+            },
+            'banner' : '',
+        })
+    
     # iopub channel
     
     def test_display_data(self):
         jsondata = dict(a=5)
         msg = self.msg("display_data", {
             'data' : {
                 'text/plain' : 'some text',
                 'application/json' : json.dumps(jsondata)
             },
             'metadata' : {'text/plain' : { 'key' : 'value' }},
         })
         v4, v5 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v5c['metadata'], v4c['metadata'])
         self.assertEqual(v5c['data']['text/plain'], v4c['data']['text/plain'])
         self.assertEqual(v5c['data']['application/json'], jsondata)
     
     # stdin channel
     
     def test_input_request(self):
         msg = self.msg('input_request', {'prompt': "$>"})
         v4, v5 = self.adapt(msg)
         self.assertEqual(v5['content']['prompt'], v4['content']['prompt'])
         self.assertFalse(v5['content']['password'])
 
 
 class V5toV4TestCase(AdapterTest):
     from_version = 5
     to_version = 4
     
     def msg(self, msg_type, content):
         return self.session.msg(msg_type, content)
     
     def test_same_version(self):
         msg = self.msg("execute_result",
             content={'status' : 'ok'}
         )
         original, adapted = self.adapt(msg, self.from_version)
     
         self.assertEqual(original, adapted)
     
     def test_no_adapt(self):
         msg = self.msg("input_reply", {'value' : 'some text'})
         v5, v4 = self.adapt(msg)
         self.assertNotIn('version', v4['header'])
         v5['header'].pop('version')
         self.assertEqual(v4, v5)
     
     def test_rename_type(self):
         for v5_type, v4_type in [
                 ('execute_result', 'pyout'),
                 ('execute_input', 'pyin'),
                 ('error', 'pyerr'),
             ]:
             msg = self.msg(v5_type, {'key' : 'value'})
             v5, v4 = self.adapt(msg)
             self.assertEqual(v4['header']['msg_type'], v4_type)
             nt.assert_not_in('version', v4['header'])
             self.assertEqual(v4['content'], v5['content'])
     
     def test_execute_request(self):
         msg = self.msg("execute_request", {
             'code' : 'a=5',
             'silent' : False,
             'user_expressions' : {'a' : 'apple'},
         })
         v5, v4 = self.adapt(msg)
         self.assertEqual(v4['header']['msg_type'], v5['header']['msg_type'])
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v4c['user_variables'], [])
         self.assertEqual(v5c['code'], v4c['code'])
     
     def test_complete_request(self):
         msg = self.msg("complete_request", {
             'code' : 'def foo():\n'
                      '    a.is\n'
                      'foo()',
             'cursor_pos': 19,
         })
         v5, v4 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         self.assertNotIn('code', v4c)
         self.assertEqual(v4c['line'], v5c['code'].splitlines(True)[1])
         self.assertEqual(v4c['cursor_pos'], 8)
         self.assertEqual(v4c['text'], '')
         self.assertEqual(v4c['block'], None)
     
     def test_complete_reply(self):
         msg = self.msg("complete_reply", {
             'cursor_start' : 10,
             'cursor_end' : 14,
             'matches' : ['a.isalnum',
                         'a.isalpha',
                         'a.isdigit',
                         'a.islower',
                         ],
             'metadata' : {},
         })
         v5, v4 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v4c['matched_text'], 'a.is')
         self.assertEqual(v4c['matches'], v5c['matches'])
     
     def test_inspect_request(self):
         msg = self.msg("inspect_request", {
             'code' : 'def foo():\n'
                      '    apple\n'
                      'bar()',
             'cursor_pos': 18,
             'detail_level' : 1,
         })
         v5, v4 = self.adapt(msg)
         self.assertEqual(v4['header']['msg_type'], 'object_info_request')
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v4c['oname'], 'apple')
         self.assertEqual(v5c['detail_level'], v4c['detail_level'])
     
     def test_inspect_reply(self):
         msg = self.msg("inspect_reply", {
             'name' : 'foo',
             'found' : True,
             'data' : {'text/plain' : 'some text'},
             'metadata' : {},
         })
         v5, v4 = self.adapt(msg)
         self.assertEqual(v4['header']['msg_type'], 'object_info_reply')
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(sorted(v4c), ['found', 'oname'])
         self.assertEqual(v4c['found'], False)
     
+    def test_kernel_info_reply(self):
+        msg = self.msg("kernel_info_reply", {
+            'protocol_version': '5.0',
+            'implementation': 'ipython',
+            'implementation_version': '1.2.3',
+            'language_info': {
+                'name': 'python',
+                'version': '2.8.0',
+                'mimetype': 'text/x-python',
+            },
+            'banner' : 'the banner',
+        })
+        v5, v4 = self.adapt(msg)
+        v4c = v4['content']
+        v5c = v5['content']
+        info = v5c['language_info']
+        self.assertEqual(v4c, {
+            'protocol_version': [5,0],
+            'language': 'python',
+            'language_version': [2,8,0],
+            'ipython_version': [1,2,3],
+        })
+    
     # iopub channel
     
     def test_display_data(self):
         jsondata = dict(a=5)
         msg = self.msg("display_data", {
             'data' : {
                 'text/plain' : 'some text',
                 'application/json' : jsondata,
             },
             'metadata' : {'text/plain' : { 'key' : 'value' }},
         })
         v5, v4 = self.adapt(msg)
         v4c = v4['content']
         v5c = v5['content']
         self.assertEqual(v5c['metadata'], v4c['metadata'])
         self.assertEqual(v5c['data']['text/plain'], v4c['data']['text/plain'])
         self.assertEqual(v4c['data']['application/json'], json.dumps(jsondata))
     
     # stdin channel
     
     def test_input_request(self):
         msg = self.msg('input_request', {'prompt': "$>", 'password' : True})
         v5, v4 = self.adapt(msg)
         self.assertEqual(v5['content']['prompt'], v4['content']['prompt'])
         self.assertNotIn('password', v4['content'])
     
 

IPython/kernel/tests/test_message_spec.py

@@ -1,429 +1,432
 """Test suite for our zeromq-based message specification."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import re
+import sys
 from distutils.version import LooseVersion as V
-from subprocess import PIPE
 try:
     from queue import Empty  # Py 3
 except ImportError:
     from Queue import Empty  # Py 2
 
 import nose.tools as nt
 
-from IPython.kernel import KernelManager
-
 from IPython.utils.traitlets import (
-    HasTraits, TraitError, Bool, Unicode, Dict, Integer, List, Enum, Any,
+    HasTraits, TraitError, Bool, Unicode, Dict, Integer, List, Enum,
 )
 from IPython.utils.py3compat import string_types, iteritems
 
 from .utils import TIMEOUT, start_global_kernel, flush_channels, execute
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 KC = None
 
 def setup():
     global KC
     KC = start_global_kernel()
 
 #-----------------------------------------------------------------------------
 # Message Spec References
 #-----------------------------------------------------------------------------
 
 class Reference(HasTraits):
 
     """
     Base class for message spec specification testing.
 
     This class is the core of the message specification test.  The
     idea is that child classes implement trait attributes for each
     message keys, so that message keys can be tested against these
     traits using :meth:`check` method.
 
     """
 
     def check(self, d):
         """validate a dict against our traits"""
         for key in self.trait_names():
             nt.assert_in(key, d)
             # FIXME: always allow None, probably not a good idea
             if d[key] is None:
                 continue
             try:
                 setattr(self, key, d[key])
             except TraitError as e:
                 assert False, str(e)
 
 
 class Version(Unicode):
     def __init__(self, *args, **kwargs):
         self.min = kwargs.pop('min', None)
         self.max = kwargs.pop('max', None)
         kwargs['default_value'] = self.min
         super(Version, self).__init__(*args, **kwargs)
     
     def validate(self, obj, value):
         if self.min and V(value) < V(self.min):
             raise TraitError("bad version: %s < %s" % (value, self.min))
         if self.max and (V(value) > V(self.max)):
             raise TraitError("bad version: %s > %s" % (value, self.max))
 
 
 class RMessage(Reference):
     msg_id = Unicode()
     msg_type = Unicode()
     header = Dict()
     parent_header = Dict()
     content = Dict()
     
     def check(self, d):
         super(RMessage, self).check(d)
         RHeader().check(self.header)
         if self.parent_header:
             RHeader().check(self.parent_header)
 
 class RHeader(Reference):
     msg_id = Unicode()
     msg_type = Unicode()
     session = Unicode()
     username = Unicode()
     version = Version(min='5.0')
 
 mime_pat = re.compile(r'^[\w\-\+\.]+/[\w\-\+\.]+$')
 
 class MimeBundle(Reference):
     metadata = Dict()
     data = Dict()
     def _data_changed(self, name, old, new):
         for k,v in iteritems(new):
             assert mime_pat.match(k)
             nt.assert_is_instance(v, string_types)
 
 # shell replies
 
 class ExecuteReply(Reference):
     execution_count = Integer()
     status = Enum((u'ok', u'error'))
     
     def check(self, d):
         Reference.check(self, d)
         if d['status'] == 'ok':
             ExecuteReplyOkay().check(d)
         elif d['status'] == 'error':
             ExecuteReplyError().check(d)
 
 
 class ExecuteReplyOkay(Reference):
     payload = List(Dict)
     user_expressions = Dict()
 
 
 class ExecuteReplyError(Reference):
     ename = Unicode()
     evalue = Unicode()
     traceback = List(Unicode)
 
 
 class InspectReply(MimeBundle):
     found = Bool()
 
 
 class ArgSpec(Reference):
     args = List(Unicode)
     varargs = Unicode()
     varkw = Unicode()
     defaults = List()
 
 
 class Status(Reference):
     execution_state = Enum((u'busy', u'idle', u'starting'))
 
 
 class CompleteReply(Reference):
     matches = List(Unicode)
     cursor_start = Integer()
     cursor_end = Integer()
     status = Unicode()
 
+class LanguageInfo(Reference):
+    name = Unicode('python')
+    version = Unicode(sys.version.split()[0])
 
 class KernelInfoReply(Reference):
     protocol_version = Version(min='5.0')
     implementation = Unicode('ipython')
     implementation_version = Version(min='2.1')
-    language_version = Version(min='2.7')
-    language = Unicode('python')
     language_info = Dict()
     banner = Unicode()
 
+    def check(self, d):
+        Reference.check(self, d)
+        LanguageInfo().check(d['language_info'])
+
 
 class IsCompleteReply(Reference):
     status = Enum((u'complete', u'incomplete', u'invalid', u'unknown'))
     
     def check(self, d):
         Reference.check(self, d)
         if d['status'] == 'incomplete':
             IsCompleteReplyIncomplete().check(d)
 
 class IsCompleteReplyIncomplete(Reference):
     indent = Unicode()
 
 
 # IOPub messages
 
 class ExecuteInput(Reference):
     code = Unicode()
     execution_count = Integer()
 
 
 Error = ExecuteReplyError
 
 
 class Stream(Reference):
     name = Enum((u'stdout', u'stderr'))
     text = Unicode()
 
 
 class DisplayData(MimeBundle):
     pass
 
 
 class ExecuteResult(MimeBundle):
     execution_count = Integer()
 
 
 references = {
     'execute_reply' : ExecuteReply(),
     'inspect_reply' : InspectReply(),
     'status' : Status(),
     'complete_reply' : CompleteReply(),
     'kernel_info_reply': KernelInfoReply(),
     'is_complete_reply': IsCompleteReply(),
     'execute_input' : ExecuteInput(),
     'execute_result' : ExecuteResult(),
     'error' : Error(),
     'stream' : Stream(),
     'display_data' : DisplayData(),
     'header' : RHeader(),
 }
 """
 Specifications of `content` part of the reply messages.
 """
 
 
 def validate_message(msg, msg_type=None, parent=None):
     """validate a message
     
     This is a generator, and must be iterated through to actually
     trigger each test.
     
     If msg_type and/or parent are given, the msg_type and/or parent msg_id
     are compared with the given values.
     """
     RMessage().check(msg)
     if msg_type:
         nt.assert_equal(msg['msg_type'], msg_type)
     if parent:
         nt.assert_equal(msg['parent_header']['msg_id'], parent)
     content = msg['content']
     ref = references[msg['msg_type']]
     ref.check(content)
 
 
 #-----------------------------------------------------------------------------
 # Tests
 #-----------------------------------------------------------------------------
 
 # Shell channel
 
 def test_execute():
     flush_channels()
     
     msg_id = KC.execute(code='x=1')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'execute_reply', msg_id)
 
 
 def test_execute_silent():
     flush_channels()
     msg_id, reply = execute(code='x=1', silent=True)
     
     # flush status=idle
     status = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(status, 'status', msg_id)
     nt.assert_equal(status['content']['execution_state'], 'idle')
 
     nt.assert_raises(Empty, KC.iopub_channel.get_msg, timeout=0.1)
     count = reply['execution_count']
     
     msg_id, reply = execute(code='x=2', silent=True)
     
     # flush status=idle
     status = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(status, 'status', msg_id)
     nt.assert_equal(status['content']['execution_state'], 'idle')
     
     nt.assert_raises(Empty, KC.iopub_channel.get_msg, timeout=0.1)
     count_2 = reply['execution_count']
     nt.assert_equal(count_2, count)
 
 
 def test_execute_error():
     flush_channels()
     
     msg_id, reply = execute(code='1/0')
     nt.assert_equal(reply['status'], 'error')
     nt.assert_equal(reply['ename'], 'ZeroDivisionError')
     
     error = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(error, 'error', msg_id)
 
 
 def test_execute_inc():
     """execute request should increment execution_count"""
     flush_channels()
 
     msg_id, reply = execute(code='x=1')
     count = reply['execution_count']
     
     flush_channels()
     
     msg_id, reply = execute(code='x=2')
     count_2 = reply['execution_count']
     nt.assert_equal(count_2, count+1)
 
 
 def test_user_expressions():
     flush_channels()
 
     msg_id, reply = execute(code='x=1', user_expressions=dict(foo='x+1'))
     user_expressions = reply['user_expressions']
     nt.assert_equal(user_expressions, {u'foo': {
         u'status': u'ok',
         u'data': {u'text/plain': u'2'},
         u'metadata': {},
     }})
 
 
 def test_user_expressions_fail():
     flush_channels()
 
     msg_id, reply = execute(code='x=0', user_expressions=dict(foo='nosuchname'))
     user_expressions = reply['user_expressions']
     foo = user_expressions['foo']
     nt.assert_equal(foo['status'], 'error')
     nt.assert_equal(foo['ename'], 'NameError')
 
 
 def test_oinfo():
     flush_channels()
 
     msg_id = KC.inspect('a')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
 
 
 def test_oinfo_found():
     flush_channels()
 
     msg_id, reply = execute(code='a=5')
     
     msg_id = KC.inspect('a')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     assert content['found']
     text = content['data']['text/plain']
     nt.assert_in('Type:', text)
     nt.assert_in('Docstring:', text)
 
 
 def test_oinfo_detail():
     flush_channels()
 
     msg_id, reply = execute(code='ip=get_ipython()')
     
     msg_id = KC.inspect('ip.object_inspect', cursor_pos=10, detail_level=1)
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     assert content['found']
     text = content['data']['text/plain']
     nt.assert_in('Definition:', text)
     nt.assert_in('Source:', text)
 
 
 def test_oinfo_not_found():
     flush_channels()
 
     msg_id = KC.inspect('dne')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     nt.assert_false(content['found'])
 
 
 def test_complete():
     flush_channels()
 
     msg_id, reply = execute(code="alpha = albert = 5")
     
     msg_id = KC.complete('al', 2)
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'complete_reply', msg_id)
     matches = reply['content']['matches']
     for name in ('alpha', 'albert'):
         nt.assert_in(name, matches)
 
 
 def test_kernel_info_request():
     flush_channels()
 
     msg_id = KC.kernel_info()
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'kernel_info_reply', msg_id)
 
 
 def test_single_payload():
     flush_channels()
     msg_id, reply = execute(code="for i in range(3):\n"+
                                  "   x=range?\n")
     payload = reply['payload']
     next_input_pls = [pl for pl in payload if pl["source"] == "set_next_input"]
     nt.assert_equal(len(next_input_pls), 1)
 
 def test_is_complete():
     flush_channels()
     
     msg_id = KC.is_complete("a = 1")
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'is_complete_reply', msg_id)
 
 # IOPub channel
 
 
 def test_stream():
     flush_channels()
 
     msg_id, reply = execute("print('hi')")
 
     stdout = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(stdout, 'stream', msg_id)
     content = stdout['content']
     nt.assert_equal(content['text'], u'hi\n')
 
 
 def test_display_data():
     flush_channels()
 
     msg_id, reply = execute("from IPython.core.display import display; display(1)")
     
     display = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(display, 'display_data', parent=msg_id)
     data = display['content']['data']
     nt.assert_equal(data['text/plain'], u'1')
 

IPython/kernel/zmq/ipkernel.py

@@ -1,330 +1,331
 """The IPython kernel implementation"""
 
 import getpass
 import sys
 import traceback
 
 from IPython.core import release
 from IPython.html.widgets import Widget
 from IPython.utils.py3compat import builtin_mod, PY3
 from IPython.utils.tokenutil import token_at_cursor, line_at_cursor
 from IPython.utils.traitlets import Instance, Type, Any
 from IPython.utils.decorators import undoc
 
 from ..comm import CommManager
 from .kernelbase import Kernel as KernelBase
 from .serialize import serialize_object, unpack_apply_message
 from .zmqshell import ZMQInteractiveShell
 
 class IPythonKernel(KernelBase):
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     shell_class = Type(ZMQInteractiveShell)
 
     user_module = Any()
     def _user_module_changed(self, name, old, new):
         if self.shell is not None:
             self.shell.user_module = new
 
     user_ns = Instance(dict, args=None, allow_none=True)
     def _user_ns_changed(self, name, old, new):
         if self.shell is not None:
             self.shell.user_ns = new
             self.shell.init_user_ns()
 
     # A reference to the Python builtin 'raw_input' function.
     # (i.e., __builtin__.raw_input for Python 2.7, builtins.input for Python 3)
     _sys_raw_input = Any()
     _sys_eval_input = Any()
 
     def __init__(self, **kwargs):
         super(IPythonKernel, self).__init__(**kwargs)
 
         # Initialize the InteractiveShell subclass
         self.shell = self.shell_class.instance(parent=self,
             profile_dir = self.profile_dir,
             user_module = self.user_module,
             user_ns     = self.user_ns,
             kernel      = self,
         )
         self.shell.displayhook.session = self.session
         self.shell.displayhook.pub_socket = self.iopub_socket
         self.shell.displayhook.topic = self._topic('execute_result')
         self.shell.display_pub.session = self.session
         self.shell.display_pub.pub_socket = self.iopub_socket
         self.shell.data_pub.session = self.session
         self.shell.data_pub.pub_socket = self.iopub_socket
 
         # TMP - hack while developing
         self.shell._reply_content = None
 
         self.comm_manager = CommManager(shell=self.shell, parent=self, 
                                         kernel=self)
         self.comm_manager.register_target('ipython.widget', Widget.handle_comm_opened)
 
         self.shell.configurables.append(self.comm_manager)
         comm_msg_types = [ 'comm_open', 'comm_msg', 'comm_close' ]
         for msg_type in comm_msg_types:
             self.shell_handlers[msg_type] = getattr(self.comm_manager, msg_type)
 
     # Kernel info fields
     implementation = 'ipython'
     implementation_version = release.version
-    language = 'python'
-    language_version = sys.version.split()[0]
-    language_info = {'mimetype': 'text/x-python',
+    language_info = {
+                     'name': 'python',
+                     'version': sys.version.split()[0],
+                     'mimetype': 'text/x-python',
                      'codemirror_mode': {'name': 'ipython',
                                          'version': sys.version_info[0]},
                      'pygments_lexer': 'ipython%d' % (3 if PY3 else 2),
                      'nbconvert_exporter': 'python',
                      'file_extension': '.py'
                     }
     @property
     def banner(self):
         return self.shell.banner
 
     def start(self):
         self.shell.exit_now = False
         super(IPythonKernel, self).start()
 
     def set_parent(self, ident, parent):
         """Overridden from parent to tell the display hook and output streams
         about the parent message.
         """
         super(IPythonKernel, self).set_parent(ident, parent)
         self.shell.set_parent(parent)
 
     def _forward_input(self, allow_stdin=False):
         """Forward raw_input and getpass to the current frontend.
 
         via input_request
         """
         self._allow_stdin = allow_stdin
 
         if PY3:
             self._sys_raw_input = builtin_mod.input
             builtin_mod.input = self.raw_input
         else:
             self._sys_raw_input = builtin_mod.raw_input
             self._sys_eval_input = builtin_mod.input
             builtin_mod.raw_input = self.raw_input
             builtin_mod.input = lambda prompt='': eval(self.raw_input(prompt))
         self._save_getpass = getpass.getpass
         getpass.getpass = self.getpass
 
     def _restore_input(self):
         """Restore raw_input, getpass"""
         if PY3:
             builtin_mod.input = self._sys_raw_input
         else:
             builtin_mod.raw_input = self._sys_raw_input
             builtin_mod.input = self._sys_eval_input
 
         getpass.getpass = self._save_getpass
 
     @property
     def execution_count(self):
         return self.shell.execution_count
 
     @execution_count.setter
     def execution_count(self, value):
         # Ignore the incrememnting done by KernelBase, in favour of our shell's
         # execution counter.
         pass
 
     def do_execute(self, code, silent, store_history=True,
                    user_expressions=None, allow_stdin=False):
         shell = self.shell # we'll need this a lot here
 
         self._forward_input(allow_stdin)
 
         reply_content = {}
         # FIXME: the shell calls the exception handler itself.
         shell._reply_content = None
         try:
             shell.run_cell(code, store_history=store_history, silent=silent)
         except:
             status = u'error'
             # FIXME: this code right now isn't being used yet by default,
             # because the run_cell() call above directly fires off exception
             # reporting.  This code, therefore, is only active in the scenario
             # where runlines itself has an unhandled exception.  We need to
             # uniformize this, for all exception construction to come from a
             # single location in the codbase.
             etype, evalue, tb = sys.exc_info()
             tb_list = traceback.format_exception(etype, evalue, tb)
             reply_content.update(shell._showtraceback(etype, evalue, tb_list))
         else:
             status = u'ok'
         finally:
             self._restore_input()
 
         reply_content[u'status'] = status
 
         # Return the execution counter so clients can display prompts
         reply_content['execution_count'] = shell.execution_count - 1
 
         # FIXME - fish exception info out of shell, possibly left there by
         # runlines.  We'll need to clean up this logic later.
         if shell._reply_content is not None:
             reply_content.update(shell._reply_content)
             e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='execute')
             reply_content['engine_info'] = e_info
             # reset after use
             shell._reply_content = None
 
         if 'traceback' in reply_content:
             self.log.info("Exception in execute request:\n%s", '\n'.join(reply_content['traceback']))
 
 
         # At this point, we can tell whether the main code execution succeeded
         # or not.  If it did, we proceed to evaluate user_expressions
         if reply_content['status'] == 'ok':
             reply_content[u'user_expressions'] = \
                          shell.user_expressions(user_expressions or {})
         else:
             # If there was an error, don't even try to compute expressions
             reply_content[u'user_expressions'] = {}
 
         # Payloads should be retrieved regardless of outcome, so we can both
         # recover partial output (that could have been generated early in a
         # block, before an error) and clear the payload system always.
         reply_content[u'payload'] = shell.payload_manager.read_payload()
         # Be agressive about clearing the payload because we don't want
         # it to sit in memory until the next execute_request comes in.
         shell.payload_manager.clear_payload()
 
         return reply_content
 
     def do_complete(self, code, cursor_pos):
         # FIXME: IPython completers currently assume single line,
         # but completion messages give multi-line context
         # For now, extract line from cell, based on cursor_pos:
         if cursor_pos is None:
             cursor_pos = len(code)
         line, offset = line_at_cursor(code, cursor_pos)
         line_cursor = cursor_pos - offset
 
         txt, matches = self.shell.complete('', line, line_cursor)
         return {'matches' : matches,
                 'cursor_end' : cursor_pos,
                 'cursor_start' : cursor_pos - len(txt),
                 'metadata' : {},
                 'status' : 'ok'}
 
     def do_inspect(self, code, cursor_pos, detail_level=0):
         name = token_at_cursor(code, cursor_pos)
         info = self.shell.object_inspect(name)
 
         reply_content = {'status' : 'ok'}
         reply_content['data'] = data = {}
         reply_content['metadata'] = {}
         reply_content['found'] = info['found']
         if info['found']:
             info_text = self.shell.object_inspect_text(
                 name,
                 detail_level=detail_level,
             )
             data['text/plain'] = info_text
 
         return reply_content
 
     def do_history(self, hist_access_type, output, raw, session=None, start=None,
                    stop=None, n=None, pattern=None, unique=False):
         if hist_access_type == 'tail':
             hist = self.shell.history_manager.get_tail(n, raw=raw, output=output,
                                                             include_latest=True)
 
         elif hist_access_type == 'range':
             hist = self.shell.history_manager.get_range(session, start, stop,
                                                         raw=raw, output=output)
 
         elif hist_access_type == 'search':
             hist = self.shell.history_manager.search(
                 pattern, raw=raw, output=output, n=n, unique=unique)
         else:
             hist = []
 
         return {'history' : list(hist)}
 
     def do_shutdown(self, restart):
         self.shell.exit_now = True
         return dict(status='ok', restart=restart)
 
     def do_is_complete(self, code):
         status, indent_spaces = self.shell.input_transformer_manager.check_complete(code)
         r = {'status': status}
         if status == 'incomplete':
             r['indent'] = ' ' * indent_spaces
         return r
 
     def do_apply(self, content, bufs, msg_id, reply_metadata):
         shell = self.shell
         try:
             working = shell.user_ns
 
             prefix = "_"+str(msg_id).replace("-","")+"_"
 
             f,args,kwargs = unpack_apply_message(bufs, working, copy=False)
 
             fname = getattr(f, '__name__', 'f')
 
             fname = prefix+"f"
             argname = prefix+"args"
             kwargname = prefix+"kwargs"
             resultname = prefix+"result"
 
             ns = { fname : f, argname : args, kwargname : kwargs , resultname : None }
             # print ns
             working.update(ns)
             code = "%s = %s(*%s,**%s)" % (resultname, fname, argname, kwargname)
             try:
                 exec(code, shell.user_global_ns, shell.user_ns)
                 result = working.get(resultname)
             finally:
                 for key in ns:
                     working.pop(key)
 
             result_buf = serialize_object(result,
                 buffer_threshold=self.session.buffer_threshold,
                 item_threshold=self.session.item_threshold,
             )
 
         except:
             # invoke IPython traceback formatting
             shell.showtraceback()
             # FIXME - fish exception info out of shell, possibly left there by
             # run_code.  We'll need to clean up this logic later.
             reply_content = {}
             if shell._reply_content is not None:
                 reply_content.update(shell._reply_content)
                 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='apply')
                 reply_content['engine_info'] = e_info
                 # reset after use
                 shell._reply_content = None
 
             self.send_response(self.iopub_socket, u'error', reply_content,
                                 ident=self._topic('error'))
             self.log.info("Exception in apply request:\n%s", '\n'.join(reply_content['traceback']))
             result_buf = []
 
             if reply_content['ename'] == 'UnmetDependency':
                 reply_metadata['dependencies_met'] = False
         else:
             reply_content = {'status' : 'ok'}
 
         return reply_content, result_buf
 
     def do_clear(self):
         self.shell.reset(False)
         return dict(status='ok')
 
 
 # This exists only for backwards compatibility - use IPythonKernel instead
 
 @undoc
 class Kernel(IPythonKernel):
     def __init__(self, *args, **kwargs):
         import warnings
         warnings.warn('Kernel is a deprecated alias of IPython.kernel.zmq.ipkernel.IPythonKernel',
                       DeprecationWarning)
         super(Kernel, self).__init__(*args, **kwargs)
  No newline at end of file

IPython/kernel/zmq/kernelbase.py

@@ -1,697 +1,695
 """Base class for a kernel that talks to frontends over 0MQ."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import sys
 import time
 import logging
 import uuid
 
 from datetime import datetime
 from signal import (
         signal, default_int_handler, SIGINT
 )
 
 import zmq
 from zmq.eventloop import ioloop
 from zmq.eventloop.zmqstream import ZMQStream
 
 from IPython.config.configurable import SingletonConfigurable
 from IPython.core.error import StdinNotImplementedError
 from IPython.core import release
 from IPython.utils import py3compat
 from IPython.utils.py3compat import unicode_type, string_types
 from IPython.utils.jsonutil import json_clean
 from IPython.utils.traitlets import (
     Any, Instance, Float, Dict, List, Set, Integer, Unicode, Bool,
 )
 
 from .session import Session
 
 
 class Kernel(SingletonConfigurable):
 
     #---------------------------------------------------------------------------
     # Kernel interface
     #---------------------------------------------------------------------------
 
     # attribute to override with a GUI
     eventloop = Any(None)
     def _eventloop_changed(self, name, old, new):
         """schedule call to eventloop from IOLoop"""
         loop = ioloop.IOLoop.instance()
         loop.add_callback(self.enter_eventloop)
 
     session = Instance(Session)
     profile_dir = Instance('IPython.core.profiledir.ProfileDir')
     shell_streams = List()
     control_stream = Instance(ZMQStream)
     iopub_socket = Instance(zmq.Socket)
     stdin_socket = Instance(zmq.Socket)
     log = Instance(logging.Logger)
 
     # identities:
     int_id = Integer(-1)
     ident = Unicode()
 
     def _ident_default(self):
         return unicode_type(uuid.uuid4())
 
     # This should be overridden by wrapper kernels that implement any real
     # language.
     language_info = {}
 
     # Private interface
     
     _darwin_app_nap = Bool(True, config=True,
         help="""Whether to use appnope for compatiblity with OS X App Nap.
         
         Only affects OS X >= 10.9.
         """
     )
 
     # track associations with current request
     _allow_stdin = Bool(False)
     _parent_header = Dict()
     _parent_ident = Any(b'')
     # Time to sleep after flushing the stdout/err buffers in each execute
     # cycle.  While this introduces a hard limit on the minimal latency of the
     # execute cycle, it helps prevent output synchronization problems for
     # clients.
     # Units are in seconds.  The minimum zmq latency on local host is probably
     # ~150 microseconds, set this to 500us for now.  We may need to increase it
     # a little if it's not enough after more interactive testing.
     _execute_sleep = Float(0.0005, config=True)
 
     # Frequency of the kernel's event loop.
     # Units are in seconds, kernel subclasses for GUI toolkits may need to
     # adapt to milliseconds.
     _poll_interval = Float(0.05, config=True)
 
     # If the shutdown was requested over the network, we leave here the
     # necessary reply message so it can be sent by our registered atexit
     # handler.  This ensures that the reply is only sent to clients truly at
     # the end of our shutdown process (which happens after the underlying
     # IPython shell's own shutdown).
     _shutdown_message = None
 
     # This is a dict of port number that the kernel is listening on. It is set
     # by record_ports and used by connect_request.
     _recorded_ports = Dict()
 
     # set of aborted msg_ids
     aborted = Set()
 
     # Track execution count here. For IPython, we override this to use the
     # execution count we store in the shell.
     execution_count = 0
 
 
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
 
         # Build dict of handlers for message types
         msg_types = [ 'execute_request', 'complete_request',
                       'inspect_request', 'history_request',
                       'kernel_info_request',
                       'connect_request', 'shutdown_request',
                       'apply_request', 'is_complete_request',
                     ]
         self.shell_handlers = {}
         for msg_type in msg_types:
             self.shell_handlers[msg_type] = getattr(self, msg_type)
         
         control_msg_types = msg_types + [ 'clear_request', 'abort_request' ]
         self.control_handlers = {}
         for msg_type in control_msg_types:
             self.control_handlers[msg_type] = getattr(self, msg_type)
 
     
     def dispatch_control(self, msg):
         """dispatch control requests"""
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.deserialize(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Control Message", exc_info=True)
             return
 
         self.log.debug("Control received: %s", msg)
         
         # Set the parent message for side effects.
         self.set_parent(idents, msg)
         self._publish_status(u'busy')
         
         header = msg['header']
         msg_type = header['msg_type']
 
         handler = self.control_handlers.get(msg_type, None)
         if handler is None:
             self.log.error("UNKNOWN CONTROL MESSAGE TYPE: %r", msg_type)
         else:
             try:
                 handler(self.control_stream, idents, msg)
             except Exception:
                 self.log.error("Exception in control handler:", exc_info=True)
         
         sys.stdout.flush()
         sys.stderr.flush()
         self._publish_status(u'idle')
     
     def dispatch_shell(self, stream, msg):
         """dispatch shell requests"""
         # flush control requests first
         if self.control_stream:
             self.control_stream.flush()
         
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.deserialize(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Message", exc_info=True)
             return
 
         # Set the parent message for side effects.
         self.set_parent(idents, msg)
         self._publish_status(u'busy')
         
         header = msg['header']
         msg_id = header['msg_id']
         msg_type = msg['header']['msg_type']
         
         # Print some info about this message and leave a '--->' marker, so it's
         # easier to trace visually the message chain when debugging.  Each
         # handler prints its message at the end.
         self.log.debug('\n*** MESSAGE TYPE:%s***', msg_type)
         self.log.debug('   Content: %s\n   --->\n   ', msg['content'])
 
         if msg_id in self.aborted:
             self.aborted.remove(msg_id)
             # is it safe to assume a msg_id will not be resubmitted?
             reply_type = msg_type.split('_')[0] + '_reply'
             status = {'status' : 'aborted'}
             md = {'engine' : self.ident}
             md.update(status)
             self.session.send(stream, reply_type, metadata=md,
                         content=status, parent=msg, ident=idents)
             return
         
         handler = self.shell_handlers.get(msg_type, None)
         if handler is None:
             self.log.error("UNKNOWN MESSAGE TYPE: %r", msg_type)
         else:
             # ensure default_int_handler during handler call
             sig = signal(SIGINT, default_int_handler)
             self.log.debug("%s: %s", msg_type, msg)
             try:
                 handler(stream, idents, msg)
             except Exception:
                 self.log.error("Exception in message handler:", exc_info=True)
             finally:
                 signal(SIGINT, sig)
         
         sys.stdout.flush()
         sys.stderr.flush()
         self._publish_status(u'idle')
     
     def enter_eventloop(self):
         """enter eventloop"""
         self.log.info("entering eventloop %s", self.eventloop)
         for stream in self.shell_streams:
             # flush any pending replies,
             # which may be skipped by entering the eventloop
             stream.flush(zmq.POLLOUT)
         # restore default_int_handler
         signal(SIGINT, default_int_handler)
         while self.eventloop is not None:
             try:
                 self.eventloop(self)
             except KeyboardInterrupt:
                 # Ctrl-C shouldn't crash the kernel
                 self.log.error("KeyboardInterrupt caught in kernel")
                 continue
             else:
                 # eventloop exited cleanly, this means we should stop (right?)
                 self.eventloop = None
                 break
         self.log.info("exiting eventloop")
 
     def start(self):
         """register dispatchers for streams"""
         if self.control_stream:
             self.control_stream.on_recv(self.dispatch_control, copy=False)
 
         def make_dispatcher(stream):
             def dispatcher(msg):
                 return self.dispatch_shell(stream, msg)
             return dispatcher
 
         for s in self.shell_streams:
             s.on_recv(make_dispatcher(s), copy=False)
 
         # publish idle status
         self._publish_status('starting')
     
     def do_one_iteration(self):
         """step eventloop just once"""
         if self.control_stream:
             self.control_stream.flush()
         for stream in self.shell_streams:
             # handle at most one request per iteration
             stream.flush(zmq.POLLIN, 1)
             stream.flush(zmq.POLLOUT)
 
 
     def record_ports(self, ports):
         """Record the ports that this kernel is using.
 
         The creator of the Kernel instance must call this methods if they
         want the :meth:`connect_request` method to return the port numbers.
         """
         self._recorded_ports = ports
 
     #---------------------------------------------------------------------------
     # Kernel request handlers
     #---------------------------------------------------------------------------
     
     def _make_metadata(self, other=None):
         """init metadata dict, for execute/apply_reply"""
         new_md = {
             'dependencies_met' : True,
             'engine' : self.ident,
             'started': datetime.now(),
         }
         if other:
             new_md.update(other)
         return new_md
     
     def _publish_execute_input(self, code, parent, execution_count):
         """Publish the code request on the iopub stream."""
 
         self.session.send(self.iopub_socket, u'execute_input',
                             {u'code':code, u'execution_count': execution_count},
                             parent=parent, ident=self._topic('execute_input')
         )
     
     def _publish_status(self, status, parent=None):
         """send status (busy/idle) on IOPub"""
         self.session.send(self.iopub_socket,
                           u'status',
                           {u'execution_state': status},
                           parent=parent or self._parent_header,
                           ident=self._topic('status'),
                           )
     
     def set_parent(self, ident, parent):
         """Set the current parent_header
         
         Side effects (IOPub messages) and replies are associated with
         the request that caused them via the parent_header.
         
         The parent identity is used to route input_request messages
         on the stdin channel.
         """
         self._parent_ident = ident
         self._parent_header = parent
     
     def send_response(self, stream, msg_or_type, content=None, ident=None,
              buffers=None, track=False, header=None, metadata=None):
         """Send a response to the message we're currently processing.
         
         This accepts all the parameters of :meth:`IPython.kernel.zmq.session.Session.send`
         except ``parent``.
         
         This relies on :meth:`set_parent` having been called for the current
         message.
         """
         return self.session.send(stream, msg_or_type, content, self._parent_header,
                                  ident, buffers, track, header, metadata)
     
     def execute_request(self, stream, ident, parent):
         """handle an execute_request"""
         
         try:
             content = parent[u'content']
             code = py3compat.cast_unicode_py2(content[u'code'])
             silent = content[u'silent']
             store_history = content.get(u'store_history', not silent)
             user_expressions = content.get('user_expressions', {})
             allow_stdin = content.get('allow_stdin', False)
         except:
             self.log.error("Got bad msg: ")
             self.log.error("%s", parent)
             return
         
         md = self._make_metadata(parent['metadata'])
         
         # Re-broadcast our input for the benefit of listening clients, and
         # start computing output
         if not silent:
             self.execution_count += 1
             self._publish_execute_input(code, parent, self.execution_count)
         
         reply_content = self.do_execute(code, silent, store_history,
                                         user_expressions, allow_stdin)
 
         # Flush output before sending the reply.
         sys.stdout.flush()
         sys.stderr.flush()
         # FIXME: on rare occasions, the flush doesn't seem to make it to the
         # clients... This seems to mitigate the problem, but we definitely need
         # to better understand what's going on.
         if self._execute_sleep:
             time.sleep(self._execute_sleep)
 
         # Send the reply.
         reply_content = json_clean(reply_content)
         
         md['status'] = reply_content['status']
         if reply_content['status'] == 'error' and \
                         reply_content['ename'] == 'UnmetDependency':
                 md['dependencies_met'] = False
 
         reply_msg = self.session.send(stream, u'execute_reply',
                                       reply_content, parent, metadata=md,
                                       ident=ident)
         
         self.log.debug("%s", reply_msg)
 
         if not silent and reply_msg['content']['status'] == u'error':
             self._abort_queues()
 
     def do_execute(self, code, silent, store_history=True,
                    user_experssions=None, allow_stdin=False):
         """Execute user code. Must be overridden by subclasses.
         """
         raise NotImplementedError
 
     def complete_request(self, stream, ident, parent):
         content = parent['content']
         code = content['code']
         cursor_pos = content['cursor_pos']
         
         matches = self.do_complete(code, cursor_pos)
         matches = json_clean(matches)
         completion_msg = self.session.send(stream, 'complete_reply',
                                            matches, parent, ident)
         self.log.debug("%s", completion_msg)
 
     def do_complete(self, code, cursor_pos):
         """Override in subclasses to find completions.
         """
         return {'matches' : [],
                 'cursor_end' : cursor_pos,
                 'cursor_start' : cursor_pos,
                 'metadata' : {},
                 'status' : 'ok'}
 
     def inspect_request(self, stream, ident, parent):
         content = parent['content']
         
         reply_content = self.do_inspect(content['code'], content['cursor_pos'],
                                         content.get('detail_level', 0))
         # Before we send this object over, we scrub it for JSON usage
         reply_content = json_clean(reply_content)
         msg = self.session.send(stream, 'inspect_reply',
                                 reply_content, parent, ident)
         self.log.debug("%s", msg)
 
     def do_inspect(self, code, cursor_pos, detail_level=0):
         """Override in subclasses to allow introspection.
         """
         return {'status': 'ok', 'data':{}, 'metadata':{}, 'found':False}
 
     def history_request(self, stream, ident, parent):
         content = parent['content']
 
         reply_content = self.do_history(**content)
 
         reply_content = json_clean(reply_content)
         msg = self.session.send(stream, 'history_reply',
                                 reply_content, parent, ident)
         self.log.debug("%s", msg)
 
     def do_history(self, hist_access_type, output, raw, session=None, start=None,
                    stop=None, n=None, pattern=None, unique=False):
         """Override in subclasses to access history.
         """
         return {'history': []}
 
     def connect_request(self, stream, ident, parent):
         if self._recorded_ports is not None:
             content = self._recorded_ports.copy()
         else:
             content = {}
         msg = self.session.send(stream, 'connect_reply',
                                 content, parent, ident)
         self.log.debug("%s", msg)
 
     @property
     def kernel_info(self):
         return {
             'protocol_version': release.kernel_protocol_version,
             'implementation': self.implementation,
             'implementation_version': self.implementation_version,
-            'language': self.language,
-            'language_version': self.language_version,
             'language_info': self.language_info,
             'banner': self.banner,
         }
 
     def kernel_info_request(self, stream, ident, parent):
         msg = self.session.send(stream, 'kernel_info_reply',
                                 self.kernel_info, parent, ident)
         self.log.debug("%s", msg)
 
     def shutdown_request(self, stream, ident, parent):
         content = self.do_shutdown(parent['content']['restart'])
         self.session.send(stream, u'shutdown_reply', content, parent, ident=ident)
         # same content, but different msg_id for broadcasting on IOPub
         self._shutdown_message = self.session.msg(u'shutdown_reply',
                                                   content, parent
         )
 
         self._at_shutdown()
         # call sys.exit after a short delay
         loop = ioloop.IOLoop.instance()
         loop.add_timeout(time.time()+0.1, loop.stop)
 
     def do_shutdown(self, restart):
         """Override in subclasses to do things when the frontend shuts down the
         kernel.
         """
         return {'status': 'ok', 'restart': restart}
     
     def is_complete_request(self, stream, ident, parent):
         content = parent['content']
         code = content['code']
         
         reply_content = self.do_is_complete(code)
         reply_content = json_clean(reply_content)
         reply_msg = self.session.send(stream, 'is_complete_reply',
                                            reply_content, parent, ident)
         self.log.debug("%s", reply_msg)
 
     def do_is_complete(self, code):
         """Override in subclasses to find completions.
         """
         return {'status' : 'unknown',
                 }
 
     #---------------------------------------------------------------------------
     # Engine methods
     #---------------------------------------------------------------------------
 
     def apply_request(self, stream, ident, parent):
         try:
             content = parent[u'content']
             bufs = parent[u'buffers']
             msg_id = parent['header']['msg_id']
         except:
             self.log.error("Got bad msg: %s", parent, exc_info=True)
             return
 
         md = self._make_metadata(parent['metadata'])
 
         reply_content, result_buf = self.do_apply(content, bufs, msg_id, md)
 
         # put 'ok'/'error' status in header, for scheduler introspection:
         md['status'] = reply_content['status']
 
         # flush i/o
         sys.stdout.flush()
         sys.stderr.flush()
         
         self.session.send(stream, u'apply_reply', reply_content,
                     parent=parent, ident=ident,buffers=result_buf, metadata=md)
 
     def do_apply(self, content, bufs, msg_id, reply_metadata):
         """Override in subclasses to support the IPython parallel framework.
         """
         raise NotImplementedError
 
     #---------------------------------------------------------------------------
     # Control messages
     #---------------------------------------------------------------------------
 
     def abort_request(self, stream, ident, parent):
         """abort a specific msg by id"""
         msg_ids = parent['content'].get('msg_ids', None)
         if isinstance(msg_ids, string_types):
             msg_ids = [msg_ids]
         if not msg_ids:
             self._abort_queues()
         for mid in msg_ids:
             self.aborted.add(str(mid))
 
         content = dict(status='ok')
         reply_msg = self.session.send(stream, 'abort_reply', content=content,
                 parent=parent, ident=ident)
         self.log.debug("%s", reply_msg)
 
     def clear_request(self, stream, idents, parent):
         """Clear our namespace."""
         content = self.do_clear()
         self.session.send(stream, 'clear_reply', ident=idents, parent=parent,
                 content = content)
 
     def do_clear(self):
         """Override in subclasses to clear the namespace
         
         This is only required for IPython.parallel.
         """
         raise NotImplementedError
 
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
 
     def _topic(self, topic):
         """prefixed topic for IOPub messages"""
         if self.int_id >= 0:
             base = "engine.%i" % self.int_id
         else:
             base = "kernel.%s" % self.ident
         
         return py3compat.cast_bytes("%s.%s" % (base, topic))
     
     def _abort_queues(self):
         for stream in self.shell_streams:
             if stream:
                 self._abort_queue(stream)
 
     def _abort_queue(self, stream):
         poller = zmq.Poller()
         poller.register(stream.socket, zmq.POLLIN)
         while True:
             idents,msg = self.session.recv(stream, zmq.NOBLOCK, content=True)
             if msg is None:
                 return
 
             self.log.info("Aborting:")
             self.log.info("%s", msg)
             msg_type = msg['header']['msg_type']
             reply_type = msg_type.split('_')[0] + '_reply'
 
             status = {'status' : 'aborted'}
             md = {'engine' : self.ident}
             md.update(status)
             reply_msg = self.session.send(stream, reply_type, metadata=md,
                         content=status, parent=msg, ident=idents)
             self.log.debug("%s", reply_msg)
             # We need to wait a bit for requests to come in. This can probably
             # be set shorter for true asynchronous clients.
             poller.poll(50)
 
 
     def _no_raw_input(self):
         """Raise StdinNotImplentedError if active frontend doesn't support
         stdin."""
         raise StdinNotImplementedError("raw_input was called, but this "
                                        "frontend does not support stdin.") 
     
     def getpass(self, prompt=''):
         """Forward getpass to frontends
         
         Raises
         ------
         StdinNotImplentedError if active frontend doesn't support stdin.
         """
         if not self._allow_stdin:
             raise StdinNotImplementedError(
                 "getpass was called, but this frontend does not support input requests."
             )
         return self._input_request(prompt,
             self._parent_ident,
             self._parent_header,
             password=True,
         )
     
     def raw_input(self, prompt=''):
         """Forward raw_input to frontends
         
         Raises
         ------
         StdinNotImplentedError if active frontend doesn't support stdin.
         """
         if not self._allow_stdin:
             raise StdinNotImplementedError(
                 "raw_input was called, but this frontend does not support input requests."
             )
         return self._input_request(prompt,
             self._parent_ident,
             self._parent_header,
             password=False,
         )
     
     def _input_request(self, prompt, ident, parent, password=False):
         # Flush output before making the request.
         sys.stderr.flush()
         sys.stdout.flush()
         # flush the stdin socket, to purge stale replies
         while True:
             try:
                 self.stdin_socket.recv_multipart(zmq.NOBLOCK)
             except zmq.ZMQError as e:
                 if e.errno == zmq.EAGAIN:
                     break
                 else:
                     raise
         
         # Send the input request.
         content = json_clean(dict(prompt=prompt, password=password))
         self.session.send(self.stdin_socket, u'input_request', content, parent,
                           ident=ident)
 
         # Await a response.
         while True:
             try:
                 ident, reply = self.session.recv(self.stdin_socket, 0)
             except Exception:
                 self.log.warn("Invalid Message:", exc_info=True)
             except KeyboardInterrupt:
                 # re-raise KeyboardInterrupt, to truncate traceback
                 raise KeyboardInterrupt
             else:
                 break
         try:
             value = py3compat.unicode_to_str(reply['content']['value'])
         except:
             self.log.error("Bad input_reply: %s", parent)
             value = ''
         if value == '\x04':
             # EOF
             raise EOFError
         return value
 
     def _at_shutdown(self):
         """Actions taken at shutdown by the kernel, called by python's atexit.
         """
         # io.rprint("Kernel at_shutdown") # dbg
         if self._shutdown_message is not None:
             self.session.send(self.iopub_socket, self._shutdown_message, ident=self._topic('shutdown'))
             self.log.debug("%s", self._shutdown_message)
         [ s.flush(zmq.POLLOUT) for s in self.shell_streams ]

IPython/nbformat/v4/nbformat.v4.schema.json

@@ -1,349 +1,375
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "description": "IPython Notebook v4.0 JSON schema.",
     "type": "object",
     "additionalProperties": false,
     "required": ["metadata", "nbformat_minor", "nbformat", "cells"],
     "properties": {
         "metadata": {
             "description": "Notebook root-level metadata.",
             "type": "object",
             "additionalProperties": true,
             "properties": {
-                "kernel_info": {
+                "kernelspec": {
                     "description": "Kernel information.",
                     "type": "object",
-                    "required": ["name", "language"],
+                    "required": ["name", "display_name"],
                     "properties": {
                         "name": {
                             "description": "Name of the kernel specification.",
                             "type": "string"
                         },
-                        "language": {
+                        "display_name": {
+                            "description": "Name to display in UI.",
+                            "type": "string"
+                        }
+                    }
+                },
+                "language_info": {
+                  "description": "Kernel information.",
+                  "type": "object",
+                  "required": ["name"],
+                  "properties": {
+                    "name": {
                             "description": "The programming language which this kernel runs.",
                             "type": "string"
                         },
                         "codemirror_mode": {
                             "description": "The codemirror mode to use for code in this language.",
+                        "oneOf": [
+                          {"type": "string"},
+                          {"type": "object"}
+                        ]
+                    },
+                    "file_extension": {
+                        "description": "The file extension for files in this language.",
+                        "type": "string"
+                    },
+                    "mimetype": {
+                        "description": "The mimetype corresponding to files in this language.",
+                        "type": "string"
+                    },
+                    "pygments_lexer": {
+                        "description": "The pygments lexer to use for code in this language.",
                             "type": "string"
                         }
                     }
                 },
                 "signature": {
                     "description": "Hash of the notebook.",
                     "type": "string"
                 },
                 "orig_nbformat": {
                     "description": "Original notebook format (major number) before converting the notebook between versions. This should never be written to a file.",
                     "type": "integer",
                     "minimum": 1
                 }
             }
         },
         "nbformat_minor": {
             "description": "Notebook format (minor number). Incremented for backward compatible changes to the notebook format.",
             "type": "integer",
             "minimum": 0
         },
         "nbformat": {
             "description": "Notebook format (major number). Incremented between backwards incompatible changes to the notebook format.",
             "type": "integer",
             "minimum": 4,
             "maximum": 4
         },
         "cells": {
             "description": "Array of cells of the current notebook.",
             "type": "array",
             "items": {"$ref": "#/definitions/cell"}
         }
     },
 
     "definitions": {
         "cell": {
             "type": "object",
             "oneOf": [
                 {"$ref": "#/definitions/raw_cell"},
                 {"$ref": "#/definitions/markdown_cell"},
                 {"$ref": "#/definitions/code_cell"}
             ]
         },
 
         "raw_cell": {
             "description": "Notebook raw nbconvert cell.",
             "type": "object",
             "additionalProperties": false,
             "required": ["cell_type", "metadata", "source"],
             "properties": {
                 "cell_type": {
                     "description": "String identifying the type of cell.",
                     "enum": ["raw"]
                 },
                 "metadata": {
                     "description": "Cell-level metadata.",
                     "type": "object",
                     "additionalProperties": true,
                     "properties": {
                         "format": {
                             "description": "Raw cell metadata format for nbconvert.",
                             "type": "string"
                         },
                         "name": {"$ref": "#/definitions/misc/metadata_name"},
                         "tags": {"$ref": "#/definitions/misc/metadata_tags"}
                     }
                 },
                 "source": {"$ref": "#/definitions/misc/source"}
             }
         },
 
         "markdown_cell": {
             "description": "Notebook markdown cell.",
             "type": "object",
             "additionalProperties": false,
             "required": ["cell_type", "metadata", "source"],
             "properties": {
                 "cell_type": {
                     "description": "String identifying the type of cell.",
                     "enum": ["markdown"]
                 },
                 "metadata": {
                     "description": "Cell-level metadata.",
                     "type": "object",
                     "properties": {
                         "name": {"$ref": "#/definitions/misc/metadata_name"},
                         "tags": {"$ref": "#/definitions/misc/metadata_tags"}
                     },
                     "additionalProperties": true
                 },
                 "source": {"$ref": "#/definitions/misc/source"}
             }
         },
 
         "code_cell": {
             "description": "Notebook code cell.",
             "type": "object",
             "additionalProperties": false,
             "required": ["cell_type", "metadata", "source", "outputs", "execution_count"],
             "properties": {
                 "cell_type": {
                     "description": "String identifying the type of cell.",
                     "enum": ["code"]
                 },
                 "metadata": {
                     "description": "Cell-level metadata.",
                     "type": "object",
                     "additionalProperties": true,
                     "properties": {
                         "collapsed": {
                             "description": "Whether the cell is collapsed/expanded.",
                             "type": "boolean"
                         },
                         "autoscroll": {
                             "description": "Whether the cell's output is scrolled, unscrolled, or autoscrolled.",
                             "enum": [true, false, "auto"]
                         },
                         "name": {"$ref": "#/definitions/misc/metadata_name"},
                         "tags": {"$ref": "#/definitions/misc/metadata_tags"}
                     }
                 },
                 "source": {"$ref": "#/definitions/misc/source"},
                 "outputs": {
                     "description": "Execution, display, or stream outputs.",
                     "type": "array",
                     "items": {"$ref": "#/definitions/output"}
                 },
                 "execution_count": {
                     "description": "The code cell's prompt number. Will be null if the cell has not been run.",
                     "type": ["integer", "null"],
                     "minimum": 0
                 }
             }
         },
         
         "unrecognized_cell": {
             "description": "Unrecognized cell from a future minor-revision to the notebook format.",
             "type": "object",
             "additionalProperties": true,
             "required": ["cell_type", "metadata"],
             "properties": {
                 "cell_type": {
                     "description": "String identifying the type of cell.",
                     "not" : {
                       "enum": ["markdown", "code", "raw"]
                     }
                 },
                 "metadata": {
                     "description": "Cell-level metadata.",
                     "type": "object",
                     "properties": {
                         "name": {"$ref": "#/definitions/misc/metadata_name"},
                         "tags": {"$ref": "#/definitions/misc/metadata_tags"}
                     },
                     "additionalProperties": true
                 }
             }
         },
         
         "output": {
             "type": "object",
             "oneOf": [
                 {"$ref": "#/definitions/execute_result"},
                 {"$ref": "#/definitions/display_data"},
                 {"$ref": "#/definitions/stream"},
                 {"$ref": "#/definitions/error"}
             ]
         },
 
         "execute_result": {
             "description": "Result of executing a code cell.",
             "type": "object",
             "additionalProperties": false,
             "required": ["output_type", "data", "metadata", "execution_count"],
             "properties": {
                 "output_type": {
                     "description": "Type of cell output.",
                     "enum": ["execute_result"]
                 },
                 "execution_count": {
                     "description": "A result's prompt number.",
                     "type": ["integer", "null"],
                     "minimum": 0
                 },
                 "data": {"$ref": "#/definitions/misc/mimebundle"},
                 "metadata": {"$ref": "#/definitions/misc/output_metadata"}
             }
         },
 
         "display_data": {
             "description": "Data displayed as a result of code cell execution.",
             "type": "object",
             "additionalProperties": false,
             "required": ["output_type", "data", "metadata"],
             "properties": {
                 "output_type": {
                     "description": "Type of cell output.",
                     "enum": ["display_data"]
                 },
                 "data": {"$ref": "#/definitions/misc/mimebundle"},
                 "metadata": {"$ref": "#/definitions/misc/output_metadata"}
             }
         },
 
         "stream": {
             "description": "Stream output from a code cell.",
             "type": "object",
             "additionalProperties": false,
             "required": ["output_type", "name", "text"],
             "properties": {
                 "output_type": {
                     "description": "Type of cell output.",
                     "enum": ["stream"]
                 },
                 "name": {
                     "description": "The name of the stream (stdout, stderr).",
                     "type": "string"
                 },
                 "text": {
                     "description": "The stream's text output, represented as an array of strings.",
                     "$ref": "#/definitions/misc/multiline_string"
                 }
             }
         },
 
         "error": {
             "description": "Output of an error that occurred during code cell execution.",
             "type": "object",
             "additionalProperties": false,
             "required": ["output_type", "ename", "evalue", "traceback"],
             "properties": {
                 "output_type": {
                     "description": "Type of cell output.",
                     "enum": ["error"]
                 },
                 "ename": {
                     "description": "The name of the error.",
                     "type": "string"
                 },
                 "evalue": {
                     "description": "The value, or message, of the error.",
                     "type": "string"
                 },
                 "traceback": {
                     "description": "The error's traceback, represented as an array of strings.",
                     "type": "array",
                     "items": {"type": "string"}
                 }
             }
         },
 
         "unrecognized_output": {
             "description": "Unrecognized output from a future minor-revision to the notebook format.",
             "type": "object",
             "additionalProperties": true,
             "required": ["output_type"],
             "properties": {
                 "output_type": {
                     "description": "Type of cell output.",
                     "not": {
                         "enum": ["execute_result", "display_data", "stream", "error"]
                     }
                 }
             }
         },
 
         "misc": {
             "metadata_name": {
                 "description": "The cell's name. If present, must be a non-empty string.",
                 "type": "string",
                 "pattern": "^.+$"
             },
             "metadata_tags": {
                 "description": "The cell's tags. Tags must be unique, and must not contain commas.",
                 "type": "array",
                 "uniqueItems": true,
                 "items": {
                     "type": "string",
                     "pattern": "^[^,]+$"
                 }
             },
             "source": {
                 "description": "Contents of the cell, represented as an array of lines.",
                 "$ref": "#/definitions/misc/multiline_string"
             },
             "execution_count": {
                 "description": "The code cell's prompt number. Will be null if the cell has not been run.",
                 "type": ["integer", "null"],
                 "minimum": 0
             },
             "mimebundle": {
                 "description": "A mime-type keyed dictionary of data",
                 "type": "object",
                 "additionalProperties": false,
                 "properties": {
                     "application/json": {
                         "type": "object"
                     }
                 },
                 "patternProperties": {
                     "^(?!application/json$)[a-zA-Z0-9]+/[a-zA-Z0-9\\-\\+\\.]+$": {
                         "description": "mimetype output (e.g. text/plain), represented as either an array of strings or a string.",
                         "$ref": "#/definitions/misc/multiline_string"
                     }
                 }
             },
             "output_metadata": {
                 "description": "Cell output metadata.",
                 "type": "object",
                 "additionalProperties": true
             },
             "multiline_string": {
                 "oneOf" : [
                     {"type": "string"},
                     {
                         "type": "array",
                         "items": {"type": "string"}
                     }
                 ]
             }
         }
     }
 }

docs/source/development/messaging.rst

@@ -1,1192 +1,1201
 .. _messaging:
 
 ======================
  Messaging in IPython
 ======================
 
 
 Versioning
 ==========
 
 The IPython message specification is versioned independently of IPython.
 The current version of the specification is 5.0.
 
 
 Introduction
 ============
 
 This document explains the basic communications design and messaging
 specification for how the various IPython objects interact over a network
 transport.  The current implementation uses the ZeroMQ_ library for messaging
 within and between hosts.
 
 .. Note::
 
    This document should be considered the authoritative description of the
    IPython messaging protocol, and all developers are strongly encouraged to
    keep it updated as the implementation evolves, so that we have a single
    common reference for all protocol details.
 
 The basic design is explained in the following diagram:
 
 .. image:: figs/frontend-kernel.png
    :width: 450px
    :alt: IPython kernel/frontend messaging architecture.
    :align: center
    :target: ../_images/frontend-kernel.png
 
 A single kernel can be simultaneously connected to one or more frontends.  The
 kernel has three sockets that serve the following functions:
 
 1. Shell: this single ROUTER socket allows multiple incoming connections from
    frontends, and this is the socket where requests for code execution, object
    information, prompts, etc. are made to the kernel by any frontend.  The
    communication on this socket is a sequence of request/reply actions from
    each frontend and the kernel.
 
 2. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
    side effects (stdout, stderr, etc.) as well as the requests coming from any
    client over the shell socket and its own requests on the stdin socket.  There
    are a number of actions in Python which generate side effects: :func:`print`
    writes to ``sys.stdout``, errors generate tracebacks, etc.  Additionally, in
    a multi-client scenario, we want all frontends to be able to know what each
    other has sent to the kernel (this can be useful in collaborative scenarios,
    for example).  This socket allows both side effects and the information
    about communications taking place with one client over the shell channel
    to be made available to all clients in a uniform manner.
 
 3. stdin: this ROUTER socket is connected to all frontends, and it allows
    the kernel to request input from the active frontend when :func:`raw_input` is called.
    The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
    for the kernel while this communication is happening (illustrated in the
    figure by the black outline around the central keyboard).  In practice,
    frontends may display such kernel requests using a special input widget or
    otherwise indicating that the user is to type input for the kernel instead
    of normal commands in the frontend.
 
    All messages are tagged with enough information (details below) for clients
    to know which messages come from their own interaction with the kernel and
    which ones are from other clients, so they can display each type
    appropriately.
 
 4. Control: This channel is identical to Shell, but operates on a separate socket,
    to allow important messages to avoid queueing behind execution requests (e.g. shutdown or abort).
 
 The actual format of the messages allowed on each of these channels is
 specified below.  Messages are dicts of dicts with string keys and values that
 are reasonably representable in JSON.  Our current implementation uses JSON
 explicitly as its message format, but this shouldn't be considered a permanent
 feature.  As we've discovered that JSON has non-trivial performance issues due
 to excessive copying, we may in the future move to a pure pickle-based raw
 message format.  However, it should be possible to easily convert from the raw
 objects to JSON, since we may have non-python clients (e.g. a web frontend).
 As long as it's easy to make a JSON version of the objects that is a faithful
 representation of all the data, we can communicate with such clients.
 
 .. Note::
 
    Not all of these have yet been fully fleshed out, but the key ones are, see
    kernel and frontend files for actual implementation details.
 
 General Message Format
 ======================
 
 A message is defined by the following four-dictionary structure::
 
     {
       # The message header contains a pair of unique identifiers for the
       # originating session and the actual message id, in addition to the
       # username for the process that generated the message.  This is useful in
       # collaborative settings where multiple users may be interacting with the
       # same kernel simultaneously, so that frontends can label the various
       # messages in a meaningful way.
       'header' : {
                     'msg_id' : uuid,
                     'username' : str,
                     'session' : uuid,
                     # All recognized message type strings are listed below.
                     'msg_type' : str,
                     # the message protocol version
                     'version' : '5.0',
          },
 
       # In a chain of messages, the header from the parent is copied so that
       # clients can track where messages come from.
       'parent_header' : dict,
       
       # Any metadata associated with the message.
       'metadata' : dict,
       
       # The actual content of the message must be a dict, whose structure
       # depends on the message type.
       'content' : dict,
     }
 
 .. versionchanged:: 5.0
 
     ``version`` key added to the header.
 
 .. _wire_protocol:
 
 The Wire Protocol
 =================
 
 
 This message format exists at a high level,
 but does not describe the actual *implementation* at the wire level in zeromq.
 The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class.
 
 .. note::
 
     This section should only be relevant to non-Python consumers of the protocol.
     Python consumers should simply import and use IPython's own implementation of the wire protocol
     in the :class:`IPython.kernel.zmq.session.Session` object.
 
 Every message is serialized to a sequence of at least six blobs of bytes:
 
 .. sourcecode:: python
 
     [
       b'u-u-i-d',         # zmq identity(ies)
       b'<IDS|MSG>',       # delimiter
       b'baddad42',        # HMAC signature
       b'{header}',        # serialized header dict
       b'{parent_header}', # serialized parent header dict
       b'{metadata}',      # serialized metadata dict
       b'{content},        # serialized content dict
       b'blob',            # extra raw data buffer(s)
       ...
     ]
 
 The front of the message is the ZeroMQ routing prefix,
 which can be zero or more socket identities.
 This is every piece of the message prior to the delimiter key ``<IDS|MSG>``.
 In the case of IOPub, there should be just one prefix component,
 which is the topic for IOPub subscribers, e.g. ``execute_result``, ``display_data``.
 
 .. note::
 
     In most cases, the IOPub topics are irrelevant and completely ignored,
     because frontends just subscribe to all topics.
     The convention used in the IPython kernel is to use the msg_type as the topic,
     and possibly extra information about the message, e.g. ``execute_result`` or ``stream.stdout``
 
 After the delimiter is the `HMAC`_ signature of the message, used for authentication.
 If authentication is disabled, this should be an empty string.
 By default, the hashing function used for computing these signatures is sha256.
 
 .. _HMAC: http://en.wikipedia.org/wiki/HMAC
 
 .. note::
 
     To disable authentication and signature checking,
     set the `key` field of a connection file to an empty string.
 
 The signature is the HMAC hex digest of the concatenation of:
 
 - A shared key (typically the ``key`` field of a connection file)
 - The serialized header dict
 - The serialized parent header dict
 - The serialized metadata dict
 - The serialized content dict
 
 In Python, this is implemented via:
 
 .. sourcecode:: python
 
     # once:
     digester = HMAC(key, digestmod=hashlib.sha256)
     
     # for each message
     d = digester.copy()
     for serialized_dict in (header, parent, metadata, content):
         d.update(serialized_dict)
     signature = d.hexdigest()
 
 After the signature is the actual message, always in four frames of bytes.
 The four dictionaries that compose a message are serialized separately,
 in the order of header, parent header, metadata, and content.
 These can be serialized by any function that turns a dict into bytes.
 The default and most common serialization is JSON, but msgpack and pickle
 are common alternatives.
 
 After the serialized dicts are zero to many raw data buffers,
 which can be used by message types that support binary data (mainly apply and data_pub).
 
 
 Python functional API
 =====================
 
 As messages are dicts, they map naturally to a ``func(**kw)`` call form.  We
 should develop, at a few key points, functional forms of all the requests that
 take arguments in this manner and automatically construct the necessary dict
 for sending.
 
 In addition, the Python implementation of the message specification extends
 messages upon deserialization to the following form for convenience::
 
     {
       'header' : dict,
       # The msg's unique identifier and type are always stored in the header,
       # but the Python implementation copies them to the top level.
       'msg_id' : uuid,
       'msg_type' : str,
       'parent_header' : dict,
       'content' : dict,
       'metadata' : dict,
     }
 
 All messages sent to or received by any IPython process should have this
 extended structure.
 
 
 Messages on the shell ROUTER/DEALER sockets
 ===========================================
 
 .. _execute:
 
 Execute
 -------
 
 This message type is used by frontends to ask the kernel to execute code on
 behalf of the user, in a namespace reserved to the user's variables (and thus
 separate from the kernel's own internal code and variables).
 
 Message type: ``execute_request``::
 
     content = {
         # Source code to be executed by the kernel, one or more lines.
     'code' : str,
 
     # A boolean flag which, if True, signals the kernel to execute
     # this code as quietly as possible.
     # silent=True forces store_history to be False,
     # and will *not*:
     #   - broadcast output on the IOPUB channel
     #   - have an execute_result
     # The default is False.
     'silent' : bool,
 
     # A boolean flag which, if True, signals the kernel to populate history
     # The default is True if silent is False.  If silent is True, store_history
     # is forced to be False.
     'store_history' : bool,
 
     # A dict mapping names to expressions to be evaluated in the
     # user's dict. The rich display-data representation of each will be evaluated after execution.
     # See the display_data content for the structure of the representation data.
     'user_expressions' : dict,
 
     # Some frontends do not support stdin requests.
     # If raw_input is called from code executed from such a frontend,
     # a StdinNotImplementedError will be raised.
     'allow_stdin' : True,
     }
 
 .. versionchanged:: 5.0
 
     ``user_variables`` removed, because it is redundant with user_expressions.
 
 The ``code`` field contains a single string (possibly multiline) to be executed.
 
 The ``user_expressions`` field deserves a detailed explanation.  In the past, IPython had
 the notion of a prompt string that allowed arbitrary code to be evaluated, and
 this was put to good use by many in creating prompts that displayed system
 status, path information, and even more esoteric uses like remote instrument
 status acquired over the network.  But now that IPython has a clean separation
 between the kernel and the clients, the kernel has no prompt knowledge; prompts
 are a frontend feature, and it should be even possible for different
 frontends to display different prompts while interacting with the same kernel.
 ``user_expressions`` can be used to retrieve this information.
 
 Any error in evaluating any expression in ``user_expressions`` will result in
 only that key containing a standard error message, of the form::
 
     {
         'status' : 'error',
         'ename' : 'NameError',
         'evalue' : 'foo',
         'traceback' : ...
     }
 
 .. Note::
 
    In order to obtain the current execution counter for the purposes of
    displaying input prompts, frontends may make an execution request with an
    empty code string and ``silent=True``.
 
 Upon completion of the execution request, the kernel *always* sends a reply,
 with a status code indicating what happened and additional data depending on
 the outcome.  See :ref:`below <execution_results>` for the possible return
 codes and associated data.
 
 .. seealso::
 
     :ref:`execution_semantics`
 
 .. _execution_counter:
 
 Execution counter (prompt number)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kernel should have a single, monotonically increasing counter of all execution
 requests that are made with ``store_history=True``. This counter is used to populate
 the ``In[n]`` and ``Out[n]`` prompts.  The value of this counter will be returned as the
 ``execution_count`` field of all ``execute_reply`` and ``execute_input`` messages.
 
 .. _execution_results:
 
 Execution results
 ~~~~~~~~~~~~~~~~~
     
 Message type: ``execute_reply``::
 
     content = {
       # One of: 'ok' OR 'error' OR 'abort'
       'status' : str,
 
       # The global kernel counter that increases by one with each request that 
       # stores history.  This will typically be used by clients to display
       # prompt numbers to the user.  If the request did not store history, this will
       # be the current value of the counter in the kernel.
       'execution_count' : int,
     }
 
 When status is 'ok', the following extra fields are present::
 
     {
       # 'payload' will be a list of payload dicts, and is optional.
       # payloads are considered deprecated.
       # The only requirement of each payload dict is that it have a 'source' key,
       # which is a string classifying the payload (e.g. 'page').
       
       'payload' : list(dict),
 
       # Results for the user_expressions.
       'user_expressions' : dict,
     }
 
 .. versionchanged:: 5.0
 
     ``user_variables`` is removed, use user_expressions instead.
 
 When status is 'error', the following extra fields are present::
 
     {
       'ename' : str,   # Exception name, as a string
       'evalue' : str,  # Exception value, as a string
 
       # The traceback will contain a list of frames, represented each as a
       # string.  For now we'll stick to the existing design of ultraTB, which
       # controls exception level of detail statefully.  But eventually we'll
       # want to grow into a model where more information is collected and
       # packed into the traceback object, with clients deciding how little or
       # how much of it to unpack.  But for now, let's start with a simple list
       # of strings, since that requires only minimal changes to ultratb as
       # written.
       'traceback' : list,
     }
 
 
 When status is 'abort', there are for now no additional data fields.  This
 happens when the kernel was interrupted by a signal.
 
 Payloads
 ********
 
 .. admonition:: Execution payloads
 
     Payloads are considered deprecated, though their replacement is not yet implemented.
 
 Payloads are a way to trigger frontend actions from the kernel. Current payloads:
 
 **page**: display data in a pager.
 
 Pager output is used for introspection, or other displayed information that's not considered output.
 Pager payloads are generally displayed in a separate pane, that can be viewed alongside code,
 and are not included in notebook documents.
 
 .. sourcecode:: python
 
     {
       "source": "page",
       # mime-bundle of data to display in the pager.
       # Must include text/plain.
       "data": mimebundle,
       # line offset to start from
       "start": int,
     }
 
 **set_next_input**: create a new output
 
 used to create new cells in the notebook,
 or set the next input in a console interface.
 The main example being ``%load``.
 
 .. sourcecode:: python
 
     {
       "source": "set_next_input",
       # the text contents of the cell to create
       "text": "some cell content",
     }
 
 **edit**: open a file for editing.
 
 Triggered by `%edit`. Only the QtConsole currently supports edit payloads.
 
 .. sourcecode:: python
 
     {
       "source": "edit",
       "filename": "/path/to/file.py", # the file to edit
       "line_number": int, # the line number to start with
     }
 
 **ask_exit**: instruct the frontend to prompt the user for exit
 
 Allows the kernel to request exit, e.g. via ``%exit`` in IPython.
 Only for console frontends.
 
 .. sourcecode:: python
 
     {
       "source": "ask_exit",
       # whether the kernel should be left running, only closing the client
       "keepkernel": bool,
     }
 
 
 .. _msging_inspection:
 
 Introspection
 -------------
 
 Code can be inspected to show useful information to the user.
 It is up to the Kernel to decide what information should be displayed, and its formatting.
 
 Message type: ``inspect_request``::
 
     content = {
         # The code context in which introspection is requested
         # this may be up to an entire multiline cell.
         'code' : str,
         
         # The cursor position within 'code' (in unicode characters) where inspection is requested
         'cursor_pos' : int,
 
         # The level of detail desired.  In IPython, the default (0) is equivalent to typing
         # 'x?' at the prompt, 1 is equivalent to 'x??'.
         # The difference is up to kernels, but in IPython level 1 includes the source code
         # if available.
         'detail_level' : 0 or 1,
     }
 
 .. versionchanged:: 5.0
 
     ``object_info_request`` renamed to ``inspect_request``.
 
 .. versionchanged:: 5.0
 
     ``name`` key replaced with ``code`` and ``cursor_pos``,
     moving the lexing responsibility to the kernel.
 
 The reply is a mime-bundle, like a `display_data`_ message,
 which should be a formatted representation of information about the context.
 In the notebook, this is used to show tooltips over function calls, etc.
 
 Message type: ``inspect_reply``::
 
     content = {
         # 'ok' if the request succeeded or 'error', with error information as in all other replies.
         'status' : 'ok',
         
         # data can be empty if nothing is found
         'data' : dict,
         'metadata' : dict,
     }
 
 .. versionchanged:: 5.0
 
     ``object_info_reply`` renamed to ``inspect_reply``.
 
 .. versionchanged:: 5.0
 
     Reply is changed from structured data to a mime bundle,  allowing formatting decisions to be made by the kernel.
 
 .. _msging_completion:
 
 Completion
 ----------
 
 Message type: ``complete_request``::
 
     content = {
         # The code context in which completion is requested
         # this may be up to an entire multiline cell, such as
         # 'foo = a.isal'
         'code' : str,
         
         # The cursor position within 'code' (in unicode characters) where completion is requested
         'cursor_pos' : int,
     }
 
 .. versionchanged:: 5.0
 
     ``line``, ``block``, and ``text`` keys are removed in favor of a single ``code`` for context.
     Lexing is up to the kernel.
 
 
 Message type: ``complete_reply``::
 
     content = {
     # The list of all matches to the completion request, such as
     # ['a.isalnum', 'a.isalpha'] for the above example.
     'matches' : list,
     
     # The range of text that should be replaced by the above matches when a completion is accepted.
     # typically cursor_end is the same as cursor_pos in the request.
     'cursor_start' : int,
     'cursor_end' : int,
     
     # Information that frontend plugins might use for extra display information about completions.
     'metadata' : dict,
     
     # status should be 'ok' unless an exception was raised during the request,
     # in which case it should be 'error', along with the usual error message content
     # in other messages.
     'status' : 'ok'
     }
 
 .. versionchanged:: 5.0
 
     - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
     - ``metadata`` is added for extended information.
 
 .. _msging_history:
 
 History
 -------
 
 For clients to explicitly request history from a kernel.  The kernel has all
 the actual execution history stored in a single location, so clients can
 request it from the kernel when needed.
 
 Message type: ``history_request``::
 
     content = {
     
       # If True, also return output history in the resulting dict.
       'output' : bool,
 
       # If True, return the raw input history, else the transformed input.
       'raw' : bool,
 
       # So far, this can be 'range', 'tail' or 'search'.
       'hist_access_type' : str,
       
       # If hist_access_type is 'range', get a range of input cells. session can
       # be a positive session number, or a negative number to count back from
       # the current session.
       'session' : int,
       # start and stop are line numbers within that session.
       'start' : int,
       'stop' : int,
       
       # If hist_access_type is 'tail' or 'search', get the last n cells.
       'n' : int,
       
       # If hist_access_type is 'search', get cells matching the specified glob
       # pattern (with * and ? as wildcards).
       'pattern' : str,
 
       # If hist_access_type is 'search' and unique is true, do not
       # include duplicated history.  Default is false.
       'unique' : bool,
       
     }
 
 .. versionadded:: 4.0
    The key ``unique`` for ``history_request``.
 
 Message type: ``history_reply``::
 
     content = {
       # A list of 3 tuples, either:
       # (session, line_number, input) or
       # (session, line_number, (input, output)),
       # depending on whether output was False or True, respectively.
       'history' : list,
     }
 
 .. _msging_is_complete:
 
 Code completeness
 -----------------
 
 .. versionadded:: 5.0
 
 When the user enters a line in a console style interface, the console must
 decide whether to immediately execute the current code, or whether to show a
 continuation prompt for further input. For instance, in Python ``a = 5`` would
 be executed immediately, while ``for i in range(5):`` would expect further input.
 
 There are four possible replies:
 
 - *complete* code is ready to be executed
 - *incomplete* code should prompt for another line
 - *invalid* code will typically be sent for execution, so that the user sees the
   error soonest.
 - *unknown* - if the kernel is not able to determine this. The frontend should
   also handle the kernel not replying promptly. It may default to sending the
   code for execution, or it may implement simple fallback heuristics for whether
   to execute the code (e.g. execute after a blank line).
 
 Frontends may have ways to override this, forcing the code to be sent for
 execution or forcing a continuation prompt.
 
 Message type: ``is_complete_request``::
 
     content = {
         # The code entered so far as a multiline string
         'code' : str,
     }
 
 Message type: ``is_complete_reply``::
 
     content = {
         # One of 'complete', 'incomplete', 'invalid', 'unknown'
         'status' : str,
         
         # If status is 'incomplete', indent should contain the characters to use
         # to indent the next line. This is only a hint: frontends may ignore it
         # and use their own autoindentation rules. For other statuses, this
         # field does not exist.
         'indent': str,
     }
 
 Connect
 -------
 
 When a client connects to the request/reply socket of the kernel, it can issue
 a connect request to get basic information about the kernel, such as the ports
 the other ZeroMQ sockets are listening on. This allows clients to only have
 to know about a single port (the shell channel) to connect to a kernel.
 
 Message type: ``connect_request``::
 
     content = {
     }
 
 Message type: ``connect_reply``::
 
     content = {
         'shell_port' : int,   # The port the shell ROUTER socket is listening on.
         'iopub_port' : int,   # The port the PUB socket is listening on.
         'stdin_port' : int,   # The port the stdin ROUTER socket is listening on.
         'hb_port' : int,      # The port the heartbeat socket is listening on.
     }
 
 .. _msging_kernel_info:
 
 Kernel info
 -----------
 
 If a client needs to know information about the kernel, it can
 make a request of the kernel's information.
 This message can be used to fetch core information of the
 kernel, including language (e.g., Python), language version number and
 IPython version number, and the IPython message spec version number.
 
 Message type: ``kernel_info_request``::
 
     content = {
     }
 
 Message type: ``kernel_info_reply``::
 
     content = {
         # Version of messaging protocol.
         # The first integer indicates major version.  It is incremented when
         # there is any backward incompatible change.
         # The second integer indicates minor version.  It is incremented when
         # there is any backward compatible change.
         'protocol_version': 'X.Y.Z',
 
         # The kernel implementation name
         # (e.g. 'ipython' for the IPython kernel)
         'implementation': str,
 
         # Implementation version number.
         # The version number of the kernel's implementation
         # (e.g. IPython.__version__ for the IPython kernel)
         'implementation_version': 'X.Y.Z', 
 
-        # Programming language in which kernel is implemented.
+        # Information about the language of code for the kernel
+        'language_info': {
+            # Name of the programming language in which kernel is implemented.
         # Kernel included in IPython returns 'python'.
-        'language': str,
+            'name': str,
         
         # Language version number.
         # It is Python version number (e.g., '2.7.3') for the kernel
         # included in IPython.
-        'language_version': 'X.Y.Z',
+            'version': 'X.Y.Z',
 
-        # Information about the language of code for the kernel
-        'language_info': {
+            # mimetype for script files in this language
             'mimetype': str,
 
             # Extension without the dot, e.g. 'py'
             'file_extension': str,
 
             # Pygments lexer, for highlighting
             # Only needed if it differs from the top level 'language' field.
             'pygments_lexer': str,
 
             # Codemirror mode, for for highlighting in the notebook.
             # Only needed if it differs from the top level 'language' field.
             'codemirror_mode': str or dict,
 
             # Nbconvert exporter, if notebooks written with this kernel should
             # be exported with something other than the general 'script'
             # exporter.
             'nbconvert_exporter': str,
         },
 
         # A banner of information about the kernel,
         # which may be desplayed in console environments.
         'banner' : str,
 
         # Optional: A list of dictionaries, each with keys 'text' and 'url'.
         # These will be displayed in the help menu in the notebook UI.
         'help_links': [
             {'text': str, 'url': str}
         ],
     }
 
 Refer to the lists of available `Pygments lexers <http://pygments.org/docs/lexers/>`_
 and `codemirror modes <http://codemirror.net/mode/index.html>`_ for those fields.
 
 .. versionchanged:: 5.0
 
     Versions changed from lists of integers to strings.
     
 .. versionchanged:: 5.0
 
     ``ipython_version`` is removed.
 
 .. versionchanged:: 5.0
 
     ``language_info``, ``implementation``, ``implementation_version``, ``banner``
     and ``help_links`` keys are added.
 
+.. versionchanged:: 5.0
+
+    ``language_version`` moved to ``language_info.version``
+
+.. versionchanged:: 5.0
+
+    ``language`` moved to ``language_info.name``
+
 .. _msging_shutdown:
 
 Kernel shutdown
 ---------------
 
 The clients can request the kernel to shut itself down; this is used in
 multiple cases:
 
 - when the user chooses to close the client application via a menu or window
   control.
 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
   IPythonQt client) to force a kernel restart to get a clean kernel without
   losing client-side state like history or inlined figures.
 
 The client sends a shutdown request to the kernel, and once it receives the
 reply message (which is otherwise empty), it can assume that the kernel has
 completed shutdown safely.
 
 Upon their own shutdown, client applications will typically execute a last
 minute sanity check and forcefully terminate any kernel that is still alive, to
 avoid leaving stray processes in the user's machine.
 
 Message type: ``shutdown_request``::
 
     content = {
         'restart' : bool # whether the shutdown is final, or precedes a restart
     }
 
 Message type: ``shutdown_reply``::
 
     content = {
         'restart' : bool # whether the shutdown is final, or precedes a restart
     }
 
 .. Note::
 
    When the clients detect a dead kernel thanks to inactivity on the heartbeat
    socket, they simply send a forceful process termination signal, since a dead
    process is unlikely to respond in any useful way to messages.
     
 
 Messages on the PUB/SUB socket
 ==============================
 
 Streams (stdout,  stderr, etc)
 ------------------------------
 
 Message type: ``stream``::
 
     content = {
         # The name of the stream is one of 'stdout', 'stderr'
         'name' : str,
     
         # The text is an arbitrary string to be written to that stream
         'text' : str,
     }
 
 .. versionchanged:: 5.0
 
     'data' key renamed to 'text' for conistency with the notebook format.
 
 Display Data
 ------------
 
 This type of message is used to bring back data that should be displayed (text,
 html, svg, etc.) in the frontends. This data is published to all frontends.
 Each message can have multiple representations of the data; it is up to the
 frontend to decide which to use and how. A single message should contain all
 possible representations of the same information. Each representation should
 be a JSON'able data structure, and should be a valid MIME type.
 
 Some questions remain about this design:
 
 * Do we use this message type for execute_result/displayhook? Probably not, because
   the displayhook also has to handle the Out prompt display. On the other hand
   we could put that information into the metadata section.
 
 .. _display_data:
 
 Message type: ``display_data``::
 
     content = {
 
         # Who create the data
         'source' : str,
 
         # The data dict contains key/value pairs, where the keys are MIME
         # types and the values are the raw data of the representation in that
         # format.
         'data' : dict,
 
         # Any metadata that describes the data
         'metadata' : dict
     }
 
 
 The ``metadata`` contains any metadata that describes the output.
 Global keys are assumed to apply to the output as a whole.
 The ``metadata`` dict can also contain mime-type keys, which will be sub-dictionaries,
 which are interpreted as applying only to output of that type.
 Third parties should put any data they write into a single dict
 with a reasonably unique name to avoid conflicts.
 
 The only metadata keys currently defined in IPython are the width and height
 of images::
 
     metadata = {
       'image/png' : {
         'width': 640,
         'height': 480
       }
     }
 
 
 .. versionchanged:: 5.0
 
     `application/json` data should be unpacked JSON data,
     not double-serialized as a JSON string.
 
 
 Raw Data Publication
 --------------------
 
 ``display_data`` lets you publish *representations* of data, such as images and html.
 This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers.
 
 data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function:
 
 .. sourcecode:: python
 
     from IPython.kernel.zmq.datapub import publish_data
     ns = dict(x=my_array)
     publish_data(ns)
 
 
 Message type: ``data_pub``::
 
     content = {
         # the keys of the data dict, after it has been unserialized
         'keys' : ['a', 'b']
     }
     # the namespace dict will be serialized in the message buffers,
     # which will have a length of at least one
     buffers = [b'pdict', ...]
 
 
 The interpretation of a sequence of data_pub messages for a given parent request should be
 to update a single namespace with subsequent results.
 
 .. note::
 
     No frontends directly handle data_pub messages at this time.
     It is currently only used by the client/engines in :mod:`IPython.parallel`,
     where engines may publish *data* to the Client,
     of which the Client can then publish *representations* via ``display_data``
     to various frontends.
 
 Code inputs
 -----------
 
 To let all frontends know what code is being executed at any given time, these
 messages contain a re-broadcast of the ``code`` portion of an
 :ref:`execute_request <execute>`, along with the :ref:`execution_count
 <execution_counter>`.
 
 Message type: ``execute_input``::
 
     content = {
         'code' : str,  # Source code to be executed, one or more lines
 
         # The counter for this execution is also provided so that clients can
         # display it, since IPython automatically creates variables called _iN
         # (for input prompt In[N]).
         'execution_count' : int
     }
 
 .. versionchanged:: 5.0
 
     ``pyin`` is renamed to ``execute_input``.
 
 
 Execution results
 -----------------
 
 Results of an execution are published as an ``execute_result``.
 These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key.
 
 Results can have multiple simultaneous formats depending on its
 configuration. A plain text representation should always be provided
 in the ``text/plain`` mime-type. Frontends are free to display any or all of these
 according to its capabilities.
 Frontends should ignore mime-types they do not understand. The data itself is
 any JSON object and depends on the format. It is often, but not always a string.
 
 Message type: ``execute_result``::
 
     content = {
 
         # The counter for this execution is also provided so that clients can
         # display it, since IPython automatically creates variables called _N
         # (for prompt N).
         'execution_count' : int,
 
         # data and metadata are identical to a display_data message.
         # the object being displayed is that passed to the display hook,
         # i.e. the *result* of the execution.
         'data' : dict,
         'metadata' : dict,
     }
 
 Execution errors
 ----------------
 
 When an error occurs during code execution
 
 Message type: ``error``::
 
     content = {
        # Similar content to the execute_reply messages for the 'error' case,
        # except the 'status' field is omitted.
     }
 
 .. versionchanged:: 5.0
 
     ``pyerr`` renamed to ``error``
 
 Kernel status
 -------------
 
 This message type is used by frontends to monitor the status of the kernel.
 
 Message type: ``status``::
 
     content = {
         # When the kernel starts to handle a message, it will enter the 'busy'
         # state and when it finishes, it will enter the 'idle' state.
         # The kernel will publish state 'starting' exactly once at process startup.
         execution_state : ('busy', 'idle', 'starting')
     }
 
 .. versionchanged:: 5.0
 
     Busy and idle messages should be sent before/after handling every message,
     not just execution.
 
 Clear output
 ------------
 
 This message type is used to clear the output that is visible on the frontend.
 
 Message type: ``clear_output``::
 
     content = {
 
         # Wait to clear the output until new output is available.  Clears the
         # existing output immediately before the new output is displayed.  
         # Useful for creating simple animations with minimal flickering.
         'wait' : bool,
     }
 
 .. versionchanged:: 4.1
 
     ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed,
     and ``wait`` is added.
     The selective clearing keys are ignored in v4 and the default behavior remains the same,
     so v4 clear_output messages will be safely handled by a v4.1 frontend.
 
 
 Messages on the stdin ROUTER/DEALER sockets
 ===========================================
 
 This is a socket where the request/reply pattern goes in the opposite direction:
 from the kernel to a *single* frontend, and its purpose is to allow
 ``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel
 to be fulfilled by the client. The request should be made to the frontend that
 made the execution request that prompted ``raw_input`` to be called. For now we
 will keep these messages as simple as possible, since they only mean to convey
 the ``raw_input(prompt)`` call.
 
 Message type: ``input_request``::
 
     content = {
         # the text to show at the prompt
         'prompt' : str,
         # Is the request for a password?
         # If so, the frontend shouldn't echo input.
         'password' : bool
     }
 
 Message type: ``input_reply``::
 
     content = { 'value' : str }
 
 
 When ``password`` is True, the frontend should not echo the input as it is entered.
 
 .. versionchanged:: 5.0
 
     ``password`` key added.
 
 .. note::
 
     The stdin socket of the client is required to have the same zmq IDENTITY
     as the client's shell socket.
     Because of this, the ``input_request`` must be sent with the same IDENTITY
     routing prefix as the ``execute_reply`` in order for the frontend to receive
     the message.
 
 .. note::
 
    We do not explicitly try to forward the raw ``sys.stdin`` object, because in
    practice the kernel should behave like an interactive program.  When a
    program is opened on the console, the keyboard effectively takes over the
    ``stdin`` file descriptor, and it can't be used for raw reading anymore.
    Since the IPython kernel effectively behaves like a console program (albeit
    one whose "keyboard" is actually living in a separate process and
    transported over the zmq connection), raw ``stdin`` isn't expected to be
    available.
 
 .. _kernel_heartbeat:
 
 Heartbeat for kernels
 =====================
 
 Clients send ping messages on a REQ socket, which are echoed right back
 from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above.
 
 
 Custom Messages
 ===============
 
 .. versionadded:: 4.1
 
 IPython 2.0 (msgspec v4.1) adds a messaging system for developers to add their own objects with Frontend
 and Kernel-side components, and allow them to communicate with each other.
 To do this, IPython adds a notion of a ``Comm``, which exists on both sides,
 and can communicate in either direction.
 
 These messages are fully symmetrical - both the Kernel and the Frontend can send each message,
 and no messages expect a reply.
 The Kernel listens for these messages on the Shell channel,
 and the Frontend listens for them on the IOPub channel.
 
 Opening a Comm
 --------------
 
 Opening a Comm produces a ``comm_open`` message, to be sent to the other side::
 
     {
       'comm_id' : 'u-u-i-d',
       'target_name' : 'my_comm',
       'data' : {}
     }
 
 Every Comm has an ID and a target name.
 The code handling the message on the receiving side is responsible for maintaining a mapping
 of target_name keys to constructors.
 After a ``comm_open`` message has been sent,
 there should be a corresponding Comm instance on both sides.
 The ``data`` key is always a dict and can be any extra JSON information used in initialization of the comm.
 
 If the ``target_name`` key is not found on the receiving side,
 then it should immediately reply with a ``comm_close`` message to avoid an inconsistent state.
 
 Comm Messages
 -------------
 
 Comm messages are one-way communications to update comm state,
 used for synchronizing widget state, or simply requesting actions of a comm's counterpart.
 
 Essentially, each comm pair defines their own message specification implemented inside the ``data`` dict.
 
 There are no expected replies (of course, one side can send another ``comm_msg`` in reply).
 
 Message type: ``comm_msg``::
 
     {
       'comm_id' : 'u-u-i-d',
       'data' : {}
     }
 
 Tearing Down Comms
 ------------------
 
 Since comms live on both sides, when a comm is destroyed the other side must be notified.
 This is done with a ``comm_close`` message.
 
 Message type: ``comm_close``::
 
     {
       'comm_id' : 'u-u-i-d',
       'data' : {}
     }
 
 Output Side Effects
 -------------------
 
 Since comm messages can execute arbitrary user code,
 handlers should set the parent header and publish status busy / idle,
 just like an execute request.
 
 
 To Do
 =====
 
 Missing things include:
 
 * Important: finish thinking through the payload concept and API.
 
 .. include:: ../links.txt

docs/source/notebook/nbformat.rst

@@ -1,338 +1,342
 .. _nbformat:
 
 ===========================
 The Jupyter Notebook Format
 ===========================
 
 Introduction
 ============
 
 Jupyter (né IPython) notebook files are simple JSON documents,
 containing text, source code, rich media output, and metadata.
 each segment of the document is stored in a cell.
 
 Some general points about the notebook format:
 
 .. note::
 
     *All* metadata fields are optional.
     While the type and values of some metadata are defined,
     no metadata values are required to be defined.
 
 
 Top-level structure
 ===================
 
 At the highest level, a Jupyter notebook is a dictionary with a few keys:
 
 - metadata (dict)
 - nbformat (int)
 - nbformat_minor (int)
 - cells (list)
 
 .. sourcecode:: python
 
     {
       "metadata" : {
         "signature": "hex-digest", # used for authenticating unsafe outputs on load
         "kernel_info": {
-            # if kernel_info is defined, its name and language fields are required.
-            "name" : "the name of the kernel",
-            "language" : "the programming language of the kernel",
-            "codemirror_mode": "The name of the codemirror mode to use [optional]"
+            # if kernel_info is defined, its name field is required.
+            "name" : "the name of the kernel"
         },
+        "language_info": {
+            # if language_info is defined, its name field is required.
+            "name" : "the programming language of the kernel",
+            "version": "the version of the language",
+            "codemirror_mode": "The name of the codemirror mode to use [optional]"
+        }
       },
       "nbformat": 4,
       "nbformat_minor": 0,
       "cells" : [
           # list of cell dictionaries, see below
       ],
     }
 
 Some fields, such as code input and text output, are characteristically multi-line strings.
 When these fields are written to disk, they **may** be written as a list of strings,
 which should be joined with ``''`` when reading back into memory.
 In programmatic APIs for working with notebooks (Python, Javascript),
 these are always re-joined into the original multi-line string.
 If you intend to work with notebook files directly,
 you must allow multi-line string fields to be either a string or list of strings.
 
 
 Cell Types
 ==========
 
 There are a few basic cell types for encapsulating code and text.
 All cells have the following basic structure:
 
 .. sourcecode:: python
 
     {
       "cell_type" : "name",
       "metadata" : {},
       "source" : "single string or [list, of, strings]",
     }
 
 
 Markdown cells
 --------------
 
 Markdown cells are used for body-text, and contain markdown,
 as defined in `GitHub-flavored markdown`_, and implemented in marked_.
 
 .. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
 .. _marked: https://github.com/chjj/marked
 
 .. sourcecode:: python
 
     {
       "cell_type" : "markdown",
       "metadata" : {},
       "source" : ["some *markdown*"],
     }
 
 .. versionchanged:: nbformat 4.0
 
     Heading cells have been removed, in favor of simple headings in markdown.
 
 
 Code cells
 ----------
 
 Code cells are the primary content of Jupyter notebooks.
 They contain source code in the language of the document's associated kernel,
 and a list of outputs associated with executing that code.
 They also have an execution_count, which must be an integer or ``null``.
 
 .. sourcecode:: python
 
     {
       "cell_type" : "code",
       "execution_count": 1, # integer or null
       "metadata" : {
           "collapsed" : True, # whether the output of the cell is collapsed
           "autoscroll": False, # any of true, false or "auto"
       },
       "source" : ["some code"],
       "outputs": [{
           # list of output dicts (described below)
           "output_type": "stream",
           ...
       }],
     }
 
 .. versionchanged:: nbformat 4.0
 
     ``input`` was renamed to ``source``, for consistency among cell types.
 
 .. versionchanged:: nbformat 4.0
 
     ``prompt_number`` renamed to ``execution_count``
 
 Code cell outputs
 -----------------
 
 A code cell can have a variety of outputs (stream data or rich mime-type output).
 These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
 
 All outputs have an ``output_type`` field,
 which is a string defining what type of output it is.
 
 
 stream output
 *************
 
 .. sourcecode:: python
 
     {
       "output_type" : "stream",
       "name" : "stdout", # or stderr
       "data" : ["multiline stream text"],
     }
 
 .. versionchanged:: nbformat 4.0
 
     The keys ``stream`` and ``text`` were changed to ``name`` and ``data`` to match
     the stream message specification.
 
 
 display_data
 ************
 
 Rich display outputs, as created by ``display_data`` messages,
 contain data keyed by mime-type. This is often called a mime-bundle,
 and shows up in various locations in the notebook format and message spec.
 The metadata of these messages may be keyed by mime-type as well.
 
 
 
 .. sourcecode:: python
 
     {
       "output_type" : "display_data",
       "data" : {
         "text/plain" : ["multiline text data"],
         "image/png": ["base64-encoded-png-data"],
         "application/json": {
           # JSON data is included as-is
           "json": "data",
         },
       },
       "metadata" : {
         "image/png": {
           "width": 640,
           "height": 480,
         },
       },
     }
 
 
 .. versionchanged:: nbformat 4.0
 
     ``application/json`` output is no longer double-serialized into a string.
 
 .. versionchanged:: nbformat 4.0
 
     mime-types are used for keys, instead of a combination of short names (``text``)
     and mime-types, and are stored in a ``data`` key, rather than the top-level.
     i.e. ``output.data['image/png']`` instead of ``output.png``.
 
 
 execute_result
 **************
 
 Results of executing a cell (as created by ``displayhook`` in Python)
 are stored in ``execute_result`` outputs.
 `execute_result` outputs are identical to ``display_data``,
 adding only a ``execution_count`` field, which must be an integer.
 
 .. sourcecode:: python
 
     {
       "output_type" : "execute_result",
       "execution_count": 42,
       "data" : {
         "text/plain" : ["multiline text data"],
         "image/png": ["base64-encoded-png-data"],
         "application/json": {
           # JSON data is included as-is
           "json": "data",
         },
       },
       "metadata" : {
         "image/png": {
           "width": 640,
           "height": 480,
         },
       },
     }
 
 .. versionchanged:: nbformat 4.0
 
     ``pyout`` renamed to ``execute_result``
 
 .. versionchanged:: nbformat 4.0
 
     ``prompt_number`` renamed to ``execution_count``
 
 
 error
 *****
 
 Failed execution may show a traceback
 
 .. sourcecode:: python
 
     {
       'ename' : str,   # Exception name, as a string
       'evalue' : str,  # Exception value, as a string
 
       # The traceback will contain a list of frames,
       # represented each as a string.
       'traceback' : list,
     }
 
 .. versionchanged:: nbformat 4.0
 
     ``pyerr`` renamed to ``error``
 
 
 .. _raw nbconvert cells:
 
 Raw NBConvert cells
 -------------------
 
 A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
 For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
 or restructured text for use in Sphinx documentation.
 
 The notebook authoring environment does not render raw cells.
 
 The only logic in a raw cell is the `format` metadata field.
 If defined, it specifies which nbconvert output format is the intended target
 for the raw cell. When outputting to any other format,
 the raw cell's contents will be excluded.
 In the default case when this value is undefined,
 a raw cell's contents will be included in any nbconvert output,
 regardless of format.
 
 .. sourcecode:: python
 
     {
       "cell_type" : "raw",
       "metadata" : {
         # the mime-type of the target nbconvert format.
         # nbconvert to formats other than this will exclude this cell.
         "format" : "mime/type"
       },
       "source" : ["some nbformat mime-type data"]
     }
 
 Metadata
 ========
 
 Metadata is a place that you can put arbitrary JSONable information about
 your notebook, cell, or output. Because it is a shared namespace,
 any custom metadata should use a sufficiently unique namespace,
 such as `metadata.kaylees_md.foo = "bar"`.
 
 Metadata fields officially defined for Jupyter notebooks are listed here:
 
 Notebook metadata
 -----------------
 
 The following metadata keys are defined at the notebook level:
 
 =========== =============== ==============
 Key         Value           Interpretation
 =========== =============== ==============
 kernelspec  dict            A :ref:`kernel specification <kernelspecs>`
 signature   str             A hashed :ref:`signature <notebook_security>` of the notebook
 =========== =============== ==============
 
 
 Cell metadata
 -------------
 
 The following metadata keys are defined at the cell level:
 
 =========== =============== ==============
 Key         Value           Interpretation
 =========== =============== ==============
 collapsed   bool            Whether the cell's output container should be collapsed
 autoscroll  bool or 'auto'  Whether the cell's output is scrolled, unscrolled, or autoscrolled
 deletable   bool            If False, prevent deletion of the cell
 format      'mime/type'     The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
 name        str             A name for the cell. Should be unique
 tags        list of str     A list of string tags on the cell. Commas are not allowed in a tag
 =========== =============== ==============
 
 Output metadata
 ---------------
 
 The following metadata keys are defined for code cell outputs:
 
 =========== =============== ==============
 Key         Value           Interpretation
 =========== =============== ==============
 isolated    bool            Whether the output should be isolated into an IFrame
 =========== =============== ==============