Some little changes in doc

docs/source/development/ipythonzmq.txt

@@ -5,7 +5,7 b' porting ipython to a two process model using zeromq'
 ===================================================
 
 abstract
---------
+----------
 
 ipython's execution in a command-line environment will be ported to a two process model using the zeromq library for inter-process communication. this will:
 
@@ -14,16 +14,9 b" ipython's execution in a command-line environment will be ported to a two proces"
 - allow ipython to reuse code for local execution and distributed computing (dc)
 - give us a path for python3 support, since zeromq supports python3 while twisted (what we use today for dc) does not.
 
-deliverables
-------------
-
-* a user-facing frontend that provides an environment like today's command-line ipython but running over two processes, with the code execution kernel living in a separate process and communicating with the frontend by using the zeromq library.
-
-* a kernel that supports ipython's features (tab-completion, code introspection, exception reporting with different levels of detail, etc), but listening to requests over a network port, and returning results as json-formatted messages over the network.
-
 
 project description
--------------------
+---------------------
 
 currently ipython provides a command-line client that executes all code in a single process, and a set of tools for distributed and parallel computing that execute code in multiple processes (possibly but not necessarily on different hosts), using the twisted asynchronous framework for communication between nodes. for a number of reasons, it is desirable to unify the architecture of the local execution with that of distributed computing, since ultimately many of the underlying abstractions are similar and should be reused.  in particular, we would like to:
 
@@ -38,12 +31,206 b' as part of the zmq python bindings, the ipython developers have already develope'
 once this port is complete, the resulting tools will be the foundation (though as part of this proposal i do not expect to undertake either of these tasks) to allow the distributed computing parts of ipython to use the same code as the command-line client, and for the whole system to be ported to python3.  so while i do not intend to tackle here the removal of twisted and the unification of the local and distributed parts of ipython, my proposal is a necessary step before those are possible.
 
 project details
----------------
-
-As part of the zeromq bindings, the ipython developers have already developed a simple prototype example that provides a python execution kernel (with none of ipython's code or features, just plain code execution) that listens on zmq sockets, and a frontend based on the interactiveconsole class of the code.py module from the python standard library. this example is capable of executing code, propagating errors, performing tab-completion over the network and having multiple frontends connect and disconnect simultaneously to a single kernel, with all inputs and outputs being made available to all connected clients (thanks to zqm's pub sockets that provide multicasting capabilities for the kernel and to which the frontends subscribe via a sub socket).
-
+-------------------
 
