erp5_data_notebook: documentation about environment object and astor egg added

Documentation on top on each Jupyter notebook about why and how we use the
environment object.

Adds the astor egg to convert abstract syntax tree objects back to source
code.

software/ipython_notebook/software.cfg

@@ -17,6 +17,7 @@ parts =
 ; ipython notebook component
 eggs +=
   requests
+  astor
   ${scipy:egg}
   ${pandas:egg}
   ${scikit-learn:egg}
@@ -52,7 +53,7 @@ md5sum = ab6e78ea20855e07d388b5b86d1770fe
 [custom-js]
 <= download-file-base
 filename = custom.js.jinja
-md5sum = 0e8262d04a6dafbc1b77d95aea2192bc
+md5sum = a851a68667a4e676cfa86b34a86b4239
 
 [instance-jupyter]
 recipe = slapos.recipe.template:jinja2
@@ -176,3 +177,5 @@ pickleshare = 0.5
 # ipython==4.0.0
 # notebook==4.0.6
 traitlets = 4.1.0b1
+
+astor = 0.5

software/ipython_notebook/template/custom.js.jinja

@@ -86,7 +86,7 @@ $([IPython.events]).on('notebook_loaded.Notebook', function(){
   var display_text="<div class='output_subarea output_text output_result'>\
   <pre>Follow these steps to customize your notebook with ERP5 kernel :-</br>\
   1. Add <b>%erp5_url &lt;your_erp5_url&gt;/erp5/Base_executeJupyter</b>.</br>\
-  Make sure you have 'erp5_data_notebook' business template installed in your erp5</br>\
+  Make sure you have 'erp5_data_notebook' business template installed in your ERP5</br>\
   2. <b>%notebook_set_reference &lt;your_notebook_refernce&gt;</b></br>\
   It would be better to set the reference to match with erp5 reference pattern.</br>\
   3. <b>%erp5_user &lt;your_erp5_username&gt;</b></br>\
@@ -96,8 +96,26 @@ $([IPython.events]).on('notebook_loaded.Notebook', function(){
   <b>%my_notebooks</b> -This is used to display all the notebooks created by the specific user.</br>\
   NOTE: Do not dynamically alter imported module objects as they are not being saved in DB, </br>\
   so changes to them would be disregarded and would throw an error.</br>\
+  <p><u>About classes, functions and global state on modules:</u></p>\
+  Your code is going to be executed by ERP5, which can have many nodes </br>\
+  and there is no guarantee that your code is always going to be executed by the same server.</br>\
+  This means that objects which cannot be stored in the ZODB, like functions, classes and modules </br>\
+  won't be available across nodes. To solve this issue, you need to use a special object </br>\
+  called 'environment' to store your global setup. This object was designed to hold global </br>\
+  state and restore it for each code cell. Example:</br></br>\
+  <b>def my_setup():</br>\
+     # import modules, define functions and classes</br>\
+     # and set global state on modules</br>\
+     # return dict of variables to be available in code cells</br>\
+     {'my_var': 1}</br>\
+  environment.define(my_setup, 'my custom setup')</b></br></br>\
+  After you execute this cell, the <b>my_setup</b> function will run before each of the</br>\
+  following cells and the <b>my_var</b> variable will be created and set to 1.</br></br>\
+  <b>WARNING:</b> it is not recommended to have too many setup functions in the environment, </br>\
+  because they will be executed in every code cell and can cause a substantial slow down.\
   </pre></div>";
   if (kernelname=="erp5"){
   $('div#notebook-container').prepend(display_text);
   }
   });
+  
\ No newline at end of file

software/wendelin/software.cfg

@@ -19,6 +19,7 @@ initialization =
 extra-paths +=
   ${wendelin:location}
 eggs +=
+  astor
   ${scipy:egg}
   ${msgpack-python:egg}
   ${wendelin.core:egg}

stack/erp5/buildout.cfg

@@ -483,6 +483,7 @@ eggs =
   ${pycrypto-python:egg}
   ${scikit-learn:egg}
   lock_file
+  astor
   PyStemmer
   PyXML
   Pympler