[IPython-dev] Re: questions about the notebook interface

Robert Kern rkern at ucsd.edu
Mon Jun 27 22:38:13 EDT 2005

Toni Alatalo wrote:
> Greetings.
> i have some questions about the notebook interface (as it's described in 
> http://ipython.scipy.org/google_soc/ipnb_google_soc.pdf). must leave 
> right now so am trying to be brief, sorry for possible unclarities:

I've been thinking a bit about this too, since I was going to volunteer 
some work on this if no one got picked for it by Google. Looks like that 
won't be necessary. Congratulations!

> 1. reasoning for true Python over special string / comments
> as e.g. rst is nice for writing documents in itself, and can also be 
> used to write text, make tables, images etc. in Python files (the 
> original purpose), i'd be interested in hearing the main arguments from 
> the 'lengthy discussions' (referred in the spec) for deciding on true 
> Python instead. am probably bying the result already, but would still 
> like to hear the reasoning.

I personally don't agree with it. I wasn't a party to those discussions, 
so I'm sure most of my complaints have already been addressed, but I'm 
going to air them out here anyways. Because I can. :-)

The foremost use cases in my head are the essentially interactive or 
demonstrative ones, not the literate programming ones. I think that 
people are going to use notebooks to run interactively or generate 
static, pretty documents. They are going to use the exported code to 
import or run on a server or whatever other "headless" activity. If you 
really want to be able to import from a notebook, you could write an 
import hook that will export the bare code and import that. (Disclosure: 
I never met a literate programming system that I liked.)

The markup-via-Python seems to me to be difficult to parse without 
running the code. Every time I make a markup change or spelling 
correction, my excessively long calculation will run again just to 
recreate a plot that I've already embedded in the notebook. I should be 
able to selectively run the code when I need to (re)generate output.

Name collisions. Or else evil hacks to avoid name collisions.

You can't embed these calls in functions because they won't get called 
until the function is run, not when that line of code is executed. And 
then they get called every time that function gets called.

I don't think that any-old-text-editor is a viable target. It just 
doesn't provide any of the real notebook capabilities. Targetting it as 
an intermediate platform before a GUI shell is available sacrifices the 
capabilities that the GUI shell is going to provide.

Allow me to make a suggestion for an intermediate target: Modify ipython 
to make a notebook file (in whatever format you go forward with) as a 
kind of log. At minimum, it just writes out the In[NN]'s and Out[NN]'s 
in the notebook format. Add a %magic to write out notes to the notebook. 
Nothing fancy or formatted, they'd mostly be just reminders that you 
would expand and format later, not the final markup. If you're on a 
roll, add another %magic for pylab mode that will save the current 
figure as a .png and write out an entry to the notebook for including an 

If the format is mildly human editable (I'm thinking something on the 
level of basic HTML as my standard for human editability here), then a 
basic text editor could be used to expand those reminders, add markup, 
add titles, and that whole jazz. Now that I think about it, you will 
want a script that can read a notebook file, rerun all of the In[NN]'s 
to (re)generate their Out[NN]'s.

The next step would be to write a wxPython (or other) editor that knows 
the structure of the notebook file and can do real WYSIWY{G,M} rich text 
editing and syntax coloration and image embedding, but no running of code.

The final step would be to implement the shell parts. Every step along 
the way is a smooth, evolutionary transition.

And now that I've convinced you that all I'm off my rocker, I'll also 
add that XML might actually be a reasonable choice for the meta-format 
of the notebook file. But since that choice assumes that you've agreed 
with everything else I've said, I'll let my explanation wait until 
people give me feedback on that.

> 2. usage targets of the library
> ReST and LaTEX are pretty clear, but how about possible other types of 
> documents, like ones with dynamic / interactive content -- should that 
> be addressed by the notebook lib? e.g. Slithy 
> (http://isotropic.org/uw/slithy/) provides a pretty nice way to make 
> dynamic/interactive diagrams with python (as functions that receive vars 
> (user controllable with slides in the player, and/or time for 
> animations) and output drawings). what (other) usages should be 
> considered? or only 'print targeted' stuff (like the mathreader things 
> seem almost like pdf)?

For this summer, just assume that anything that wants to do something 
funky will create a context in which to do it. Leave how that happens up 
to the people writing the GUI. Allow things to fail gracefully when it 
doesn't make sense (e.g. Pygame animations in HTML).

> one other area here is linking, which 
> rest/latex/pdf and of course html do support too, and there perhaps 
> granularity .. like to have support for so-called 'purple numbers' 
> http://www.eekim.com/software/purple/purple.html .

Intra-notebook linking gets a big +1 from me. As an offhand thought, 
every time In[NN] or Out[NN] is used in an expression, it should get a 
link back to the original when the expression is being syntax colored.

> 3. markup
> is something like Stan from twisted.nevow considered nice? 
> http://nevow.com/ , http://nevowexamples.adytum.us/sources/hellostan.py

Yes. Or any of the other umpteen syntax colorers.

> 4. ipython and non-ipython
> i suppose the basic notebook module would be independent from ipython, 
> and then some separate glue for it would be made for ipython (in the 
> ipython cvs), like has been done with gnuplot - right? or is there 
> something ipython specific about the project i'm missing? indeed the 
> real-time / interactive aspect is interesting, but does that imply much 
> for the API design? and in this case, should be a separate project, 
> hosted on some of the sourceforge forks (berlios, gna.org or something?) 
> .. would 'notebook' be a good name for the package, and pynotebook for 
> the project, or what? or is it more tied to ipython and should start there?

Development should probably be done on the scipy.org server. Hopefully 
the SVN server will be up soon for ipython. Most of the development will 
probably happen outside of the ipython tree itself, I imagine.

I recommend against pynotebook. It's redundant and duplicative.

Robert Kern
rkern at ucsd.edu

"In the fields of hell where the grass grows high
  Are the graves of dreams allowed to die."
   -- Richard Harter

More information about the IPython-dev mailing list