Collecting Python's responses.

[Jacek Generowicz]

I'm looking for ways of creating annotated records of Python
interactive sessions, for documentation purposes. For example,
something like

   # dir shows the contents of the namespace
   >>> dir()
   ['__builtins__', '__doc__', '__name__']
   # Addition works too
   >>> 1+2
   3

However, I would like to automate the incorporation of Python's actual
output, so I would like to run a program which looks something like
this:


   session(text('dir shows the contents of the namespace'),
           code('dir()'),
           text('Addition works too'),
           code('1+2'))

which would somehow send the code to a Python process, collect the
response, and interleave the two with the annotation text to create
HTML output, or commented Python source code (or some other format for
which I provide a back end).

Does anything like this exitst? If not, any suggestions how best to go
about it. (The popen family seems unsuitable because of buffering
deadlocks, I'd rather not use telnetlib ...)