-** we have all example code in
+as part of the zeromq bindings, the ipython developers have already developed a simple prototype example that provides a python execution kernel (with none of ipython's code or features, just plain code execution) that listens on zmq sockets, and a frontend based on the interactiveconsole class of the code.py module from the python standard library. this example is capable of executing code, propagating errors, performing tab-completion over the network and having multiple frontends connect and disconnect simultaneously to a single kernel, with all inputs and outputs being made available to all connected clients (thanks to zqm's pub sockets that provide multicasting capabilities for the kernel and to which the frontends subscribe via a sub socket).
+
+this simple code shows how the kernel starts:
+
+
+  def main():                                                                 
+                                                                              
+     c = zmq.context(1, 1)                                                    
+                                                                              
+     #ip = '192.168.2.109'                                                    
+                                                                              
+     ip = '127.0.0.1'                                                         
+                                                                              
+     #ip = '192.168.4.128'                                                    
+                                                                              
+     port_base = 5555                                                         
+                                                                              
+     connection = ('tcp://%s' % ip) + ':%i'                                   
+                                                                              
+     rep_conn = connection % port_base                                        
+                                                                              
+     pub_conn = connection % (port_base+1)                                    
+                                                                              
+     print >>sys.__stdout__, "starting the kernel..."                         
+                                                                              
+     print >>sys.__stdout__, "on:",rep_conn, pub_conn                         
+                                                                              
+     session = session(username=u'kernel')                                    
+                                                                              
+     reply_socket = c.socket(zmq.xrep)                                        
+                                                                              
+     reply_socket.bind(rep_conn)                                              
+                                                                              
+     pub_socket = c.socket(zmq.pub)                                           
+                                                                              
+     pub_socket.bind(pub_conn)                                                
+                                                                              
+     stdout = outstream(session, pub_socket, u'stdout')                       
+                                                                              
+     stderr = outstream(session, pub_socket, u'stderr')                       
+                                                                              
+     sys.stdout = stdout                                                      
+                                                                              
+     sys.stderr = stderr                                                      
+                                                                              
+     display_hook = displayhook(session, pub_socket)                          
+                                                                              
+     sys.displayhook = display_hook                                           
+                                                                              
+     kernel = kernel(session, reply_socket, pub_socket)                       
+                                                                              
+
+
+and the heart of the kernel is the method to execute code and post back the results over the necessary sockets, using json-formatted messages:
+
+
+  def execute_request(self, ident, parent):                                    
+                                                                               
+         try:                                                                  
+                                                                               
+             code = parent[u'content'][u'code']                                
+                                                                               
+         except:                                                               
+                                                                               
+             print>>sys.__stderr__, "got bad msg: "                            
+                                                                               
+             print>>sys.__stderr__, message(parent)                            
+                                                                               
+             return                                                            
+                                                                               
+         pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)    
+                                                                               
+         self.pub_socket.send_json(pyin_msg)                                   
+                                                                               
+         try:                                                                  
+                                                                               
+             comp_code = self.compiler(code, '<zmq-kernel>')                   
+                                                                               
+             sys.displayhook.set_parent(parent)                                
+                                                                               
+             exec comp_code in self.user_ns, self.user_ns                      
+                                                                               
+         except:                                                               
+                                                                               
+             result = u'error'                                                 
+                                                                               
+             etype, evalue, tb = sys.exc_info()                                
+                                                                               
+             tb = traceback.format_exception(etype, evalue, tb)                
+                                                                               
+             exc_content = {                                                   
+                                                                               
+                 u'status' : u'error',                                         
+                                                                               
+                 u'traceback' : tb,                                            
+                                                                               
+                 u'etype' : unicode(etype),                                    
+                                                                               
+                 u'evalue' : unicode(evalue)                                   
+                                                                               
+             }                                                                 
+                                                                               
+             exc_msg = self.session.msg(u'pyerr', exc_content, parent)         
+                                                                               
+             self.pub_socket.send_json(exc_msg)                                
+                                                                               
+             reply_content = exc_content                                       
+                                                                               
+         else:                                                                 
+                                                                               
+             reply_content = {'status' : 'ok'}                                 
+                                                                               
+         reply_msg = self.session.msg(u'execute_reply', reply_content, parent) 
+                                                                               
+         print>>sys.__stdout__, message(reply_msg)                             
+                                                                               
+         self.reply_socket.send_json(reply_msg, ident=ident)                   
+                                                                               
+         if reply_msg['content']['status'] == u'error':                         
+                                                                               
+             self.abort_queue()                                                
+                                                                               
+                                                                               
+
+and a little system to tab-completion
+
+
+  def execute_request(self, ident, parent):                                    
+                                                                               
+         try:                                                                  
+                                                                               
+             code = parent[u'content'][u'code']                                
+                                                                               
+         except:                                                               
+                                                                               
+             print>>sys.__stderr__, "got bad msg: "                            
+                                                                               
+             print>>sys.__stderr__, message(parent)                            
+                                                                               
+             return                                                            
+                                                                               
+         pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)    
+                                                                               
+         self.pub_socket.send_json(pyin_msg)                                   
+                                                                               
+         try:                                                                  
+                                                                               
+             comp_code = self.compiler(code, '<zmq-kernel>')                   
+                                                                               
+             sys.displayhook.set_parent(parent)                                
+                                                                               
+             exec comp_code in self.user_ns, self.user_ns                      
+                                                                               
+         except:                                                               
+                                                                               
+             result = u'error'                                                 
+                                                                               
+             etype, evalue, tb = sys.exc_info()                                
+                                                                               
+             tb = traceback.format_exception(etype, evalue, tb)                
+                                                                               
+             exc_content = {                                                   
+                                                                               
+                 u'status' : u'error',                                         
+                                                                               
+                 u'traceback' : tb,                                            
+                                                                               
+                 u'etype' : unicode(etype),                                    
+                                                                               
+                u'evalue' : unicode(evalue)                                    
+                                                                               
+             }                                                                 
+                                                                               
+             exc_msg = self.session.msg(u'pyerr', exc_content, parent)         
+                                                                               
+             self.pub_socket.send_json(exc_msg)                                
+                                                                               
+             reply_content = exc_content                                       
+                                                                               
+         else:                                                                 
+                                                                               
+             reply_content = {'status' : 'ok'}                                 
+                                                                               
+         reply_msg = self.session.msg(u'execute_reply', reply_content, parent) 
+                                                                               
+         print>>sys.__stdout__, message(reply_msg)                             
+                                                                               
+         self.reply_socket.send_json(reply_msg, ident=ident)                   
+                                                                               
+         if reply_msg['content']['status'] == u'error':                        
+                                                                               
+             self.abort_queue()                                                 
+                                                                               
+
+
+
+
+**we have all example code in
 
 * http://github.com/ellisonbg/pyzmq/blob/completer/examples/kernel/kernel.py
 
@@ -56,7 +243,8 b' all of this code already works, and can be seen in this example directory from t'
 
 * http://github.com/ellisonbg/pyzmq/blob/completer/examples/kernel
 
-Based on this work, i expect to write a stable system for ipython kernel with ipython standards, error control,crash recovery system and general configuration options, also standardize defaults ports or auth system for remote connection etc.
 
-the crash recovery system, is a ipython kernel module for when it fails unexpectedly, you can retrieve the information from the section, this will be based on a log and a lock file to indicate when the kernel was not closed in a proper way.
+based on this work, i expect to write a stable system for ipython kernel with ipython standards, error control,crash recovery system and general configuration options, also standardize defaults ports or auth system for remote connection etc.
 
+the crash recovery system, is a ipython kernel module for when it fails unexpectedly, you can retrieve the information from the section, this will be based on a log and a lock file to indicate when the kernel was not closed in a proper way.
+