Small fix in ultraTB, and fix autocall.

Add Scott's patch (issue 48) to fix the new fix_syntax hook.

I started updating the copyright notices, but I don't really think that's
worth doing or even necessary (adding the 2006 year mark).  That's why so
many files appear changed, though the functional diff is fairly small.

IPython/ColorANSI.py

@@ -1,164 +1,164 b''
 # -*- coding: utf-8 -*-
 """Tools for coloring text in ANSI terminals.
 
-$Id: ColorANSI.py 951 2005-12-25 00:57:24Z fperez $"""
+$Id: ColorANSI.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2002-2004 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2002-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 __all__ = ['TermColors','InputTermColors','ColorScheme','ColorSchemeTable']
 
 import os
 
 from IPython.Struct import Struct
 
 def make_color_table(in_class):
     """Build a set of color attributes in a class.
 
     Helper function for building the *TermColors classes."""
     
     color_templates = (
         ("Black"       , "0;30"),
         ("Red"         , "0;31"),
         ("Green"       , "0;32"),
         ("Brown"       , "0;33"),
         ("Blue"        , "0;34"),
         ("Purple"      , "0;35"),
         ("Cyan"        , "0;36"),
         ("LightGray"   , "0;37"),
         ("DarkGray"    , "1;30"),
         ("LightRed"    , "1;31"),
         ("LightGreen"  , "1;32"),
         ("Yellow"      , "1;33"),
         ("LightBlue"   , "1;34"),
         ("LightPurple" , "1;35"),
         ("LightCyan"   , "1;36"),
         ("White"       , "1;37"),  )
 
     for name,value in color_templates:
         setattr(in_class,name,in_class._base % value)
 
 class TermColors:
     """Color escape sequences.
 
     This class defines the escape sequences for all the standard (ANSI?) 
     colors in terminals. Also defines a NoColor escape which is just the null
     string, suitable for defining 'dummy' color schemes in terminals which get
     confused by color escapes.
 
     This class should be used as a mixin for building color schemes."""
     
     NoColor = ''  # for color schemes in color-less terminals.
     Normal = '\033[0m'   # Reset normal coloring
     _base  = '\033[%sm'  # Template for all other colors
 
 # Build the actual color table as a set of class attributes:
 make_color_table(TermColors)
 
 class InputTermColors:
     """Color escape sequences for input prompts.
 
     This class is similar to TermColors, but the escapes are wrapped in \001
     and \002 so that readline can properly know the length of each line and
     can wrap lines accordingly.  Use this class for any colored text which
     needs to be used in input prompts, such as in calls to raw_input().
 
     This class defines the escape sequences for all the standard (ANSI?) 
     colors in terminals. Also defines a NoColor escape which is just the null
     string, suitable for defining 'dummy' color schemes in terminals which get
     confused by color escapes.
 
     This class should be used as a mixin for building color schemes."""
     
     NoColor = ''  # for color schemes in color-less terminals.
     Normal = '\001\033[0m\002'   # Reset normal coloring
     _base  = '\001\033[%sm\002'  # Template for all other colors
 
 # Build the actual color table as a set of class attributes:
 make_color_table(InputTermColors)
 
 class ColorScheme:
     """Generic color scheme class. Just a name and a Struct."""
     def __init__(self,__scheme_name_,colordict=None,**colormap):
         self.name = __scheme_name_
         if colordict is None:
             self.colors = Struct(**colormap)
         else:
             self.colors = Struct(colordict)
 
     def copy(self,name=None):
         """Return a full copy of the object, optionally renaming it."""
         if name is None:
             name = self.name
         return ColorScheme(name,self.colors.__dict__)
         
 class ColorSchemeTable(dict):
     """General class to handle tables of color schemes.
 
     It's basically a dict of color schemes with a couple of shorthand
     attributes and some convenient methods.
     
     active_scheme_name -> obvious
     active_colors -> actual color table of the active scheme"""
 
     def __init__(self,scheme_list=None,default_scheme=''):
         """Create a table of color schemes.
 
         The table can be created empty and manually filled or it can be
         created with a list of valid color schemes AND the specification for
         the default active scheme.
         """
         
         # create object attributes to be set later
         self.active_scheme_name = ''
         self.active_colors = None
         
         if scheme_list:
             if default_scheme == '':
                 raise ValueError,'you must specify the default color scheme'
             for scheme in scheme_list:
                 self.add_scheme(scheme)
             self.set_active_scheme(default_scheme)
 
     def copy(self):
         """Return full copy of object"""
         return ColorSchemeTable(self.values(),self.active_scheme_name)
 
     def add_scheme(self,new_scheme):
         """Add a new color scheme to the table."""
         if not isinstance(new_scheme,ColorScheme):
             raise ValueError,'ColorSchemeTable only accepts ColorScheme instances'
         self[new_scheme.name] = new_scheme
         
     def set_active_scheme(self,scheme,case_sensitive=0):
         """Set the currently active scheme.
 
         Names are by default compared in a case-insensitive way, but this can
         be changed by setting the parameter case_sensitive to true."""
 
         scheme_names = self.keys()
         if case_sensitive:
             valid_schemes = scheme_names
             scheme_test = scheme
         else:
             valid_schemes = [s.lower() for s in scheme_names]
             scheme_test = scheme.lower()
         try:
             scheme_idx = valid_schemes.index(scheme_test)
         except ValueError:
             raise ValueError,'Unrecognized color scheme: ' + scheme + \
                   '\nValid schemes: '+str(scheme_names).replace("'', ",'')
         else:
             active = scheme_names[scheme_idx]
             self.active_scheme_name = active
             self.active_colors = self[active].colors
             # Now allow using '' as an index for the current active scheme
             self[''] = self[active]

IPython/ConfigLoader.py

@@ -1,116 +1,116 b''
 # -*- coding: utf-8 -*-
 """Configuration loader
 
-$Id: ConfigLoader.py 958 2005-12-27 23:17:51Z fperez $"""
+$Id: ConfigLoader.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 import exceptions
 import os
 from pprint import pprint
 
 from IPython import ultraTB
 from IPython.Struct import Struct
 from IPython.genutils import *
 
 class ConfigLoaderError(exceptions.Exception):
     """Exception for ConfigLoader class."""
 
     def __init__(self,args=None):
         self.args = args
 
 class ConfigLoader:
 
     """Configuration file loader capable of handling recursive inclusions and
     with parametrized conflict resolution for multiply found keys."""
 
     def __init__(self,conflict=None,field_sep=None,reclimit=15):
 
         """The reclimit parameter controls the number of recursive
         configuration file inclusions. This way we can stop early on (before
         python's own recursion limit is hit) if there is a circular
         inclusion.
 
         - conflict: dictionary for conflict resolutions (see Struct.merge())
 
         """
         self.conflict = conflict
         self.field_sep = field_sep
         self.reset(reclimit)
         
     def reset(self,reclimit=15):
         self.reclimit = reclimit
         self.recdepth = 0
         self.included = []
         
     def load(self,fname,convert=None,recurse_key='',incpath = '.',**kw):
         """Load a configuration file, return the resulting Struct.
 
         Call: load_config(fname,convert=None,conflict=None,recurse_key='')
 
          - fname: file to load from.
          - convert: dictionary of type conversions (see read_dict())
          - recurse_key: keyword in dictionary to trigger recursive file
          inclusions.
          """
 
         if self.recdepth > self.reclimit:
             raise ConfigLoaderError, 'maximum recursive inclusion of rcfiles '+\
                   'exceeded: ' + `self.recdepth` + \
                   '.\nMaybe you have a circular chain of inclusions?'
         self.recdepth += 1
         fname = filefind(fname,incpath)
         data = Struct()
         # avoid including the same file more than once
         if fname in self.included:
             return data
         Xinfo = ultraTB.AutoFormattedTB()
         if convert==None and recurse_key : convert = {qwflat:recurse_key}
         # for production, change warn to 0:
         data.merge(read_dict(fname,convert,fs=self.field_sep,strip=1,
                              warn=0,no_empty=0,**kw))
         # keep track of successfully loaded files
         self.included.append(fname)
         if recurse_key in data.keys():
             for incfilename in data[recurse_key]:
                 found=0
                 try:
                     incfile = filefind(incfilename,incpath)
                 except IOError:
                     if os.name in ['nt','dos']:
                         try:
                             # Try again with '.ini' extension
                             incfilename += '.ini'
                             incfile = filefind(incfilename,incpath)
                         except IOError:
                             found = 0
                         else:
                             found = 1
                     else:
                         found = 0
                 else:
                     found = 1
                 if found:
                     try:
                         data.merge(self.load(incfile,convert,recurse_key,
                                              incpath,**kw),
                                    self.conflict)
                     except:
                         Xinfo()
                         warn('Problem loading included file: '+
                              `incfilename` + '. Ignoring it...')
                 else:
                     warn('File `%s` not found. Included by %s' % (incfilename,fname))
 
         return data
 
 # end ConfigLoader

IPython/CrashHandler.py

@@ -1,111 +1,111 b''
 # -*- coding: utf-8 -*-
 """sys.excepthook for IPython itself, leaves a detailed report on disk.
 
-$Id: CrashHandler.py 958 2005-12-27 23:17:51Z fperez $"""
+$Id: CrashHandler.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__   = '%s <%s>' % Release.authors['Fernando']
 __license__  = Release.license
 __version__  = Release.version
 
 #****************************************************************************
 # Required modules
 
 # From the standard library
 import os
 import sys
 from pprint import pprint,pformat
 
 # Homebrewed
 from IPython.Itpl import Itpl,itpl,printpl
 from IPython.ColorANSI import ColorScheme,ColorSchemeTable  # too long names
 from IPython import ultraTB
 from IPython.genutils import *
 
 #****************************************************************************
 class CrashHandler:
     """sys.excepthook for IPython itself, leaves a detailed report on disk."""
 
     def __init__(self,IP):
         self.IP = IP  # IPython instance
         self.bug_contact = Release.authors['Fernando'][0]
         self.mailto = Release.authors['Fernando'][1]
 
     def __call__(self,etype, evalue, etb):
 
         # Report tracebacks shouldn't use color in general (safer for users)
         color_scheme = 'NoColor'
 
         # Use this ONLY for developer debugging (keep commented out for release)
         #color_scheme = 'Linux'   # dbg
         
         try:
             rptdir = self.IP.rc.ipythondir
         except:
             rptdir = os.getcwd()
         if not os.path.isdir(rptdir):
             rptdir = os.getcwd()
         self.report_name = os.path.join(rptdir,'IPython_crash_report.txt')
         self.TBhandler = ultraTB.VerboseTB(color_scheme=color_scheme,long_header=1)
         traceback = self.TBhandler.text(etype,evalue,etb,context=31)
 
         # print traceback to screen
         print >> sys.stderr, traceback
 
         # and generate a complete report on disk
         try:
             report = open(self.report_name,'w')
         except:
             print >> sys.stderr, 'Could not create crash report on disk.'
             return
 
         msg = itpl('\n'+'*'*70+'\n'
 """
 Oops, IPython crashed. We do our best to make it stable, but...
 
 A crash report was automatically generated with the following information:
   - A verbatim copy of the traceback above this text.
   - A copy of your input history during this session.
   - Data on your current IPython configuration.
 
 It was left in the file named:
 \t'$self.report_name'
 If you can email this file to the developers, the information in it will help
 them in understanding and correcting the problem.
 
 You can mail it to $self.bug_contact at $self.mailto
 with the subject 'IPython Crash Report'.
 
 If you want to do it now, the following command will work (under Unix):
 mail -s 'IPython Crash Report' $self.mailto < $self.report_name
 
 To ensure accurate tracking of this issue, please file a report about it at:
 http://www.scipy.net/roundup/ipython  (IPython's online bug tracker).
 """)
         print >> sys.stderr, msg
 
         sec_sep = '\n\n'+'*'*75+'\n\n'
         report.write('*'*75+'\n\n'+'IPython post-mortem report\n\n')
         report.write('IPython version: %s \n\n' % Release.version)
         report.write('SVN revision   : %s \n\n' % Release.revision)
         report.write('Platform info  : os.name -> %s, sys.platform -> %s' %
                      (os.name,sys.platform) )
         report.write(sec_sep+'Current user configuration structure:\n\n')
         report.write(pformat(self.IP.rc.dict()))
         report.write(sec_sep+'Crash traceback:\n\n' + traceback)
         try:
             report.write(sec_sep+"History of session input:")
             for line in self.IP.user_ns['_ih']:
                 report.write(line)
             report.write('\n*** Last line of input (may not be in above history):\n')
             report.write(self.IP._last_input_line+'\n')
         except:
             pass
         report.close()

IPython/Debugger.py

@@ -1,270 +1,286 b''
 # -*- coding: utf-8 -*-
 """
 Pdb debugger class.
 
 Modified from the standard pdb.Pdb class to avoid including readline, so that
 the command line completion of other programs which include this isn't
 damaged.
 
 In the future, this class will be expanded with improvements over the standard
 pdb.
 
 The code in this file is mainly lifted out of cmd.py in Python 2.2, with minor
 changes. Licensing should therefore be under the standard Python terms.  For
 details on the PSF (Python Software Foundation) standard license, see:
 
 http://www.python.org/2.2.3/license.html
 
-$Id: Debugger.py 958 2005-12-27 23:17:51Z fperez $"""
+$Id: Debugger.py 994 2006-01-08 08:29:44Z fperez $"""
+
+#*****************************************************************************
+#
+# Since this file is essentially a modified copy of the pdb module which is
+# part of the standard Python distribution, I assume that the proper procedure
+# is to maintain its copyright as belonging to the Python Software Foundation
+# (in addition to my own, for all new code).
+#
+#       Copyright (C) 2001 Python Software Foundation, www.python.org
+#       Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#
+#*****************************************************************************
+
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = 'Python'
 
 import bdb
 import cmd
 import linecache
 import os
 import pdb
 import sys
 
 from IPython import PyColorize, ColorANSI
 from IPython.genutils import Term
 from IPython.excolors import ExceptionColors
 
 def _file_lines(fname):
     """Return the contents of a named file as a list of lines.
 
     This function never raises an IOError exception: if the file can't be
     read, it simply returns an empty list."""
 
     try:
         outfile = open(fname)
     except IOError:
         return []
     else:
         out = outfile.readlines()
         outfile.close()
         return out
 
 
 class Pdb(pdb.Pdb):
     """Modified Pdb class, does not load readline."""
     def __init__(self,color_scheme='NoColor'):
         bdb.Bdb.__init__(self)
         cmd.Cmd.__init__(self,completekey=None) # don't load readline
         self.prompt = 'ipdb> ' # The default prompt is '(Pdb)'
         self.aliases = {}
 
         # Read $HOME/.pdbrc and ./.pdbrc
         try:
             self.rcLines = _file_lines(os.path.join(os.environ['HOME'],
                                                     ".pdbrc"))
         except KeyError:
             self.rcLines = []
         self.rcLines.extend(_file_lines(".pdbrc"))
 
         # Create color table: we copy the default one from the traceback
         # module and add a few attributes needed for debugging
         self.color_scheme_table = ExceptionColors.copy()
         
         # shorthands 
         C = ColorANSI.TermColors
         cst = self.color_scheme_table
 
         cst['NoColor'].colors.breakpoint_enabled = C.NoColor
         cst['NoColor'].colors.breakpoint_disabled = C.NoColor
 
         cst['Linux'].colors.breakpoint_enabled = C.LightRed
         cst['Linux'].colors.breakpoint_disabled = C.Red
 
         cst['LightBG'].colors.breakpoint_enabled = C.LightRed
         cst['LightBG'].colors.breakpoint_disabled = C.Red
 
         self.set_colors(color_scheme)
         
     def set_colors(self, scheme):
         """Shorthand access to the color table scheme selector method."""
         self.color_scheme_table.set_active_scheme(scheme)
 
 
     def interaction(self, frame, traceback):
         __IPYTHON__.set_completer_frame(frame)
         pdb.Pdb.interaction(self, frame, traceback)
 
 
     def do_up(self, arg):
         pdb.Pdb.do_up(self, arg)
         __IPYTHON__.set_completer_frame(self.curframe)
     do_u = do_up
 
 
     def do_down(self, arg):
         pdb.Pdb.do_down(self, arg)
         __IPYTHON__.set_completer_frame(self.curframe)
     do_d = do_down
 
 
     def postloop(self):
         __IPYTHON__.set_completer_frame(None)
 
 
     def print_stack_trace(self):
         try:
             for frame_lineno in self.stack:
                 self.print_stack_entry(frame_lineno, context = 5)
         except KeyboardInterrupt:
             pass
 
 
     def print_stack_entry(self,frame_lineno,prompt_prefix='\n-> ',
                           context = 3):
         frame, lineno = frame_lineno
         print >>Term.cout, self.format_stack_entry(frame_lineno, '', context)
 
 
     def format_stack_entry(self, frame_lineno, lprefix=': ', context = 3):
         import linecache, repr
         
         ret = ""
         
         Colors = self.color_scheme_table.active_colors
         ColorsNormal = Colors.Normal
         tpl_link = '%s%%s%s' % (Colors.filenameEm, ColorsNormal)
         tpl_call = 'in %s%%s%s%%s%s' % (Colors.vName, Colors.valEm, ColorsNormal)
         tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
         tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line,
                                             ColorsNormal)
         
         frame, lineno = frame_lineno
         
         return_value = ''
         if '__return__' in frame.f_locals:
             rv = frame.f_locals['__return__']
             #return_value += '->'
             return_value += repr.repr(rv) + '\n'
         ret += return_value
 
         #s = filename + '(' + `lineno` + ')'
         filename = self.canonic(frame.f_code.co_filename)
         link = tpl_link % filename
         
         if frame.f_code.co_name:
             func = frame.f_code.co_name
         else:
             func = "<lambda>"
             
         call = ''
         if func != '?':         
             if '__args__' in frame.f_locals:
                 args = repr.repr(frame.f_locals['__args__'])
             else:
                 args = '()'
             call = tpl_call % (func, args)
         
         level = '%s %s\n' % (link, call)
         ret += level
             
         start = lineno - 1 - context//2
         lines = linecache.getlines(filename)
         start = max(start, 0)
         start = min(start, len(lines) - context)
         lines = lines[start : start + context]
             
         for i in range(len(lines)):
             line = lines[i]
             if start + 1 + i == lineno:
                 ret += self.__format_line(tpl_line_em, filename, start + 1 + i, line, arrow = True)
             else:
                 ret += self.__format_line(tpl_line, filename, start + 1 + i, line, arrow = False)
             
         return ret
 
 
     def __format_line(self, tpl_line, filename, lineno, line, arrow = False):
         bp_mark = ""
         bp_mark_color = ""
 
         bp = None
         if lineno in self.get_file_breaks(filename):
             bps = self.get_breaks(filename, lineno)
             bp = bps[-1]
         
         if bp:
             Colors = self.color_scheme_table.active_colors
             bp_mark = str(bp.number)
             bp_mark_color = Colors.breakpoint_enabled
             if not bp.enabled:
                 bp_mark_color = Colors.breakpoint_disabled
 
         numbers_width = 7
         if arrow:
             # This is the line with the error
             pad = numbers_width - len(str(lineno)) - len(bp_mark)
             if pad >= 3:
                 marker = '-'*(pad-3) + '-> '
             elif pad == 2:
                  marker = '> '
             elif pad == 1:
                  marker = '>'
             else:
                  marker = ''
             num = '%s%s' % (marker, str(lineno))
             line = tpl_line % (bp_mark_color + bp_mark, num, line)
         else:
             num = '%*s' % (numbers_width - len(bp_mark), str(lineno))
             line = tpl_line % (bp_mark_color + bp_mark, num, line)
             
         return line
         
 
     def do_list(self, arg):
         self.lastcmd = 'list'
         last = None
         if arg:
             try:
                 x = eval(arg, {}, {})
                 if type(x) == type(()):
                     first, last = x
                     first = int(first)
                     last = int(last)
                     if last < first:
                         # Assume it's a count
                         last = first + last
                 else:
                     first = max(1, int(x) - 5)
             except:
                 print '*** Error in argument:', `arg`
                 return
         elif self.lineno is None:
             first = max(1, self.curframe.f_lineno - 5)
         else:
             first = self.lineno + 1
         if last is None:
             last = first + 10
         filename = self.curframe.f_code.co_filename
         try:
             Colors = self.color_scheme_table.active_colors
             ColorsNormal = Colors.Normal
             tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
             tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line, ColorsNormal)
             src = []
             for lineno in range(first, last+1):
                 line = linecache.getline(filename, lineno)
                 if not line:
                     break
 
                 if lineno == self.curframe.f_lineno:
                     line = self.__format_line(tpl_line_em, filename, lineno, line, arrow = True)
                 else:
                     line = self.__format_line(tpl_line, filename, lineno, line, arrow = False)
 
                 src.append(line)
                 self.lineno = lineno
 
             print >>Term.cout, ''.join(src)
 
         except KeyboardInterrupt:
             pass
 
     do_l = do_list

IPython/Extensions/InterpreterExec.py

@@ -1,272 +1,272 b''
 # -*- coding: utf-8 -*-
 """Modified input prompt for executing files.
 
 We define a special input line filter to allow typing lines which begin with
 '~', '/' or '.'. If one of those strings is encountered, it is automatically
 executed.
 
-$Id: InterpreterExec.py 638 2005-07-18 03:01:41Z fperez $"""
+$Id: InterpreterExec.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
 #       Copyright (C) 2004 W.J. van der Laan <[e-mail]>
-#       Copyright (C) 2004 Fernando Perez <[e-mail]>
+#       Copyright (C) 2004-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__ = 'W.J. van der Laan <[e-mail]>, '\
              '%s <%s>' %  Release.authors['Fernando']
 __license__ = Release.license
 
 def prefilter_shell(self,line,continuation):
     """Alternate prefilter, modified for shell-like functionality.
 
     - Execute all lines beginning with '~', '/' or '.'
     - $var=cmd <=> %sc var=cmd
     - $$var=cmd <=> %sc -l var=cmd
     """
 
     if line:
         l0 = line[0]
         if l0 in '~/.':
             return self._prefilter("!%s"%line,continuation)
         elif l0=='$':
             lrest = line[1:]
             if lrest.startswith('$'):
                 # $$var=cmd <=> %sc -l var=cmd
                 return self._prefilter("%ssc -l %s" % (self.ESC_MAGIC,lrest[1:]),
                                        continuation)
             else:
                 # $var=cmd <=> %sc var=cmd
                 return self._prefilter("%ssc %s" % (self.ESC_MAGIC,lrest),
                                        continuation)
         else:
             return self._prefilter(line,continuation)
     else:
         return self._prefilter(line,continuation)
 
 # Rebind this to be the new IPython prefilter:
 from IPython.iplib import InteractiveShell
 InteractiveShell.prefilter = prefilter_shell
 # Clean up the namespace.
 del InteractiveShell,prefilter_shell
 
 # Provide pysh and further shell-oriented services
 import os,sys,shutil
 from IPython.genutils import system,shell,getoutput,getoutputerror
 
 # Short aliases for getting shell output as a string and a list
 sout = getoutput
 lout = lambda cmd: getoutput(cmd,split=1)
 
 # Empty function, meant as a docstring holder so help(pysh) works.
 def pysh():
     """Pysh is a set of modules and extensions to IPython which make shell-like
     usage with Python syntax more convenient.  Keep in mind that pysh is NOT a
     full-blown shell, so don't try to make it your /etc/passwd entry!
     
     In particular, it has no job control, so if you type Ctrl-Z (under Unix),
     you'll suspend pysh itself, not the process you just started.
 
     Since pysh is really nothing but a customized IPython, you should
     familiarize yourself with IPython's features.  This brief help mainly
     documents areas in which pysh differs from the normal IPython.
 
     ALIASES
     -------
     All of your $PATH has been loaded as IPython aliases, so you should be
     able to type any normal system command and have it executed.  See %alias? 
     and %unalias? for details on the alias facilities.
 
     SPECIAL SYNTAX
     --------------
     Any lines which begin with '~', '/' and '.' will be executed as shell
     commands instead of as Python code. The special escapes below are also
     recognized.  !cmd is valid in single or multi-line input, all others are
     only valid in single-line input:
 
     !cmd      - pass 'cmd' directly to the shell
     !!cmd     - execute 'cmd' and return output as a list (split on '\\n')
     $var=cmd  - capture output of cmd into var, as a string
     $$var=cmd - capture output of cmd into var, as a list (split on '\\n')
 
     The $/$$ syntaxes make Python variables from system output, which you can
     later use for further scripting.  The converse is also possible: when
     executing an alias or calling to the system via !/!!, you can expand any
     python variable or expression by prepending it with $.  Full details of
     the allowed syntax can be found in Python's PEP 215.
 
     A few brief examples will illustrate these:
 
         fperez[~/test]|3> !ls *s.py
         scopes.py  strings.py
 
     ls is an internal alias, so there's no need to use !:
         fperez[~/test]|4> ls *s.py
         scopes.py*  strings.py
 
     !!ls will return the output into a Python variable:
         fperez[~/test]|5> !!ls *s.py
                       <5> ['scopes.py', 'strings.py']
         fperez[~/test]|6> print _5
         ['scopes.py', 'strings.py']
 
     $ and $$ allow direct capture to named variables:
         fperez[~/test]|7> $astr = ls *s.py
         fperez[~/test]|8> astr
                       <8> 'scopes.py\\nstrings.py'
 
         fperez[~/test]|9> $$alist = ls *s.py
         fperez[~/test]|10> alist
                       <10> ['scopes.py', 'strings.py']
 
     alist is now a normal python list you can loop over.  Using $ will expand
     back the python values when alias calls are made:
         fperez[~/test]|11> for f in alist:
                       |..>     print 'file',f,
                       |..>     wc -l $f
                       |..>
         file scopes.py     13 scopes.py
         file strings.py      4 strings.py
 
     Note that you may need to protect your variables with braces if you want
     to append strings to their names.  To copy all files in alist to .bak
     extensions, you must use:
         fperez[~/test]|12> for f in alist:
                       |..>     cp $f ${f}.bak
 
     If you try using $f.bak, you'll get an AttributeError exception saying
     that your string object doesn't have a .bak attribute.  This is because
     the $ expansion mechanism allows you to expand full Python expressions:
         fperez[~/test]|13> echo "sys.platform is: $sys.platform"
         sys.platform is: linux2
 
     IPython's input history handling is still active, which allows you to
     rerun a single block of multi-line input by simply using exec:    
         fperez[~/test]|14> $$alist = ls *.eps
         fperez[~/test]|15> exec _i11
         file image2.eps    921 image2.eps
         file image.eps    921 image.eps
 
     While these are new special-case syntaxes, they are designed to allow very
     efficient use of the shell with minimal typing.  At an interactive shell
     prompt, conciseness of expression wins over readability.
 
     USEFUL FUNCTIONS AND MODULES
     ----------------------------
     The os, sys and shutil modules from the Python standard library are
     automatically loaded.  Some additional functions, useful for shell usage,
     are listed below.  You can request more help about them with '?'.
 
     shell   - execute a command in the underlying system shell    
     system  - like shell(), but return the exit status of the command
     sout    - capture the output of a command as a string
     lout    - capture the output of a command as a list (split on '\\n')
     getoutputerror - capture (output,error) of a shell command
 
     sout/lout are the functional equivalents of $/$$.  They are provided to
     allow you to capture system output in the middle of true python code,
     function definitions, etc (where $ and $$ are invalid).
 
     DIRECTORY MANAGEMENT
     --------------------
     Since each command passed by pysh to the underlying system is executed in
     a subshell which exits immediately, you can NOT use !cd to navigate the
     filesystem.
 
     Pysh provides its own builtin '%cd' magic command to move in the
     filesystem (the % is not required with automagic on).  It also maintains a
     list of visited directories (use %dhist to see it) and allows direct
     switching to any of them.  Type 'cd?' for more details.
 
     %pushd, %popd and %dirs are provided for directory stack handling.
 
     PROMPT CUSTOMIZATION
     --------------------
     
     The supplied ipythonrc-pysh profile comes with an example of a very
     colored and detailed prompt, mainly to serve as an illustration.  The
     valid escape sequences, besides color names, are:
 
         \\#  - Prompt number.
         \\D  - Dots, as many as there are digits in \\# (so they align).
         \\w  - Current working directory (cwd).
         \\W  - Basename of current working directory.
         \\XN - Where N=0..5. N terms of the cwd, with $HOME written as ~.
         \\YN - Where N=0..5. Like XN, but if ~ is term N+1 it's also shown.
         \\u  - Username.
         \\H  - Full hostname.
         \\h  - Hostname up to first '.'
         \\$  - Root symbol ($ or #).
         \\t  - Current time, in H:M:S format.
         \\v  - IPython release version.
         \\n  - Newline.
         \\r  - Carriage return.
         \\\\ - An explicitly escaped '\\'.
 
     You can configure your prompt colors using any ANSI color escape.  Each
     color escape sets the color for any subsequent text, until another escape
     comes in and changes things.  The valid color escapes are:
 
         \\C_Black
         \\C_Blue
         \\C_Brown
         \\C_Cyan
         \\C_DarkGray
         \\C_Green
         \\C_LightBlue
         \\C_LightCyan
         \\C_LightGray
         \\C_LightGreen
         \\C_LightPurple
         \\C_LightRed
         \\C_Purple
         \\C_Red
         \\C_White
         \\C_Yellow
         \\C_Normal - Stop coloring, defaults to your terminal settings.
     """
     pass
 
 # Configure a few things.  Much of this is fairly hackish, since IPython
 # doesn't really expose a clean API for it.  Be careful if you start making
 # many modifications here.
 
 print """\
 Welcome to pysh, a set of extensions to IPython for shell usage.
 help(pysh) -> help on the installed shell extensions and syntax.
 """
 
 #  Set the 'cd' command to quiet mode, a more shell-like behavior
 __IPYTHON__.default_option('cd','-q')
 
 # Load all of $PATH as aliases
 if os.name == 'posix':
     # %rehash is very fast, but it doesn't check for executability, it simply
     # dumps everything in $PATH as an alias. Use rehashx if you want more
     # checks.
     __IPYTHON__.magic_rehash()
 else:
     # Windows users: the list of extensions considered executable is read from
     # the environment variable 'pathext'.  If this is undefined, IPython
     # defaults to EXE, COM and BAT.
     # %rehashx is the one which does extension analysis, at the cost of
     # being much slower than %rehash.
     __IPYTHON__.magic_rehashx()
 
 # Remove %sc,%sx if present as aliases
 __IPYTHON__.magic_unalias('sc')
 __IPYTHON__.magic_unalias('sx')
 
 # We need different criteria for line-splitting, so that aliases such as
 # 'gnome-terminal' are interpreted as a single alias instead of variable
 # 'gnome' minus variable 'terminal'.
 import re
 __IPYTHON__.line_split = re.compile(r'^([\s*,;/])'
                                     r'([\?\w\.\-\+]+\w*\s*)'
                                     r'(\(?.*$)')
 
 # Namespace cleanup
 del re

IPython/Extensions/InterpreterPasteInput.py

@@ -1,91 +1,91 b''
 # -*- coding: utf-8 -*-
 """Modified input prompt for entering text with >>> or ... at the start.
 
 We define a special input line filter to allow typing lines which begin with
 '>>> ' or '... '. These two strings, if present at the start of the input
 line, are stripped. This allows for direct pasting of code from examples such
 as those available in the standard Python tutorial.
 
 Normally pasting such code is one chunk is impossible because of the
 extraneous >>> and ..., requiring one to do a line by line paste with careful
 removal of those characters. This module allows pasting that kind of
 multi-line examples in one pass.
 
 Here is an 'screenshot' of a section of the tutorial pasted into IPython with
 this feature enabled:
 
 In [1]: >>> def fib2(n): # return Fibonacci series up to n
    ...: ...     '''Return a list containing the Fibonacci series up to n.'''
    ...: ...     result = []
    ...: ...     a, b = 0, 1
    ...: ...     while b < n:
    ...: ...         result.append(b)    # see below
    ...: ...         a, b = b, a+b
    ...: ...     return result
    ...:
 
 In [2]: fib2(10)
 Out[2]: [1, 1, 2, 3, 5, 8]
 
 The >>> and ... are stripped from the input so that the python interpreter
 only sees the real part of the code.
 
 All other input is processed normally.
 """
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 # This file is an example of how to modify IPython's line-processing behavior
 # without touching the internal code. We'll define an alternate pre-processing
 # stage which allows a special form of input (which is invalid Python syntax)
 # for certain quantities, rewrites a line of proper Python in those cases, and
 # then passes it off to IPython's normal processor for further work.
 
 # With this kind of customization, IPython can be adapted for many
 # special-purpose scenarios providing alternate input syntaxes.
 
 # This file can be imported like a regular module.
 
 # IPython has a prefilter() function that analyzes each input line. We redefine
 # it here to first pre-process certain forms of input
 
 # The prototype of any alternate prefilter must be like this one (the name
 # doesn't matter):
 # - line is a string containing the user input line.
 # - continuation is a parameter which tells us if we are processing a first line of
 #   user input or the second or higher of a multi-line statement.
 
 def prefilter_paste(self,line,continuation):
     """Alternate prefilter for input of pasted code from an interpreter.
     """
 
     from re import match
 
     if match(r'^>>> |^\.\.\. ',line):
         # In the end, always call the default IPython _prefilter() function.
         # Note that self must be passed explicitly, b/c we're calling the
         # unbound class method (since this method will overwrite the instance
         # prefilter())
         return self._prefilter(line[4:],continuation)
     elif line.strip() == '...':
         return self._prefilter('',continuation)
     else:
         return self._prefilter(line,continuation)
             
 # Rebind this to be the new IPython prefilter:
 from IPython.iplib import InteractiveShell
 InteractiveShell.prefilter = prefilter_paste
 
 # Clean up the namespace.
 del InteractiveShell,prefilter_paste
 
 # Just a heads up at the console
 print '*** Pasting of code with ">>>" or "..." has been enabled.'

IPython/Logger.py

@@ -1,233 +1,233 b''
 # -*- coding: utf-8 -*-
 """
 Logger class for IPython's logging facilities.
 
-$Id: Logger.py 988 2006-01-02 21:21:47Z fperez $
+$Id: Logger.py 994 2006-01-08 08:29:44Z fperez $
 """
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
-#       Copyright (C) 2001-2005 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 #****************************************************************************
 # Modules and globals
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % \
               ( Release.authors['Janko'] + Release.authors['Fernando'] )
 __license__ = Release.license
 
 # Python standard modules
 import glob
 import os
 import time
 
 #****************************************************************************
 # FIXME: This class isn't a mixin anymore, but it still needs attributes from
 # ipython and does input cache management.  Finish cleanup later...
 
 class Logger(object):
     """A Logfile class with different policies for file creation"""
 
     def __init__(self,shell,logfname='Logger.log',loghead='',logmode='over'):
 
         self._i00,self._i,self._ii,self._iii = '','','',''
 
         # this is the full ipython instance, we need some attributes from it
         # which won't exist until later. What a mess, clean up later...
         self.shell = shell
 
         self.logfname = logfname
         self.loghead = loghead
         self.logmode = logmode
         self.logfile = None
 
         # whether to also log output
         self.log_output = False
 
         # whether to put timestamps before each log entry
         self.timestamp = False
 
         # activity control flags
         self.log_active = False
 
     # logmode is a validated property
     def _set_mode(self,mode):
         if mode not in ['append','backup','global','over','rotate']:
             raise ValueError,'invalid log mode %s given' % mode
         self._logmode = mode
 
     def _get_mode(self):
         return self._logmode
 
     logmode = property(_get_mode,_set_mode)
     
     def logstart(self,logfname=None,loghead=None,logmode=None,
                  log_output=False,timestamp=False):
         """Generate a new log-file with a default header.
 
         Raises RuntimeError if the log has already been started"""
 
         if self.logfile is not None:
             raise RuntimeError('Log file is already active: %s' %
                                self.logfname)
         
         self.log_active = True
 
         # The three parameters can override constructor defaults
         if logfname: self.logfname = logfname
         if loghead: self.loghead = loghead
         if logmode: self.logmode = logmode
         self.timestamp = timestamp
         self.log_output = log_output
         
         # init depending on the log mode requested
         isfile = os.path.isfile
         logmode = self.logmode
 
         if logmode == 'append':
             self.logfile = open(self.logfname,'a')
 
         elif logmode == 'backup':
             if isfile(self.logfname):
                 backup_logname = self.logfname+'~'
                 # Manually remove any old backup, since os.rename may fail
                 # under Windows.
                 if isfile(backup_logname):
                     os.remove(backup_logname)
                 os.rename(self.logfname,backup_logname)
             self.logfile = open(self.logfname,'w')
 
         elif logmode == 'global':
             self.logfname = os.path.join(self.shell.home_dir,self.logfname)
             self.logfile = open(self.logfname, 'a')
 
         elif logmode == 'over':
             if isfile(self.logfname):
                 os.remove(self.logfname) 
             self.logfile = open(self.logfname,'w')
 
         elif logmode == 'rotate':
             if isfile(self.logfname):
                 if isfile(self.logfname+'.001~'): 
                     old = glob.glob(self.logfname+'.*~')
                     old.sort()
                     old.reverse()
                     for f in old:
                         root, ext = os.path.splitext(f)
                         num = int(ext[1:-1])+1
                         os.rename(f, root+'.'+`num`.zfill(3)+'~')
                 os.rename(self.logfname, self.logfname+'.001~')
             self.logfile = open(self.logfname,'w')
             
         if logmode != 'append':
             self.logfile.write(self.loghead)
 
         self.logfile.flush()
 
     def switch_log(self,val):
         """Switch logging on/off. val should be ONLY a boolean."""
 
         if val not in [False,True,0,1]:
             raise ValueError, \
                   'Call switch_log ONLY with a boolean argument, not with:',val
         
         label = {0:'OFF',1:'ON',False:'OFF',True:'ON'}
 
         if self.logfile is None:
             print """
 Logging hasn't been started yet (use logstart for that).
 
 %logon/%logoff are for temporarily starting and stopping logging for a logfile
 which already exists. But you must first start the logging process with
 %logstart (optionally giving a logfile name)."""
             
         else:
             if self.log_active == val:
                 print 'Logging is already',label[val]
             else:
                 print 'Switching logging',label[val]
                 self.log_active = not self.log_active
                 self.log_active_out = self.log_active
 
     def logstate(self):
         """Print a status message about the logger."""
         if self.logfile is None:
             print 'Logging has not been activated.'
         else:
             state = self.log_active and 'active' or 'temporarily suspended'
             print 'Filename       :',self.logfname
             print 'Mode           :',self.logmode
             print 'Output logging :',self.log_output
             print 'Timestamping   :',self.timestamp
             print 'State          :',state
 
     def log(self, line,continuation=None):
         """Write the line to a log and create input cache variables _i*."""
 
         # update the auto _i tables
         #print '***logging line',line # dbg
         #print '***cache_count', self.shell.outputcache.prompt_count # dbg
         try:
             input_hist = self.shell.user_ns['_ih']
         except:
             print 'userns:',self.shell.user_ns.keys()
             return
         
         if not continuation and line:
             self._iii = self._ii
             self._ii = self._i
             self._i = self._i00
             # put back the final \n of every input line
             self._i00 = line+'\n'
             #print 'Logging input:<%s>' % line  # dbg
             input_hist.append(self._i00)
         #print '---[%s]' % (len(input_hist)-1,) # dbg
 
         # hackish access to top-level namespace to create _i1,_i2... dynamically
         to_main = {'_i':self._i,'_ii':self._ii,'_iii':self._iii}
         if self.shell.outputcache.do_full_cache:
             in_num = self.shell.outputcache.prompt_count
             # add blank lines if the input cache fell out of sync. This can
             # happen for embedded instances which get killed via C-D and then
             # get resumed.
             while in_num >= len(input_hist):
                 input_hist.append('\n')
             # but if the opposite is true (a macro can produce multiple inputs
             # with no output display called), then bring the output counter in
             # sync:
             last_num = len(input_hist)-1
             if in_num != last_num:
                 in_num = self.shell.outputcache.prompt_count = last_num
             new_i = '_i%s' % in_num
             if continuation:
                 self._i00 = '%s%s\n' % (self.shell.user_ns[new_i],line)
                 input_hist[in_num] = self._i00
             to_main[new_i] = self._i00
         self.shell.user_ns.update(to_main)
         self.log_write(line)
 
     def log_write(self,data,kind='input'):
         """Write data to the log file, if active"""
 
         if self.log_active and data:
             write = self.logfile.write
             if kind=='input':
                 if self.timestamp:
                     write(time.strftime('# %a, %d %b %Y %H:%M:%S\n',
                                         time.localtime()))
                 write('%s\n' % data)
             elif kind=='output' and self.log_output:
                 odata = '\n'.join(['#[Out]# %s' % s
                                    for s in data.split('\n')])
                 write('%s\n' % odata)
             self.logfile.flush()
 
     def close_log(self):
         self.logfile.close()
         self.logfile = None
         self.logfname = ''

IPython/Magic.py

@@ -1,2707 +1,2736 b''
 # -*- coding: utf-8 -*-
 """Magic functions for InteractiveShell.
 
-$Id: Magic.py 991 2006-01-04 18:15:34Z fperez $"""
+$Id: Magic.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
-#       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 #****************************************************************************
 # Modules and globals
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % \
               ( Release.authors['Janko'] + Release.authors['Fernando'] )
 __license__ = Release.license
 
 # Python standard modules
 import __builtin__
 import bdb
 import inspect
 import os
 import pdb
 import pydoc
 import sys
 import re
 import tempfile
 import time
 import cPickle as pickle
 from cStringIO import StringIO
 from getopt import getopt
 from pprint import pprint, pformat
 
 # profile isn't bundled by default in Debian for license reasons
 try:
     import profile,pstats
 except ImportError:
     profile = pstats = None
 
 # Homebrewed
 from IPython import Debugger, OInspect, wildcard
 from IPython.FakeModule import FakeModule
 from IPython.Itpl import Itpl, itpl, printpl,itplns
 from IPython.PyColorize import Parser
 from IPython.Struct import Struct
 from IPython.macro import Macro
 from IPython.genutils import *
 
 #***************************************************************************
 # Utility functions
 def on_off(tag):
     """Return an ON/OFF string for a 1/0 input. Simple utility function."""
     return ['OFF','ON'][tag]
 
+class Bunch: pass
 
 #***************************************************************************
 # Main class implementing Magic functionality
 class Magic:
     """Magic functions for InteractiveShell.
 
     Shell functions which can be reached as %function_name. All magic
     functions should accept a string, which they can parse for their own
     needs. This can make some functions easier to type, eg `%cd ../`
     vs. `%cd("../")`
 
     ALL definitions MUST begin with the prefix magic_. The user won't need it
     at the command line, but it is is needed in the definition. """
 
     # class globals
     auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
                    'Automagic is ON, % prefix NOT needed for magic functions.']
 
     #......................................................................
     # some utility functions
 
     def __init__(self,shell):
         
         self.options_table = {}
         if profile is None:
             self.magic_prun = self.profile_missing_notice
         self.shell = shell
 
+        # namespace for holding state we may need
+        self._magic_state = Bunch()
+
     def profile_missing_notice(self, *args, **kwargs):
         error("""\
 The profile module could not be found.  If you are a Debian user,
 it has been removed from the standard Debian package because of its non-free
 license. To use profiling, please install"python2.3-profiler" from non-free.""")
 
     def default_option(self,fn,optstr):
         """Make an entry in the options_table for fn, with value optstr"""
         
         if fn not in self.lsmagic():
             error("%s is not a magic function" % fn)
         self.options_table[fn] = optstr
 
     def lsmagic(self):
         """Return a list of currently available magic functions.
 
         Gives a list of the bare names after mangling (['ls','cd', ...], not
         ['magic_ls','magic_cd',...]"""
 
         # FIXME. This needs a cleanup, in the way the magics list is built.
         
         # magics in class definition
         class_magic = lambda fn: fn.startswith('magic_') and \
                       callable(Magic.__dict__[fn])
         # in instance namespace (run-time user additions)
         inst_magic =  lambda fn: fn.startswith('magic_') and \
                      callable(self.__dict__[fn])
         # and bound magics by user (so they can access self):
         inst_bound_magic =  lambda fn: fn.startswith('magic_') and \
                            callable(self.__class__.__dict__[fn])
         magics = filter(class_magic,Magic.__dict__.keys()) + \
                  filter(inst_magic,self.__dict__.keys()) + \
                  filter(inst_bound_magic,self.__class__.__dict__.keys())
         out = []
         for fn in magics:
             out.append(fn.replace('magic_','',1))
         out.sort()
         return out
     
     def extract_input_slices(self,slices):
         """Return as a string a set of input history slices.
 
         The set of slices is given as a list of strings (like ['1','4:8','9'],
         since this function is for use by magic functions which get their
         arguments as strings.
 
         Note that slices can be called with two notations:
 
         N:M -> standard python form, means including items N...(M-1).
 
         N-M -> include items N..M (closed endpoint)."""
 
         cmds = []
         for chunk in slices:
             if ':' in chunk:
                 ini,fin = map(int,chunk.split(':'))
             elif '-' in chunk:
                 ini,fin = map(int,chunk.split('-'))
                 fin += 1
             else:
                 ini = int(chunk)
                 fin = ini+1
             cmds.append(self.shell.input_hist[ini:fin])
         return cmds
         
     def _ofind(self,oname):
         """Find an object in the available namespaces.
 
         self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
 
         Has special code to detect magic functions.
         """
         
         oname = oname.strip()
 
         # Namespaces to search in:
         user_ns        = self.shell.user_ns
         internal_ns    = self.shell.internal_ns
         builtin_ns     = __builtin__.__dict__
         alias_ns       = self.shell.alias_table
 
         # Put them in a list. The order is important so that we find things in
         # the same order that Python finds them.
         namespaces = [ ('Interactive',user_ns),
                        ('IPython internal',internal_ns),
                        ('Python builtin',builtin_ns),
                        ('Alias',alias_ns),
                        ]
 
         # initialize results to 'null'
         found = 0; obj = None;  ospace = None;  ds = None;
         ismagic = 0; isalias = 0
 
         # Look for the given name by splitting it in parts.  If the head is
         # found, then we look for all the remaining parts as members, and only
         # declare success if we can find them all.
         oname_parts = oname.split('.')
         oname_head, oname_rest = oname_parts[0],oname_parts[1:]
         for nsname,ns in namespaces:
             try:
                 obj = ns[oname_head]
             except KeyError:
                 continue
             else:
                 for part in oname_rest:
                     try:
                         obj = getattr(obj,part)
                     except:
                         # Blanket except b/c some badly implemented objects
                         # allow __getattr__ to raise exceptions other than
                         # AttributeError, which then crashes IPython.
                         break
                 else:
                     # If we finish the for loop (no break), we got all members
                     found = 1
                     ospace = nsname
                     if ns == alias_ns:
                         isalias = 1
                     break  # namespace loop
 
         # Try to see if it's magic
         if not found:
             if oname.startswith(self.shell.ESC_MAGIC):
                 oname = oname[1:]
             obj = getattr(self,'magic_'+oname,None)
             if obj is not None:
                 found = 1
                 ospace = 'IPython internal'
                 ismagic = 1
 
         # Last try: special-case some literals like '', [], {}, etc:
         if not found and oname_head in ["''",'""','[]','{}','()']:
             obj = eval(oname_head)
             found = 1
             ospace = 'Interactive'
             
         return {'found':found, 'obj':obj, 'namespace':ospace,
                 'ismagic':ismagic, 'isalias':isalias}
     
     def arg_err(self,func):
         """Print docstring if incorrect arguments were passed"""
         print 'Error in arguments:'
         print OInspect.getdoc(func)
 
     def format_latex(self,strng):
         """Format a string for latex inclusion."""
 
         # Characters that need to be escaped for latex:
         escape_re = re.compile(r'(%|_|\$|#)',re.MULTILINE)
         # Magic command names as headers:
         cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
                                  re.MULTILINE)
         # Magic commands 
         cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
                             re.MULTILINE)
         # Paragraph continue
         par_re = re.compile(r'\\$',re.MULTILINE)
 
         # The "\n" symbol
         newline_re = re.compile(r'\\n')
 
         # Now build the string for output:
         strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
         strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
         strng = par_re.sub(r'\\\\',strng)
         strng = escape_re.sub(r'\\\1',strng)
         strng = newline_re.sub(r'\\textbackslash{}n',strng)
         return strng
 
     def format_screen(self,strng):
         """Format a string for screen printing.
 
         This removes some latex-type format codes."""
         # Paragraph continue
         par_re = re.compile(r'\\$',re.MULTILINE)
         strng = par_re.sub('',strng)
         return strng
 
     def parse_options(self,arg_str,opt_str,*long_opts,**kw):
         """Parse options passed to an argument string.
 
         The interface is similar to that of getopt(), but it returns back a
         Struct with the options as keys and the stripped argument string still
         as a string.
 
         arg_str is quoted as a true sys.argv vector by using shlex.split.
         This allows us to easily expand variables, glob files, quote
         arguments, etc.
 
         Options:
           -mode: default 'string'. If given as 'list', the argument string is
           returned as a list (split on whitespace) instead of a string.
 
           -list_all: put all option values in lists. Normally only options
           appearing more than once are put in a list."""
 
         # inject default options at the beginning of the input line
         caller = sys._getframe(1).f_code.co_name.replace('magic_','')
         arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
         
         mode = kw.get('mode','string')
         if mode not in ['string','list']:
             raise ValueError,'incorrect mode given: %s' % mode
         # Get options
         list_all = kw.get('list_all',0)
 
         # Check if we have more than one argument to warrant extra processing:
         odict = {}  # Dictionary with options
         args = arg_str.split()
         if len(args) >= 1:
             # If the list of inputs only has 0 or 1 thing in it, there's no
             # need to look for options
             argv = shlex_split(arg_str)
             # Do regular option processing
             opts,args = getopt(argv,opt_str,*long_opts)
             for o,a in opts:
                 if o.startswith('--'):
                     o = o[2:]
                 else:
                     o = o[1:]
                 try:
                     odict[o].append(a)
                 except AttributeError:
                     odict[o] = [odict[o],a]
                 except KeyError:
                     if list_all:
                         odict[o] = [a]
                     else:
                         odict[o] = a
 
         # Prepare opts,args for return
         opts = Struct(odict)
         if mode == 'string':
             args = ' '.join(args)
 
         return opts,args
     
     #......................................................................
     # And now the actual magic functions
 
     # Functions for IPython shell work (vars,funcs, config, etc)
     def magic_lsmagic(self, parameter_s = ''):
         """List currently available magic functions."""
         mesc = self.shell.ESC_MAGIC
         print 'Available magic functions:\n'+mesc+\
               ('  '+mesc).join(self.lsmagic())
         print '\n' + Magic.auto_status[self.shell.rc.automagic]
         return None
         
     def magic_magic(self, parameter_s = ''):
         """Print information about the magic function system."""
 
         mode = ''
         try:
             if parameter_s.split()[0] == '-latex':
                 mode = 'latex'
         except:
             pass
 
         magic_docs = []
         for fname in self.lsmagic():
             mname = 'magic_' + fname
             for space in (Magic,self,self.__class__):
                 try:
                     fn = space.__dict__[mname]
                 except KeyError:
                     pass
                 else:
                     break
             magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
                                                 fname,fn.__doc__))
         magic_docs = ''.join(magic_docs)
 
         if mode == 'latex':
             print self.format_latex(magic_docs)
             return
         else:
             magic_docs = self.format_screen(magic_docs)
         
         outmsg = """
 IPython's 'magic' functions
 ===========================
 
 The magic function system provides a series of functions which allow you to
 control the behavior of IPython itself, plus a lot of system-type
 features. All these functions are prefixed with a % character, but parameters
 are given without parentheses or quotes.
 
 NOTE: If you have 'automagic' enabled (via the command line option or with the
 %automagic function), you don't need to type in the % explicitly.  By default,
 IPython ships with automagic on, so you should only rarely need the % escape.
 
 Example: typing '%cd mydir' (without the quotes) changes you working directory
 to 'mydir', if it exists.
 
 You can define your own magic functions to extend the system. See the supplied
 ipythonrc and example-magic.py files for details (in your ipython
 configuration directory, typically $HOME/.ipython/).
 
 You can also define your own aliased names for magic functions. In your
 ipythonrc file, placing a line like:
 
   execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
 
 will define %pf as a new name for %profile.
 
 You can also call magics in code using the ipmagic() function, which IPython
 automatically adds to the builtin namespace.  Type 'ipmagic?' for details.
 
 For a list of the available magic functions, use %lsmagic. For a description
 of any of them, type %magic_name?, e.g. '%cd?'.
 
 Currently the magic system has the following functions:\n"""
 
         mesc = self.shell.ESC_MAGIC
         outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
                   "\n\n%s%s\n\n%s" % (outmsg,
                                      magic_docs,mesc,mesc,
                                      ('  '+mesc).join(self.lsmagic()),
                                      Magic.auto_status[self.shell.rc.automagic] ) )
 
         page(outmsg,screen_lines=self.shell.rc.screen_length)
   
     def magic_automagic(self, parameter_s = ''):
         """Make magic functions callable without having to type the initial %.
         
         Toggles on/off (when off, you must call it as %automagic, of
         course). Note that magic functions have lowest priority, so if there's
         a variable whose name collides with that of a magic fn, automagic
         won't work for that function (you get the variable instead). However,
         if you delete the variable (del var), the previously shadowed magic
         function becomes visible to automagic again."""
 
         rc = self.shell.rc
         rc.automagic = not rc.automagic
         print '\n' + Magic.auto_status[rc.automagic]
 
     def magic_autocall(self, parameter_s = ''):
         """Make functions callable without having to type parentheses.
 
-        This cycles the autocall command line through its three valid values
-        (0->Off, 1->Smart, 2->Full)"""
+        Usage:
+
+           %autocall [mode]
+
+        The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
+        value is toggled on and off (remembering the previous state)."""
         
         rc = self.shell.rc
-        rc.autocall = not rc.autocall
+
+        if parameter_s:
+            arg = int(parameter_s)
+        else:
+            arg = 'toggle'
+
+        if not arg in (0,1,2,'toggle'):
+            error('Valid modes: (0->Off, 1->Smart, 2->Full')
+            return
+
+        if arg in (0,1,2):
+            rc.autocall = arg
+        else: # toggle
+            if rc.autocall:
+                self._magic_state.autocall_save = rc.autocall
+                rc.autocall = 0
+            else:
+                try:
+                    rc.autocall = self._magic_state.autocall_save
+                except AttributeError:
+                    rc.autocall = self._magic_state.autocall_save = 1
+                
         print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
 
     def magic_autoindent(self, parameter_s = ''):
         """Toggle autoindent on/off (if available)."""
 
         self.shell.set_autoindent()
         print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
 
     def magic_system_verbose(self, parameter_s = ''):
         """Toggle verbose printing of system calls on/off."""
 
         self.shell.rc_set_toggle('system_verbose')
         print "System verbose printing is:",\
               ['OFF','ON'][self.shell.rc.system_verbose]
 
     def magic_history(self, parameter_s = ''):
         """Print input history (_i<n> variables), with most recent last.
         
         %history [-n]       -> print at most 40 inputs (some may be multi-line)\\
         %history [-n] n     -> print at most n inputs\\
         %history [-n] n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
 
         Each input's number <n> is shown, and is accessible as the
         automatically generated variable _i<n>.  Multi-line statements are
         printed starting at a new line for easy copy/paste.
 
         If option -n is used, input numbers are not printed. This is useful if
         you want to get a printout of many lines which can be directly pasted
         into a text editor.
 
         This feature is only available if numbered prompts are in use."""
 
         shell = self.shell
         if not shell.outputcache.do_full_cache:
             print 'This feature is only available if numbered prompts are in use.'
             return
         opts,args = self.parse_options(parameter_s,'n',mode='list')
         
         input_hist = shell.input_hist
         default_length = 40
         if len(args) == 0:
             final = len(input_hist)
             init = max(1,final-default_length)
         elif len(args) == 1:
             final = len(input_hist)
             init = max(1,final-int(args[0]))
         elif len(args) == 2:
             init,final = map(int,args)
         else:
             warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
             print self.magic_hist.__doc__
             return
         width = len(str(final))
         line_sep = ['','\n']
         print_nums = not opts.has_key('n')
         for in_num in range(init,final):
             inline = input_hist[in_num]
             multiline = int(inline.count('\n') > 1)
             if print_nums:
                 print '%s:%s' % (str(in_num).ljust(width),line_sep[multiline]),
             print inline,
 
     def magic_hist(self, parameter_s=''):
         """Alternate name for %history."""
         return self.magic_history(parameter_s)
 
     def magic_p(self, parameter_s=''):
         """Just a short alias for Python's 'print'."""
         exec 'print ' + parameter_s in self.shell.user_ns
 
     def magic_r(self, parameter_s=''):
         """Repeat previous input.
 
         If given an argument, repeats the previous command which starts with
         the same string, otherwise it just repeats the previous input.
 
         Shell escaped commands (with ! as first character) are not recognized
         by this system, only pure python code and magic commands.
         """
 
         start = parameter_s.strip()
         esc_magic = self.shell.ESC_MAGIC
         # Identify magic commands even if automagic is on (which means
         # the in-memory version is different from that typed by the user).
         if self.shell.rc.automagic:
             start_magic = esc_magic+start
         else:
             start_magic = start
         # Look through the input history in reverse
         for n in range(len(self.shell.input_hist)-2,0,-1):
             input = self.shell.input_hist[n]
             # skip plain 'r' lines so we don't recurse to infinity
             if input != 'ipmagic("r")\n' and \
                    (input.startswith(start) or input.startswith(start_magic)):
                 #print 'match',`input`  # dbg
                 print 'Executing:',input,
                 self.shell.runlines(input)
                 return
         print 'No previous input matching `%s` found.' % start
 
     def magic_page(self, parameter_s=''):
         """Pretty print the object and display it through a pager.
         
         If no parameter is given, use _ (last output)."""
         # After a function contributed by Olivier Aubert, slightly modified.
 
         oname = parameter_s and parameter_s or '_' 
         info = self._ofind(oname)
         if info['found']:
             page(pformat(info['obj']))
         else:
             print 'Object `%s` not found' % oname
 
     def magic_profile(self, parameter_s=''):
         """Print your currently active IPyhton profile."""
         if self.shell.rc.profile:
             printpl('Current IPython profile: $self.shell.rc.profile.')
         else:
             print 'No profile active.'
         
     def _inspect(self,meth,oname,**kw):
         """Generic interface to the inspector system.
 
         This function is meant to be called by pdef, pdoc & friends."""
         
         oname = oname.strip()
         info = Struct(self._ofind(oname))
         if info.found:
             pmethod = getattr(self.shell.inspector,meth)
             formatter = info.ismagic and self.format_screen or None
             if meth == 'pdoc':
                 pmethod(info.obj,oname,formatter)
             elif meth == 'pinfo':
                 pmethod(info.obj,oname,formatter,info,**kw)
             else:
                 pmethod(info.obj,oname)
         else:
             print 'Object `%s` not found.' % oname
             return 'not found'  # so callers can take other action
         
     def magic_pdef(self, parameter_s=''):
         """Print the definition header for any callable object.
 
         If the object is a class, print the constructor information."""
         self._inspect('pdef',parameter_s)
         
     def magic_pdoc(self, parameter_s=''):
         """Print the docstring for an object.
 
         If the given object is a class, it will print both the class and the
         constructor docstrings."""
         self._inspect('pdoc',parameter_s)
 
     def magic_psource(self, parameter_s=''):
         """Print (or run through pager) the source code for an object."""
         self._inspect('psource',parameter_s)
 
     def magic_pfile(self, parameter_s=''):
         """Print (or run through pager) the file where an object is defined.
 
         The file opens at the line where the object definition begins. IPython
         will honor the environment variable PAGER if set, and otherwise will
         do its best to print the file in a convenient form.
 
         If the given argument is not an object currently defined, IPython will
         try to interpret it as a filename (automatically adding a .py extension
         if needed). You can thus use %pfile as a syntax highlighting code
         viewer."""
 
         # first interpret argument as an object name
         out = self._inspect('pfile',parameter_s)
         # if not, try the input as a filename
         if out == 'not found':
             try:
                 filename = get_py_filename(parameter_s)
             except IOError,msg:
                 print msg
                 return
             page(self.shell.inspector.format(file(filename).read()))
             
     def magic_pinfo(self, parameter_s=''):
         """Provide detailed information about an object.
 
         '%pinfo object' is just a synonym for object? or ?object."""
 
         #print 'pinfo par: <%s>' % parameter_s  # dbg
 
         # detail_level: 0 -> obj? , 1 -> obj??
         detail_level = 0
         # We need to detect if we got called as 'pinfo pinfo foo', which can
         # happen if the user types 'pinfo foo?' at the cmd line.
         pinfo,qmark1,oname,qmark2 = \
                re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
         if pinfo or qmark1 or qmark2:
             detail_level = 1
         if "*" in oname:
             self.magic_psearch(oname)
         else:
             self._inspect('pinfo',oname,detail_level=detail_level)
 
     def magic_psearch(self, parameter_s=''):
         """Search for object in namespaces by wildcard.
 
         %psearch [options] PATTERN [OBJECT TYPE]
 
         Note: ? can be used as a synonym for %psearch, at the beginning or at
         the end: both a*? and ?a* are equivalent to '%psearch a*'.  Still, the
         rest of the command line must be unchanged (options come first), so
         for example the following forms are equivalent
 
         %psearch -i a* function
         -i a* function?
         ?-i a* function
 
         Arguments:
         
           PATTERN
 
           where PATTERN is a string containing * as a wildcard similar to its
           use in a shell.  The pattern is matched in all namespaces on the
           search path. By default objects starting with a single _ are not
           matched, many IPython generated objects have a single
           underscore. The default is case insensitive matching. Matching is
           also done on the attributes of objects and not only on the objects
           in a module.
 
           [OBJECT TYPE]
 
           Is the name of a python type from the types module. The name is
           given in lowercase without the ending type, ex. StringType is
           written string. By adding a type here only objects matching the
           given type are matched. Using all here makes the pattern match all
           types (this is the default).
 
         Options:
 
           -a: makes the pattern match even objects whose names start with a
           single underscore.  These names are normally ommitted from the
           search.
 
           -i/-c: make the pattern case insensitive/sensitive.  If neither of
           these options is given, the default is read from your ipythonrc
           file.  The option name which sets this value is
           'wildcards_case_sensitive'.  If this option is not specified in your
           ipythonrc file, IPython's internal default is to do a case sensitive
           search.
 
           -e/-s NAMESPACE: exclude/search a given namespace.  The pattern you
           specifiy can be searched in any of the following namespaces:
           'builtin', 'user', 'user_global','internal', 'alias', where
           'builtin' and 'user' are the search defaults.  Note that you should
           not use quotes when specifying namespaces.
 
           'Builtin' contains the python module builtin, 'user' contains all
           user data, 'alias' only contain the shell aliases and no python
           objects, 'internal' contains objects used by IPython.  The
           'user_global' namespace is only used by embedded IPython instances,
           and it contains module-level globals.  You can add namespaces to the
           search with -s or exclude them with -e (these options can be given
           more than once).
     
         Examples:
        
         %psearch a*            -> objects beginning with an a
         %psearch -e builtin a* -> objects NOT in the builtin space starting in a
         %psearch a* function   -> all functions beginning with an a
         %psearch re.e*         -> objects beginning with an e in module re
         %psearch r*.e*         -> objects that start with e in modules starting in r
         %psearch r*.* string   -> all strings in modules beginning with r
 
         Case sensitve search:
        
         %psearch -c a*         list all object beginning with lower case a
 
         Show objects beginning with a single _:
        
         %psearch -a _*         list objects beginning with a single underscore"""
 
         # default namespaces to be searched
         def_search = ['user','builtin']
 
         # Process options/args
         opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
         opt = opts.get
         shell = self.shell
         psearch = shell.inspector.psearch
         
         # select case options
         if opts.has_key('i'):
             ignore_case = True
         elif opts.has_key('c'):
             ignore_case = False
         else:
             ignore_case = not shell.rc.wildcards_case_sensitive
 
         # Build list of namespaces to search from user options
         def_search.extend(opt('s',[]))
         ns_exclude = ns_exclude=opt('e',[])
         ns_search = [nm for nm in def_search if nm not in ns_exclude]
         
         # Call the actual search
         try:
             psearch(args,shell.ns_table,ns_search,
                     show_all=opt('a'),ignore_case=ignore_case)
         except:
             shell.showtraceback()
 
     def magic_who_ls(self, parameter_s=''):
         """Return a sorted list of all interactive variables.
 
         If arguments are given, only variables of types matching these
         arguments are returned."""
 
         user_ns = self.shell.user_ns
         internal_ns = self.shell.internal_ns
         user_config_ns = self.shell.user_config_ns
         out = []
         typelist = parameter_s.split()
 
         for i in user_ns:
             if not (i.startswith('_') or i.startswith('_i')) \
                    and not (i in internal_ns or i in user_config_ns):
                 if typelist:
                     if type(user_ns[i]).__name__ in typelist:
                         out.append(i)
                 else:
                     out.append(i)
         out.sort()
         return out
         
     def magic_who(self, parameter_s=''):
         """Print all interactive variables, with some minimal formatting.
 
         If any arguments are given, only variables whose type matches one of
         these are printed.  For example:
 
           %who function str
 
         will only list functions and strings, excluding all other types of
         variables.  To find the proper type names, simply use type(var) at a
         command line to see how python prints type names.  For example:
 
           In [1]: type('hello')\\
           Out[1]: <type 'str'>
 
         indicates that the type name for strings is 'str'.
 
         %who always excludes executed names loaded through your configuration
         file and things which are internal to IPython.
 
         This is deliberate, as typically you may load many modules and the
         purpose of %who is to show you only what you've manually defined."""
 
         varlist = self.magic_who_ls(parameter_s)
         if not varlist:
             print 'Interactive namespace is empty.'
             return
 
         # if we have variables, move on...
 
         # stupid flushing problem: when prompts have no separators, stdout is
         # getting lost. I'm starting to think this is a python bug. I'm having
         # to force a flush with a print because even a sys.stdout.flush
         # doesn't seem to do anything!
 
         count = 0
         for i in varlist:
             print i+'\t',
             count += 1
             if count > 8:
                 count = 0
                 print
             sys.stdout.flush()  # FIXME. Why the hell isn't this flushing???
             
         print # well, this does force a flush at the expense of an extra \n
 
     def magic_whos(self, parameter_s=''):
         """Like %who, but gives some extra information about each variable.
 
         The same type filtering of %who can be applied here.
 
         For all variables, the type is printed. Additionally it prints:
         
           - For {},[],(): their length.
 
           - For Numeric arrays, a summary with shape, number of elements,
           typecode and size in memory.
 
           - Everything else: a string representation, snipping their middle if
           too long."""
         
         varnames = self.magic_who_ls(parameter_s)
         if not varnames:
             print 'Interactive namespace is empty.'
             return
 
         # if we have variables, move on...
 
         # for these types, show len() instead of data:
         seq_types = [types.DictType,types.ListType,types.TupleType]
 
         # for Numeric arrays, display summary info
         try:
             import Numeric
         except ImportError:
             array_type = None
         else:
             array_type = Numeric.ArrayType.__name__
         
         # Find all variable names and types so we can figure out column sizes
         get_vars = lambda i: self.shell.user_ns[i]
         type_name = lambda v: type(v).__name__
         varlist = map(get_vars,varnames)
 
         typelist = []
         for vv in varlist:
             tt = type_name(vv)
             if tt=='instance':
                 typelist.append(str(vv.__class__))
             else:
                 typelist.append(tt)
 
         # column labels and # of spaces as separator
         varlabel = 'Variable'
         typelabel = 'Type'
         datalabel = 'Data/Info'
         colsep = 3
         # variable format strings
         vformat    = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
         vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
         aformat    = "%s: %s elems, type `%s`, %s bytes"
         # find the size of the columns to format the output nicely
         varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
         typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
         # table header
         print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
               ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
         # and the table itself
         kb = 1024
         Mb = 1048576  # kb**2
         for vname,var,vtype in zip(varnames,varlist,typelist):
             print itpl(vformat),
             if vtype in seq_types:
                 print len(var)
             elif vtype==array_type:
                 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
                 vsize  = Numeric.size(var)
                 vbytes = vsize*var.itemsize()
                 if vbytes < 100000:
                     print aformat % (vshape,vsize,var.typecode(),vbytes)
                 else:
                     print aformat % (vshape,vsize,var.typecode(),vbytes),
                     if vbytes < Mb:
                         print '(%s kb)' % (vbytes/kb,)
                     else:
                         print '(%s Mb)' % (vbytes/Mb,)
             else:
                 vstr = str(var).replace('\n','\\n')
                 if len(vstr) < 50:
                     print vstr
                 else:
                     printpl(vfmt_short)
                 
     def magic_reset(self, parameter_s=''):
         """Resets the namespace by removing all names defined by the user.
 
         Input/Output history are left around in case you need them."""
 
         ans = raw_input(
           "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
         if not ans.lower() == 'y':
             print 'Nothing done.'
             return
         user_ns = self.shell.user_ns
         for i in self.magic_who_ls():
             del(user_ns[i])
 
     def magic_config(self,parameter_s=''):
         """Show IPython's internal configuration."""
         
         page('Current configuration structure:\n'+
              pformat(self.shell.rc.dict()))
 
     def magic_logstart(self,parameter_s=''):
         """Start logging anywhere in a session.
 
         %logstart [-o|-t] [log_name [log_mode]]
 
         If no name is given, it defaults to a file named 'ipython_log.py' in your
         current directory, in 'rotate' mode (see below).
 
         '%logstart name' saves to file 'name' in 'backup' mode.  It saves your
         history up to that point and then continues logging.
 
         %logstart takes a second optional parameter: logging mode. This can be one
         of (note that the modes are given unquoted):\\
           append: well, that says it.\\
           backup: rename (if exists) to name~ and start name.\\
           global: single logfile in your home dir, appended to.\\
           over  : overwrite existing log.\\
           rotate: create rotating logs name.1~, name.2~, etc.
 
         Options:
 
           -o: log also IPython's output.  In this mode, all commands which
           generate an Out[NN] prompt are recorded to the logfile, right after
           their corresponding input line.  The output lines are always
           prepended with a '#[Out]# ' marker, so that the log remains valid
           Python code.
 
           Since this marker is always the same, filtering only the output from
           a log is very easy, using for example a simple awk call:
 
             awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
 
           -t: put timestamps before each input line logged (these are put in
           comments)."""
         
         opts,par = self.parse_options(parameter_s,'ot')
         log_output = 'o' in opts
         timestamp = 't' in opts
 
         rc = self.shell.rc
         logger = self.shell.logger
 
         # if no args are given, the defaults set in the logger constructor by
         # ipytohn remain valid
         if par:
             try:
                 logfname,logmode = par.split()
             except:
                 logfname = par
                 logmode = 'backup'
         else:
             logfname = logger.logfname
             logmode = logger.logmode
         # put logfname into rc struct as if it had been called on the command
         # line, so it ends up saved in the log header Save it in case we need
         # to restore it...
         old_logfile = rc.opts.get('logfile','')  
         if logfname:
             logfname = os.path.expanduser(logfname)
         rc.opts.logfile = logfname
         loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
         try:
             started  = logger.logstart(logfname,loghead,logmode,
                                        log_output,timestamp)
         except:
             rc.opts.logfile = old_logfile
             warn("Couldn't start log: %s" % sys.exc_info()[1])
         else:
             # log input history up to this point, optionally interleaving
             # output if requested
 
             if timestamp:
                 # disable timestamping for the previous history, since we've
                 # lost those already (no time machine here).
                 logger.timestamp = False
             if log_output:
                 log_write = logger.log_write
                 input_hist = self.shell.input_hist
                 output_hist = self.shell.output_hist
                 for n in range(1,len(input_hist)-1):
                     log_write(input_hist[n].rstrip())
                     if n in output_hist:
                         log_write(repr(output_hist[n]),'output')
             else:
                 logger.log_write(self.shell.input_hist[1:])
             if timestamp:
                 # re-enable timestamping
                 logger.timestamp = True
                 
             print ('Activating auto-logging. '
                    'Current session state plus future input saved.')
             logger.logstate()
 
     def magic_logoff(self,parameter_s=''):
         """Temporarily stop logging.
 
         You must have previously started logging."""
         self.shell.logger.switch_log(0)
         
     def magic_logon(self,parameter_s=''):
         """Restart logging.
 
         This function is for restarting logging which you've temporarily
         stopped with %logoff. For starting logging for the first time, you
         must use the %logstart function, which allows you to specify an
         optional log filename."""
         
         self.shell.logger.switch_log(1)
     
     def magic_logstate(self,parameter_s=''):
         """Print the status of the logging system."""
 
         self.shell.logger.logstate()
         
     def magic_pdb(self, parameter_s=''):
         """Control the calling of the pdb interactive debugger.
 
         Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
         argument it works as a toggle.
 
         When an exception is triggered, IPython can optionally call the
         interactive pdb debugger after the traceback printout. %pdb toggles
         this feature on and off."""
 
         par = parameter_s.strip().lower()
 
         if par:
             try:
                 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
             except KeyError:
                 print ('Incorrect argument. Use on/1, off/0, '
                        'or nothing for a toggle.')
                 return
         else:
             # toggle
             new_pdb = not self.shell.InteractiveTB.call_pdb
 
         # set on the shell
         self.shell.call_pdb = new_pdb
         print 'Automatic pdb calling has been turned',on_off(new_pdb)
 
     def magic_prun(self, parameter_s ='',user_mode=1,
                    opts=None,arg_lst=None,prog_ns=None):
 
         """Run a statement through the python code profiler.
 
         Usage:\\
           %prun [options] statement
 
         The given statement (which doesn't require quote marks) is run via the
         python profiler in a manner similar to the profile.run() function.
         Namespaces are internally managed to work correctly; profile.run
         cannot be used in IPython because it makes certain assumptions about
         namespaces which do not hold under IPython.
 
         Options:
 
         -l <limit>: you can place restrictions on what or how much of the
         profile gets printed. The limit value can be:
 
           * A string: only information for function names containing this string
           is printed.
 
           * An integer: only these many lines are printed.
 
           * A float (between 0 and 1): this fraction of the report is printed
           (for example, use a limit of 0.4 to see the topmost 40% only).
 
         You can combine several limits with repeated use of the option. For
         example, '-l __init__ -l 5' will print only the topmost 5 lines of
         information about class constructors.
 
         -r: return the pstats.Stats object generated by the profiling. This
         object has all the information about the profile in it, and you can
         later use it for further analysis or in other functions.
 
         Since magic functions have a particular form of calling which prevents
         you from writing something like:\\
           In [1]: p = %prun -r print 4  # invalid!\\
         you must instead use IPython's automatic variables to assign this:\\
           In [1]: %prun -r print 4  \\
           Out[1]: <pstats.Stats instance at 0x8222cec>\\
           In [2]: stats = _
 
         If you really need to assign this value via an explicit function call,
         you can always tap directly into the true name of the magic function
         by using the ipmagic function (which IPython automatically adds to the
         builtins):\\
           In [3]: stats = ipmagic('prun','-r print 4')
 
         You can type ipmagic? for more details on ipmagic.
 
        -s <key>: sort profile by given key. You can provide more than one key
         by using the option several times: '-s key1 -s key2 -s key3...'. The
         default sorting key is 'time'.
 
         The following is copied verbatim from the profile documentation
         referenced below:
 
         When more than one key is provided, additional keys are used as
         secondary criteria when the there is equality in all keys selected
         before them.
         
         Abbreviations can be used for any key names, as long as the
         abbreviation is unambiguous.  The following are the keys currently
         defined:
 
                 Valid Arg       Meaning\\
                   "calls"      call count\\
                   "cumulative" cumulative time\\
                   "file"       file name\\
                   "module"     file name\\
                   "pcalls"     primitive call count\\
                   "line"       line number\\
                   "name"       function name\\
                   "nfl"        name/file/line\\
                   "stdname"    standard name\\
                   "time"       internal time
 
         Note that all sorts on statistics are in descending order (placing
         most time consuming items first), where as name, file, and line number
         searches are in ascending order (i.e., alphabetical). The subtle
         distinction between "nfl" and "stdname" is that the standard name is a
         sort of the name as printed, which means that the embedded line
         numbers get compared in an odd way.  For example, lines 3, 20, and 40
         would (if the file names were the same) appear in the string order
         "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
         line numbers.  In fact, sort_stats("nfl") is the same as
         sort_stats("name", "file", "line").
 
         -T <filename>: save profile results as shown on screen to a text
         file. The profile is still shown on screen.
 
         -D <filename>: save (via dump_stats) profile statistics to given
         filename. This data is in a format understod by the pstats module, and
         is generated by a call to the dump_stats() method of profile
         objects. The profile is still shown on screen.
 
         If you want to run complete programs under the profiler's control, use
         '%run -p [prof_opts] filename.py [args to program]' where prof_opts
         contains profiler specific options as described here.
         
         You can read the complete documentation for the profile module with:\\
           In [1]: import profile; profile.help() """
 
         opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
         # protect user quote marks
         parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
         
         if user_mode:  # regular user call
             opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
                                               list_all=1)
             namespace = self.shell.user_ns
         else:  # called to run a program by %run -p
             try:
                 filename = get_py_filename(arg_lst[0])
             except IOError,msg:
                 error(msg)
                 return
 
             arg_str = 'execfile(filename,prog_ns)'
             namespace = locals()
 
         opts.merge(opts_def)
         
         prof = profile.Profile()
         try:
             prof = prof.runctx(arg_str,namespace,namespace)
             sys_exit = ''
         except SystemExit:
             sys_exit = """*** SystemExit exception caught in code being profiled."""
 
         stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
 
         lims = opts.l
         if lims:
             lims = []  # rebuild lims with ints/floats/strings
             for lim in opts.l:
                 try:
                     lims.append(int(lim))
                 except ValueError:
                     try:
                         lims.append(float(lim))
                     except ValueError:
                         lims.append(lim)
                     
         # trap output
         sys_stdout = sys.stdout
         stdout_trap = StringIO()
         try:
             sys.stdout = stdout_trap
             stats.print_stats(*lims)
         finally:
             sys.stdout = sys_stdout
         output = stdout_trap.getvalue()
         output = output.rstrip()
 
         page(output,screen_lines=self.shell.rc.screen_length)
         print sys_exit,
 
         dump_file = opts.D[0]
         text_file = opts.T[0]
         if dump_file:
             prof.dump_stats(dump_file)
             print '\n*** Profile stats marshalled to file',\
                   `dump_file`+'.',sys_exit
         if text_file:
             file(text_file,'w').write(output)
             print '\n*** Profile printout saved to text file',\
                   `text_file`+'.',sys_exit
 
         if opts.has_key('r'):
             return stats
         else:
             return None
 
     def magic_run(self, parameter_s ='',runner=None):
         """Run the named file inside IPython as a program.
 
         Usage:\\
           %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
 
         Parameters after the filename are passed as command-line arguments to
         the program (put in sys.argv). Then, control returns to IPython's
         prompt.
 
         This is similar to running at a system prompt:\\
           $ python file args\\
         but with the advantage of giving you IPython's tracebacks, and of
         loading all variables into your interactive namespace for further use
         (unless -p is used, see below).
 
         The file is executed in a namespace initially consisting only of
         __name__=='__main__' and sys.argv constructed as indicated. It thus
         sees its environment as if it were being run as a stand-alone
         program. But after execution, the IPython interactive namespace gets
         updated with all variables defined in the program (except for __name__
         and sys.argv). This allows for very convenient loading of code for
         interactive work, while giving each program a 'clean sheet' to run in.
 
         Options:
         
         -n: __name__ is NOT set to '__main__', but to the running file's name
         without extension (as python does under import).  This allows running
         scripts and reloading the definitions in them without calling code
         protected by an ' if __name__ == "__main__" ' clause.
 
         -i: run the file in IPython's namespace instead of an empty one. This
         is useful if you are experimenting with code written in a text editor
         which depends on variables defined interactively.
 
         -e: ignore sys.exit() calls or SystemExit exceptions in the script
         being run.  This is particularly useful if IPython is being used to
         run unittests, which always exit with a sys.exit() call.  In such
         cases you are interested in the output of the test results, not in
         seeing a traceback of the unittest module.
 
         -t: print timing information at the end of the run.  IPython will give
         you an estimated CPU time consumption for your script, which under
         Unix uses the resource module to avoid the wraparound problems of
         time.clock().  Under Unix, an estimate of time spent on system tasks
         is also given (for Windows platforms this is reported as 0.0).
 
         If -t is given, an additional -N<N> option can be given, where <N>
         must be an integer indicating how many times you want the script to
         run.  The final timing report will include total and per run results.
 
         For example (testing the script uniq_stable.py):
 
             In [1]: run -t uniq_stable
 
             IPython CPU timings (estimated):\\
               User  :    0.19597 s.\\
               System:        0.0 s.\\
 
             In [2]: run -t -N5 uniq_stable
 
             IPython CPU timings (estimated):\\
             Total runs performed: 5\\
               Times :      Total       Per run\\
               User  :   0.910862 s,  0.1821724 s.\\
               System:        0.0 s,        0.0 s.
 
         -d: run your program under the control of pdb, the Python debugger.
         This allows you to execute your program step by step, watch variables,
         etc.  Internally, what IPython does is similar to calling:
         
           pdb.run('execfile("YOURFILENAME")')
 
         with a breakpoint set on line 1 of your file.  You can change the line
         number for this automatic breakpoint to be <N> by using the -bN option
         (where N must be an integer).  For example:
 
           %run -d -b40 myscript
 
         will set the first breakpoint at line 40 in myscript.py.  Note that
         the first breakpoint must be set on a line which actually does
         something (not a comment or docstring) for it to stop execution.
 
         When the pdb debugger starts, you will see a (Pdb) prompt.  You must
         first enter 'c' (without qoutes) to start execution up to the first
         breakpoint.
 
         Entering 'help' gives information about the use of the debugger.  You
         can easily see pdb's full documentation with "import pdb;pdb.help()"
         at a prompt.
 
         -p: run program under the control of the Python profiler module (which
         prints a detailed report of execution times, function calls, etc).
 
         You can pass other options after -p which affect the behavior of the
         profiler itself. See the docs for %prun for details.
 
         In this mode, the program's variables do NOT propagate back to the
         IPython interactive namespace (because they remain in the namespace
         where the profiler executes them).
 
         Internally this triggers a call to %prun, see its documentation for
         details on the options available specifically for profiling."""
 
         # get arguments and set sys.argv for program to be run.
         opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
                                           mode='list',list_all=1)
 
         try:
             filename = get_py_filename(arg_lst[0])
         except IndexError:
             warn('you must provide at least a filename.')
             print '\n%run:\n',OInspect.getdoc(self.magic_run)
             return
         except IOError,msg:
             error(msg)
             return
 
         # Control the response to exit() calls made by the script being run
         exit_ignore = opts.has_key('e')
         
         # Make sure that the running script gets a proper sys.argv as if it
         # were run from a system shell.
         save_argv = sys.argv # save it for later restoring
         sys.argv = [filename]+ arg_lst[1:]  # put in the proper filename
 
         if opts.has_key('i'):
             prog_ns = self.shell.user_ns
             __name__save = self.shell.user_ns['__name__']
             prog_ns['__name__'] = '__main__'
         else:
             if opts.has_key('n'):
                 name = os.path.splitext(os.path.basename(filename))[0]
             else:
                 name = '__main__'
             prog_ns = {'__name__':name}
 
         # pickle fix.  See iplib for an explanation.  But we need to make sure
         # that, if we overwrite __main__, we replace it at the end
         if prog_ns['__name__'] == '__main__':
             restore_main = sys.modules['__main__']
         else:
             restore_main = False
             
         sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
         
         stats = None
         try:
             if opts.has_key('p'):
                 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
             else:
                 if opts.has_key('d'):
                     deb = Debugger.Pdb(self.shell.rc.colors)
                     # reset Breakpoint state, which is moronically kept
                     # in a class
                     bdb.Breakpoint.next = 1
                     bdb.Breakpoint.bplist = {}
                     bdb.Breakpoint.bpbynumber = [None]
                     # Set an initial breakpoint to stop execution
                     maxtries = 10
                     bp = int(opts.get('b',[1])[0])
                     checkline = deb.checkline(filename,bp)
                     if not checkline:
                         for bp in range(bp+1,bp+maxtries+1):
                             if deb.checkline(filename,bp):
                                 break
                         else:
                             msg = ("\nI failed to find a valid line to set "
                                    "a breakpoint\n"
                                    "after trying up to line: %s.\n"
                                    "Please set a valid breakpoint manually "
                                    "with the -b option." % bp)
                             error(msg)
                             return
                     # if we find a good linenumber, set the breakpoint
                     deb.do_break('%s:%s' % (filename,bp))
                     # Start file run
                     print "NOTE: Enter 'c' at the",
                     print "ipdb> prompt to start your script."
                     try:
                         deb.run('execfile("%s")' % filename,prog_ns)
                     except:
                         etype, value, tb = sys.exc_info()
                         # Skip three frames in the traceback: the %run one,
                         # one inside bdb.py, and the command-line typed by the
                         # user (run by exec in pdb itself).
                         self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
                 else:
                     if runner is None:
                         runner = self.shell.safe_execfile
                     if opts.has_key('t'):
                         try:
                             nruns = int(opts['N'][0])
                             if nruns < 1:
                                 error('Number of runs must be >=1')
                                 return
                         except (KeyError):
                             nruns = 1
                         if nruns == 1:
                             t0 = clock2()
                             runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
                             t1 = clock2()
                             t_usr = t1[0]-t0[0]
                             t_sys = t1[1]-t1[1]
                             print "\nIPython CPU timings (estimated):"
                             print "  User  : %10s s." % t_usr
                             print "  System: %10s s." % t_sys
                         else:
                             runs = range(nruns)
                             t0 = clock2()
                             for nr in runs:
                                 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
                             t1 = clock2()
                             t_usr = t1[0]-t0[0]
                             t_sys = t1[1]-t1[1]
                             print "\nIPython CPU timings (estimated):"
                             print "Total runs performed:",nruns
                             print "  Times : %10s    %10s" % ('Total','Per run')
                             print "  User  : %10s s, %10s s." % (t_usr,t_usr/nruns)
                             print "  System: %10s s, %10s s." % (t_sys,t_sys/nruns)
                             
                     else:
                         runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
                 if opts.has_key('i'):
                     self.shell.user_ns['__name__'] = __name__save
                 else:
                     # update IPython interactive namespace
                     del prog_ns['__name__']
                     self.shell.user_ns.update(prog_ns)
         finally:
             sys.argv = save_argv
             if restore_main:
                 sys.modules['__main__'] = restore_main
         return stats
 
     def magic_runlog(self, parameter_s =''):
         """Run files as logs.
 
         Usage:\\
           %runlog file1 file2 ...
 
         Run the named files (treating them as log files) in sequence inside
         the interpreter, and return to the prompt.  This is much slower than
         %run because each line is executed in a try/except block, but it
         allows running files with syntax errors in them.
 
         Normally IPython will guess when a file is one of its own logfiles, so
         you can typically use %run even for logs. This shorthand allows you to
         force any file to be treated as a log file."""
 
         for f in parameter_s.split():
             self.shell.safe_execfile(f,self.shell.user_ns,
                                      self.shell.user_ns,islog=1)
 
     def magic_time(self,parameter_s = ''):
         """Time execution of a Python statement or expression.
 
         The CPU and wall clock times are printed, and the value of the
         expression (if any) is returned.  Note that under Win32, system time
         is always reported as 0, since it can not be measured.
 
         This function provides very basic timing functionality.  In Python
         2.3, the timeit module offers more control and sophistication, but for
         now IPython supports Python 2.2, so we can not rely on timeit being
         present.
         
         Some examples:
 
           In [1]: time 2**128
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
           Out[1]: 340282366920938463463374607431768211456L
 
           In [2]: n = 1000000
 
           In [3]: time sum(range(n))
           CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
           Wall time: 1.37
           Out[3]: 499999500000L
 
           In [4]: time print 'hello world'
           hello world
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00
           """
         
         # fail immediately if the given expression can't be compiled
         try:
             mode = 'eval'
             code = compile(parameter_s,'<timed eval>',mode)
         except SyntaxError:
             mode = 'exec'
             code = compile(parameter_s,'<timed exec>',mode)
         # skew measurement as little as possible
         glob = self.shell.user_ns
         clk = clock2
         wtime = time.time
         # time execution
         wall_st = wtime()
         if mode=='eval':
             st = clk()
             out = eval(code,glob)
             end = clk()
         else:
             st = clk()
             exec code in glob
             end = clk()
             out = None
         wall_end = wtime()
         # Compute actual times and report
         wall_time = wall_end-wall_st
         cpu_user = end[0]-st[0]
         cpu_sys = end[1]-st[1]
         cpu_tot = cpu_user+cpu_sys
         print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
               (cpu_user,cpu_sys,cpu_tot)
         print "Wall time: %.2f" % wall_time
         return out
 
     def magic_macro(self,parameter_s = ''):
         """Define a set of input lines as a macro for future re-execution.
 
         Usage:\\
           %macro name n1-n2 n3-n4 ... n5 .. n6 ...
 
         This will define a global variable called `name` which is a string
         made of joining the slices and lines you specify (n1,n2,... numbers
         above) from your input history into a single string. This variable
         acts like an automatic function which re-executes those lines as if
         you had typed them. You just type 'name' at the prompt and the code
         executes.
 
         The notation for indicating number ranges is: n1-n2 means 'use line
         numbers n1,...n2' (the endpoint is included).  That is, '5-7' means
         using the lines numbered 5,6 and 7.
 
         Note: as a 'hidden' feature, you can also use traditional python slice
         notation, where N:M means numbers N through M-1.
 
         For example, if your history contains (%hist prints it):
         
           44: x=1\\
           45: y=3\\
           46: z=x+y\\
           47: print x\\
           48: a=5\\
           49: print 'x',x,'y',y\\
 
         you can create a macro with lines 44 through 47 (included) and line 49
         called my_macro with:
 
           In [51]: %macro my_macro 44-47 49
 
         Now, typing `my_macro` (without quotes) will re-execute all this code
         in one pass.
 
         You don't need to give the line-numbers in order, and any given line
         number can appear multiple times. You can assemble macros with any
         lines from your input history in any order.
 
         The macro is a simple object which holds its value in an attribute,
         but IPython's display system checks for macros and executes them as
         code instead of printing them when you type their name.
 
         You can view a macro's contents by explicitly printing it with:
         
           'print macro_name'.
 
         For one-off cases which DON'T contain magic function calls in them you
         can obtain similar results by explicitly executing slices from your
         input history with:
 
           In [60]: exec In[44:48]+In[49]"""
 
         args = parameter_s.split()
         name,ranges = args[0], args[1:]
         #print 'rng',ranges  # dbg
         lines = self.extract_input_slices(ranges)
         macro = Macro(lines)
         self.shell.user_ns.update({name:macro})
         print 'Macro `%s` created. To execute, type its name (without quotes).' % name
         print 'Macro contents:'
         print macro,
 
     def magic_save(self,parameter_s = ''):
         """Save a set of lines to a given filename.
 
         Usage:\\
           %save filename n1-n2 n3-n4 ... n5 .. n6 ...
 
         This function uses the same syntax as %macro for line extraction, but
         instead of creating a macro it saves the resulting string to the
         filename you specify.
 
         It adds a '.py' extension to the file if you don't do so yourself, and
         it asks for confirmation before overwriting existing files."""
 
         args = parameter_s.split()
         fname,ranges = args[0], args[1:]
         if not fname.endswith('.py'):
             fname += '.py'
         if os.path.isfile(fname):
             ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
             if ans.lower() not in ['y','yes']:
                 print 'Operation cancelled.'
                 return
         cmds = ''.join(self.extract_input_slices(ranges))
         f = file(fname,'w')
         f.write(cmds)
         f.close()
         print 'The following commands were written to file `%s`:' % fname
         print cmds
 
     def _edit_macro(self,mname,macro):
         """open an editor with the macro data in a file"""
         filename = self.shell.mktempfile(macro.value)
         self.shell.hooks.editor(filename)
 
         # and make a new macro object, to replace the old one
         mfile = open(filename)
         mvalue = mfile.read()
         mfile.close()
         self.shell.user_ns[mname] = Macro(mvalue)
 
     def magic_ed(self,parameter_s=''):
         """Alias to %edit."""
         return self.magic_edit(parameter_s)
 
     def magic_edit(self,parameter_s='',last_call=['','']):
         """Bring up an editor and execute the resulting code.
 
         Usage:
           %edit [options] [args]
 
         %edit runs IPython's editor hook.  The default version of this hook is
         set to call the __IPYTHON__.rc.editor command.  This is read from your
         environment variable $EDITOR.  If this isn't found, it will default to
         vi under Linux/Unix and to notepad under Windows.  See the end of this
         docstring for how to change the editor hook.
 
         You can also set the value of this editor via the command line option
         '-editor' or in your ipythonrc file. This is useful if you wish to use
         specifically for IPython an editor different from your typical default
         (and for Windows users who typically don't set environment variables).
 
         This command allows you to conveniently edit multi-line code right in
         your IPython session.
         
         If called without arguments, %edit opens up an empty editor with a
         temporary file and will execute the contents of this file when you
         close it (don't forget to save it!).
 
         Options:
 
         -p: this will call the editor with the same data as the previous time
         it was used, regardless of how long ago (in your current session) it
         was.
 
         -x: do not execute the edited code immediately upon exit. This is
         mainly useful if you are editing programs which need to be called with
         command line arguments, which you can then do using %run.
 
         Arguments:
 
         If arguments are given, the following possibilites exist:
 
         - The arguments are numbers or pairs of colon-separated numbers (like
         1 4:8 9). These are interpreted as lines of previous input to be
         loaded into the editor. The syntax is the same of the %macro command.
 
         - If the argument doesn't start with a number, it is evaluated as a
         variable and its contents loaded into the editor. You can thus edit
         any string which contains python code (including the result of
         previous edits).
 
         - If the argument is the name of an object (other than a string),
         IPython will try to locate the file where it was defined and open the
         editor at the point where it is defined. You can use `%edit function`
         to load an editor exactly at the point where 'function' is defined,
         edit it and have the file be executed automatically.
 
         If the object is a macro (see %macro for details), this opens up your
         specified editor with a temporary file containing the macro's data.
         Upon exit, the macro is reloaded with the contents of the file.
 
         Note: opening at an exact line is only supported under Unix, and some
         editors (like kedit and gedit up to Gnome 2.8) do not understand the
         '+NUMBER' parameter necessary for this feature. Good editors like
         (X)Emacs, vi, jed, pico and joe all do.
 
         - If the argument is not found as a variable, IPython will look for a
         file with that name (adding .py if necessary) and load it into the
         editor. It will execute its contents with execfile() when you exit,
         loading any code in the file into your interactive namespace.
 
         After executing your code, %edit will return as output the code you
         typed in the editor (except when it was an existing file). This way
         you can reload the code in further invocations of %edit as a variable,
         via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
         the output.
 
         Note that %edit is also available through the alias %ed.
 
         This is an example of creating a simple function inside the editor and
         then modifying it. First, start up the editor:
 
         In [1]: ed\\
         Editing... done. Executing edited code...\\
         Out[1]: 'def foo():\\n    print "foo() was defined in an editing session"\\n'
 
         We can then call the function foo():
         
         In [2]: foo()\\
         foo() was defined in an editing session
 
         Now we edit foo.  IPython automatically loads the editor with the
         (temporary) file where foo() was previously defined:
         
         In [3]: ed foo\\
         Editing... done. Executing edited code...
 
         And if we call foo() again we get the modified version:
         
         In [4]: foo()\\
         foo() has now been changed!
 
         Here is an example of how to edit a code snippet successive
         times. First we call the editor:
 
         In [8]: ed\\
         Editing... done. Executing edited code...\\
         hello\\
         Out[8]: "print 'hello'\\n"
 
         Now we call it again with the previous output (stored in _):
 
         In [9]: ed _\\
         Editing... done. Executing edited code...\\
         hello world\\
         Out[9]: "print 'hello world'\\n"
 
         Now we call it with the output #8 (stored in _8, also as Out[8]):
 
         In [10]: ed _8\\
         Editing... done. Executing edited code...\\
         hello again\\
         Out[10]: "print 'hello again'\\n"
 
 
         Changing the default editor hook:
 
         If you wish to write your own editor hook, you can put it in a
         configuration file which you load at startup time.  The default hook
         is defined in the IPython.hooks module, and you can use that as a
         starting example for further modifications.  That file also has
         general instructions on how to set a new hook for use once you've
         defined it."""
         
         # FIXME: This function has become a convoluted mess.  It needs a
         # ground-up rewrite with clean, simple logic.
 
         def make_filename(arg):
             "Make a filename from the given args"
             try:
                 filename = get_py_filename(arg)
             except IOError:
                 if args.endswith('.py'):
                     filename = arg
                 else:
                     filename = None
             return filename
 
         # custom exceptions
         class DataIsObject(Exception): pass
 
         opts,args = self.parse_options(parameter_s,'px')
 
         # Default line number value
         lineno = None
         if opts.has_key('p'):
             args = '_%s' % last_call[0]
             if not self.shell.user_ns.has_key(args):
                 args = last_call[1]
             
         # use last_call to remember the state of the previous call, but don't
         # let it be clobbered by successive '-p' calls.
         try:
             last_call[0] = self.shell.outputcache.prompt_count
             if not opts.has_key('p'):
                 last_call[1] = parameter_s
         except:
             pass
 
         # by default this is done with temp files, except when the given
         # arg is a filename
         use_temp = 1
 
         if re.match(r'\d',args):
             # Mode where user specifies ranges of lines, like in %macro.
             # This means that you can't edit files whose names begin with
             # numbers this way. Tough.
             ranges = args.split()
             data = ''.join(self.extract_input_slices(ranges))
         elif args.endswith('.py'):
             filename = make_filename(args)
             data = ''
             use_temp = 0
         elif args:
             try:
                 # Load the parameter given as a variable. If not a string,
                 # process it as an object instead (below)
 
                 #print '*** args',args,'type',type(args)  # dbg
                 data = eval(args,self.shell.user_ns)
                 if not type(data) in StringTypes:
                     raise DataIsObject
 
             except (NameError,SyntaxError):
                 # given argument is not a variable, try as a filename
                 filename = make_filename(args)
                 if filename is None:
                     warn("Argument given (%s) can't be found as a variable "
                          "or as a filename." % args)
                     return
 
                 data = ''
                 use_temp = 0
             except DataIsObject:
 
                 # macros have a special edit function
                 if isinstance(data,Macro):
                     self._edit_macro(args,data)
                     return
                 
                 # For objects, try to edit the file where they are defined
                 try:
                     filename = inspect.getabsfile(data)
                     datafile = 1
                 except TypeError:
                     filename = make_filename(args)
                     datafile = 1
                     warn('Could not find file where `%s` is defined.\n'
                          'Opening a file named `%s`' % (args,filename))
                 # Now, make sure we can actually read the source (if it was in
                 # a temp file it's gone by now).
                 if datafile:
                     try:
                         lineno = inspect.getsourcelines(data)[1]
                     except IOError:
                         filename = make_filename(args)
                         if filename is None:
                             warn('The file `%s` where `%s` was defined cannot '
                                  'be read.' % (filename,data))
                             return
                 use_temp = 0
         else:
             data = ''
 
         if use_temp:
             filename = self.shell.mktempfile(data)
 
         # do actual editing here
         print 'Editing...',
         sys.stdout.flush()
         self.shell.hooks.editor(filename,lineno)
         if opts.has_key('x'):  # -x prevents actual execution
             print
         else:
             print 'done. Executing edited code...'
             try:
                 self.shell.safe_execfile(filename,self.shell.user_ns)
             except IOError,msg:
                 if msg.filename == filename:
                     warn('File not found. Did you forget to save?')
                     return
                 else:
                     self.shell.showtraceback()
             except:
                 self.shell.showtraceback()
 
     def magic_xmode(self,parameter_s = ''):
         """Switch modes for the exception handlers.
 
         Valid modes: Plain, Context and Verbose.
 
         If called without arguments, acts as a toggle."""
 
         def xmode_switch_err(name):
             warn('Error changing %s exception modes.\n%s' %
                  (name,sys.exc_info()[1]))
 
         shell = self.shell
         new_mode = parameter_s.strip().capitalize()
         try:
             shell.InteractiveTB.set_mode(mode=new_mode)
             print 'Exception reporting mode:',shell.InteractiveTB.mode
         except:
             xmode_switch_err('user')
 
         # threaded shells use a special handler in sys.excepthook
         if shell.isthreaded:
             try:
                 shell.sys_excepthook.set_mode(mode=new_mode)
             except:
                 xmode_switch_err('threaded')
             
     def magic_colors(self,parameter_s = ''):
         """Switch color scheme for prompts, info system and exception handlers.
 
         Currently implemented schemes: NoColor, Linux, LightBG.
 
         Color scheme names are not case-sensitive."""
 
         def color_switch_err(name):
             warn('Error changing %s color schemes.\n%s' %
                  (name,sys.exc_info()[1]))
             
         
         new_scheme = parameter_s.strip()
         if not new_scheme:
             print 'You must specify a color scheme.'
             return
         # Under Windows, check for Gary Bishop's readline, which is necessary
         # for ANSI coloring
         if os.name in ['nt','dos']:
             try:
                 import readline
             except ImportError:
                 has_readline = 0
             else:
                 try:
                     readline.GetOutputFile()
                 except AttributeError:
                     has_readline = 0
                 else:
                     has_readline = 1
             if not has_readline:
                 msg = """\
 Proper color support under MS Windows requires Gary Bishop's readline library.
 You can find it at:
 http://sourceforge.net/projects/uncpythontools
 Gary's readline needs the ctypes module, from:
 http://starship.python.net/crew/theller/ctypes
 
 Defaulting color scheme to 'NoColor'"""
                 new_scheme = 'NoColor'
                 warn(msg)
         # local shortcut
         shell = self.shell
         
         # Set prompt colors
         try:
             shell.outputcache.set_colors(new_scheme)
         except:
             color_switch_err('prompt')
         else:
             shell.rc.colors = \
                        shell.outputcache.color_table.active_scheme_name
         # Set exception colors
         try:
             shell.InteractiveTB.set_colors(scheme = new_scheme)
             shell.SyntaxTB.set_colors(scheme = new_scheme)
         except:
             color_switch_err('exception')
 
         # threaded shells use a verbose traceback in sys.excepthook
         if shell.isthreaded:
             try:
                 shell.sys_excepthook.set_colors(scheme=new_scheme)
             except:
                 color_switch_err('system exception handler')
         
         # Set info (for 'object?') colors
         if shell.rc.color_info:
             try:
                 shell.inspector.set_active_scheme(new_scheme)
             except:
                 color_switch_err('object inspector')
         else:
             shell.inspector.set_active_scheme('NoColor')
                 
     def magic_color_info(self,parameter_s = ''):
         """Toggle color_info.
 
         The color_info configuration parameter controls whether colors are
         used for displaying object details (by things like %psource, %pfile or
         the '?' system). This function toggles this value with each call.
 
         Note that unless you have a fairly recent pager (less works better
         than more) in your system, using colored object information displays
         will not work properly. Test it and see."""
         
         self.shell.rc.color_info = 1 - self.shell.rc.color_info
         self.magic_colors(self.shell.rc.colors)
         print 'Object introspection functions have now coloring:',
         print ['OFF','ON'][self.shell.rc.color_info]
 
     def magic_Pprint(self, parameter_s=''):
         """Toggle pretty printing on/off."""
         
         self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
         print 'Pretty printing has been turned', \
               ['OFF','ON'][self.shell.outputcache.Pprint]
         
     def magic_exit(self, parameter_s=''):
         """Exit IPython, confirming if configured to do so.
 
         You can configure whether IPython asks for confirmation upon exit by
         setting the confirm_exit flag in the ipythonrc file."""
 
         self.shell.exit()
 
     def magic_quit(self, parameter_s=''):
         """Exit IPython, confirming if configured to do so (like %exit)"""
 
         self.shell.exit()
         
     def magic_Exit(self, parameter_s=''):
         """Exit IPython without confirmation."""
 
         self.shell.exit_now = True
 
     def magic_Quit(self, parameter_s=''):
         """Exit IPython without confirmation (like %Exit)."""
 
         self.shell.exit_now = True
         
     #......................................................................
     # Functions to implement unix shell-type things
     
     def magic_alias(self, parameter_s = ''):
         """Define an alias for a system command.
 
         '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
         Then, typing 'alias_name params' will execute the system command 'cmd
         params' (from your underlying operating system).
 
         Aliases have lower precedence than magic functions and Python normal
         variables, so if 'foo' is both a Python variable and an alias, the
         alias can not be executed until 'del foo' removes the Python variable.
 
         You can use the %l specifier in an alias definition to represent the
         whole line when the alias is called.  For example:
 
           In [2]: alias all echo "Input in brackets: <%l>"\\
           In [3]: all hello world\\
           Input in brackets: <hello world>
 
         You can also define aliases with parameters using %s specifiers (one
         per parameter):
         
           In [1]: alias parts echo first %s second %s\\
           In [2]: %parts A B\\
           first A second B\\
           In [3]: %parts A\\
           Incorrect number of arguments: 2 expected.\\
           parts is an alias to: 'echo first %s second %s'
 
         Note that %l and %s are mutually exclusive.  You can only use one or
         the other in your aliases.
 
         Aliases expand Python variables just like system calls using ! or !! 
         do: all expressions prefixed with '$' get expanded.  For details of
         the semantic rules, see PEP-215:
         http://www.python.org/peps/pep-0215.html.  This is the library used by
         IPython for variable expansion.  If you want to access a true shell
         variable, an extra $ is necessary to prevent its expansion by IPython:
 
         In [6]: alias show echo\\
         In [7]: PATH='A Python string'\\
         In [8]: show $PATH\\
         A Python string\\
         In [9]: show $$PATH\\
         /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
 
         You can use the alias facility to acess all of $PATH.  See the %rehash
         and %rehashx functions, which automatically create aliases for the
         contents of your $PATH.
 
         If called with no parameters, %alias prints the current alias table."""
 
         par = parameter_s.strip()
         if not par:
             if self.shell.rc.automagic:
                 prechar = ''
             else:
                 prechar = self.shell.ESC_MAGIC
             print 'Alias\t\tSystem Command\n'+'-'*30
             atab = self.shell.alias_table
             aliases = atab.keys()
             aliases.sort()
             for alias in aliases:
                 print prechar+alias+'\t\t'+atab[alias][1]
             print '-'*30+'\nTotal number of aliases:',len(aliases)
             return
         try:
             alias,cmd = par.split(None,1)
         except:
             print OInspect.getdoc(self.magic_alias)
         else:
             nargs = cmd.count('%s')
             if nargs>0 and cmd.find('%l')>=0:
                 error('The %s and %l specifiers are mutually exclusive '
                       'in alias definitions.')
             else:  # all looks OK
                 self.shell.alias_table[alias] = (nargs,cmd)
                 self.shell.alias_table_validate(verbose=1)
     # end magic_alias
 
     def magic_unalias(self, parameter_s = ''):
         """Remove an alias"""
 
         aname = parameter_s.strip()
         if aname in self.shell.alias_table:
             del self.shell.alias_table[aname]
             
     def magic_rehash(self, parameter_s = ''):
         """Update the alias table with all entries in $PATH.
 
         This version does no checks on execute permissions or whether the
         contents of $PATH are truly files (instead of directories or something
         else).  For such a safer (but slower) version, use %rehashx."""
 
         # This function (and rehashx) manipulate the alias_table directly
         # rather than calling magic_alias, for speed reasons.  A rehash on a
         # typical Linux box involves several thousand entries, so efficiency
         # here is a top concern.
         
         path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
         alias_table = self.shell.alias_table
         for pdir in path:
             for ff in os.listdir(pdir):
                 # each entry in the alias table must be (N,name), where
                 # N is the number of positional arguments of the alias.
                 alias_table[ff] = (0,ff)
         # Make sure the alias table doesn't contain keywords or builtins
         self.shell.alias_table_validate()
         # Call again init_auto_alias() so we get 'rm -i' and other modified
         # aliases since %rehash will probably clobber them
         self.shell.init_auto_alias()
 
     def magic_rehashx(self, parameter_s = ''):
         """Update the alias table with all executable files in $PATH.
 
         This version explicitly checks that every entry in $PATH is a file
         with execute access (os.X_OK), so it is much slower than %rehash.
 
         Under Windows, it checks executability as a match agains a
         '|'-separated string of extensions, stored in the IPython config
         variable win_exec_ext.  This defaults to 'exe|com|bat'. """
         
         path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
         alias_table = self.shell.alias_table
 
         if os.name == 'posix':
             isexec = lambda fname:os.path.isfile(fname) and \
                      os.access(fname,os.X_OK)
         else:
 
             try:
                 winext = os.environ['pathext'].replace(';','|').replace('.','')
             except KeyError:
                 winext = 'exe|com|bat'
     
             execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
             isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
         savedir = os.getcwd()
         try:
             # write the whole loop for posix/Windows so we don't have an if in
             # the innermost part
             if os.name == 'posix':
                 for pdir in path:
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         if isexec(ff):
                             # each entry in the alias table must be (N,name),
                             # where N is the number of positional arguments of the
                             # alias.
                             alias_table[ff] = (0,ff)
             else:
                 for pdir in path:
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         if isexec(ff):
                             alias_table[execre.sub(r'\1',ff)] = (0,ff)
             # Make sure the alias table doesn't contain keywords or builtins
             self.shell.alias_table_validate()
             # Call again init_auto_alias() so we get 'rm -i' and other
             # modified aliases since %rehashx will probably clobber them
             self.shell.init_auto_alias()
         finally:
             os.chdir(savedir)
         
     def magic_pwd(self, parameter_s = ''):
         """Return the current working directory path."""
         return os.getcwd()
 
     def magic_cd(self, parameter_s=''):
         """Change the current working directory.
 
         This command automatically maintains an internal list of directories
         you visit during your IPython session, in the variable _dh. The
         command %dhist shows this history nicely formatted.
 
         Usage:
 
           cd 'dir': changes to directory 'dir'.
 
           cd -: changes to the last visited directory.
 
           cd -<n>: changes to the n-th directory in the directory history.
 
           cd -b <bookmark_name>: jump to a bookmark set by %bookmark
              (note: cd <bookmark_name> is enough if there is no
               directory <bookmark_name>, but a bookmark with the name exists.)
 
         Options:
 
         -q: quiet.  Do not print the working directory after the cd command is
         executed.  By default IPython's cd command does print this directory,
         since the default prompts do not display path information.
         
         Note that !cd doesn't work for this purpose because the shell where
         !command runs is immediately discarded after executing 'command'."""
 
         parameter_s = parameter_s.strip()
         bkms = self.shell.persist.get("bookmarks",{})
 
         numcd = re.match(r'(-)(\d+)$',parameter_s)
         # jump in directory history by number
         if numcd:
             nn = int(numcd.group(2))
             try:
                 ps = self.shell.user_ns['_dh'][nn]
             except IndexError:
                 print 'The requested directory does not exist in history.'
                 return
             else:
                 opts = {}
         else:
             opts,ps = self.parse_options(parameter_s,'qb',mode='string')
         # jump to previous
         if ps == '-':
             try:
                 ps = self.shell.user_ns['_dh'][-2]
             except IndexError:
                 print 'No previous directory to change to.'
                 return
         # jump to bookmark
         elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
             if bkms.has_key(ps):
                 target = bkms[ps]
                 print '(bookmark:%s) -> %s' % (ps,target)
                 ps = target
             else:
                 if bkms:
                     error("Bookmark '%s' not found.  "
                           "Use '%%bookmark -l' to see your bookmarks." % ps)
                 else:
                     print "Bookmarks not set - use %bookmark <bookmarkname>"
                 return
             
         # at this point ps should point to the target dir
         if ps:
             try:
                 os.chdir(os.path.expanduser(ps))
             except OSError:
                 print sys.exc_info()[1]
             else:
                 self.shell.user_ns['_dh'].append(os.getcwd())
         else:
             os.chdir(self.shell.home_dir)
             self.shell.user_ns['_dh'].append(os.getcwd())
         if not 'q' in opts:
             print self.shell.user_ns['_dh'][-1]
 
     def magic_dhist(self, parameter_s=''):
         """Print your history of visited directories.
 
         %dhist       -> print full history\\
         %dhist n     -> print last n entries only\\
         %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
 
         This history is automatically maintained by the %cd command, and
         always available as the global list variable _dh. You can use %cd -<n>
         to go to directory number <n>."""
 
         dh = self.shell.user_ns['_dh']
         if parameter_s:
             try:
                 args = map(int,parameter_s.split())
             except:
                 self.arg_err(Magic.magic_dhist)
                 return
             if len(args) == 1:
                 ini,fin = max(len(dh)-(args[0]),0),len(dh)
             elif len(args) == 2:
                 ini,fin = args
             else:
                 self.arg_err(Magic.magic_dhist)
                 return
         else:
             ini,fin = 0,len(dh)
         nlprint(dh,
                 header = 'Directory history (kept in _dh)',
                 start=ini,stop=fin)
 
     def magic_env(self, parameter_s=''):
         """List environment variables."""
         
         return os.environ.data
 
     def magic_pushd(self, parameter_s=''):
         """Place the current dir on stack and change directory.
         
         Usage:\\
           %pushd ['dirname']
 
         %pushd with no arguments does a %pushd to your home directory.
         """
         if parameter_s == '': parameter_s = '~'
         dir_s = self.shell.dir_stack
         if len(dir_s)>0 and os.path.expanduser(parameter_s) != \
            os.path.expanduser(self.shell.dir_stack[0]):
             try:
                 self.magic_cd(parameter_s)
                 dir_s.insert(0,os.getcwd().replace(self.home_dir,'~'))
                 self.magic_dirs()
             except:
                 print 'Invalid directory'
         else:
             print 'You are already there!'
 
     def magic_popd(self, parameter_s=''):
         """Change to directory popped off the top of the stack.
         """
         if len (self.shell.dir_stack) > 1:
             self.shell.dir_stack.pop(0)
             self.magic_cd(self.shell.dir_stack[0])
             print self.shell.dir_stack[0]
         else:
             print "You can't remove the starting directory from the stack:",\
                   self.shell.dir_stack
 
     def magic_dirs(self, parameter_s=''):
         """Return the current directory stack."""
 
         return self.shell.dir_stack[:]
 
     def magic_sc(self, parameter_s=''):
         """Shell capture - execute a shell command and capture its output.
 
         %sc [options] varname=command
 
         IPython will run the given command using commands.getoutput(), and
         will then update the user's interactive namespace with a variable
         called varname, containing the value of the call.  Your command can
         contain shell wildcards, pipes, etc.
 
         The '=' sign in the syntax is mandatory, and the variable name you
         supply must follow Python's standard conventions for valid names.
 
         Options:
 
           -l: list output.  Split the output on newlines into a list before
           assigning it to the given variable.  By default the output is stored
           as a single string.
 
           -v: verbose.  Print the contents of the variable.
 
         In most cases you should not need to split as a list, because the
         returned value is a special type of string which can automatically
         provide its contents either as a list (split on newlines) or as a
         space-separated string.  These are convenient, respectively, either
         for sequential processing or to be passed to a shell command.
 
         For example:
 
             # Capture into variable a
             In [9]: sc a=ls *py
 
             # a is a string with embedded newlines
             In [10]: a
             Out[10]: 'setup.py\nwin32_manual_post_install.py'
 
             # which can be seen as a list:
             In [11]: a.l
             Out[11]: ['setup.py', 'win32_manual_post_install.py']
 
             # or as a whitespace-separated string:
             In [12]: a.s
             Out[12]: 'setup.py win32_manual_post_install.py'
 
             # a.s is useful to pass as a single command line:
             In [13]: !wc -l $a.s
               146 setup.py
               130 win32_manual_post_install.py
               276 total
 
             # while the list form is useful to loop over:
             In [14]: for f in a.l:
                ....:      !wc -l $f
                ....:
             146 setup.py
             130 win32_manual_post_install.py
 
         Similiarly, the lists returned by the -l option are also special, in
         the sense that you can equally invoke the .s attribute on them to
         automatically get a whitespace-separated string from their contents:
 
             In [1]: sc -l b=ls *py
 
             In [2]: b
             Out[2]: ['setup.py', 'win32_manual_post_install.py']
 
             In [3]: b.s
             Out[3]: 'setup.py win32_manual_post_install.py'
 
         In summary, both the lists and strings used for ouptut capture have
         the following special attributes:
 
             .l (or .list) : value as list.
             .n (or .nlstr): value as newline-separated string.
             .s (or .spstr): value as space-separated string.
         """
 
         opts,args = self.parse_options(parameter_s,'lv')
         # Try to get a variable name and command to run
         try:
             # the variable name must be obtained from the parse_options
             # output, which uses shlex.split to strip options out.
             var,_ = args.split('=',1)
             var = var.strip()
             # But the the command has to be extracted from the original input
             # parameter_s, not on what parse_options returns, to avoid the
             # quote stripping which shlex.split performs on it.
             _,cmd = parameter_s.split('=',1)
         except ValueError:
             var,cmd = '',''
         if not var:
             error('you must specify a variable to assign the command to.')
             return
         # If all looks ok, proceed
         out,err = self.shell.getoutputerror(cmd)
         if err:
             print >> Term.cerr,err
         if opts.has_key('l'):
             out = SList(out.split('\n'))
         else:
             out = LSString(out)
         if opts.has_key('v'):
             print '%s ==\n%s' % (var,pformat(out))
         self.shell.user_ns.update({var:out})
 
     def magic_sx(self, parameter_s=''):
         """Shell execute - run a shell command and capture its output.
 
         %sx command
 
         IPython will run the given command using commands.getoutput(), and
         return the result formatted as a list (split on '\\n').  Since the
         output is _returned_, it will be stored in ipython's regular output
         cache Out[N] and in the '_N' automatic variables.
 
         Notes:
 
         1) If an input line begins with '!!', then %sx is automatically
         invoked.  That is, while:
           !ls
         causes ipython to simply issue system('ls'), typing
           !!ls
         is a shorthand equivalent to:
           %sx ls
         
         2) %sx differs from %sc in that %sx automatically splits into a list,
         like '%sc -l'.  The reason for this is to make it as easy as possible
         to process line-oriented shell output via further python commands.
         %sc is meant to provide much finer control, but requires more
         typing.
 
         3) Just like %sc -l, this is a list with special attributes:
 
           .l (or .list) : value as list.
           .n (or .nlstr): value as newline-separated string.
           .s (or .spstr): value as whitespace-separated string.
 
         This is very useful when trying to use such lists as arguments to
         system commands."""
 
         if parameter_s:
             out,err = self.shell.getoutputerror(parameter_s)
             if err:
                 print >> Term.cerr,err
             return SList(out.split('\n'))
 
     def magic_bg(self, parameter_s=''):
         """Run a job in the background, in a separate thread.
 
         For example,
 
           %bg myfunc(x,y,z=1)
 
         will execute 'myfunc(x,y,z=1)' in a background thread.  As soon as the
         execution starts, a message will be printed indicating the job
         number.  If your job number is 5, you can use
 
           myvar = jobs.result(5)  or  myvar = jobs[5].result
 
         to assign this result to variable 'myvar'.
 
         IPython has a job manager, accessible via the 'jobs' object.  You can
         type jobs? to get more information about it, and use jobs.<TAB> to see
         its attributes.  All attributes not starting with an underscore are
         meant for public use.
 
         In particular, look at the jobs.new() method, which is used to create
         new jobs.  This magic %bg function is just a convenience wrapper
         around jobs.new(), for expression-based jobs.  If you want to create a
         new job with an explicit function object and arguments, you must call
         jobs.new() directly.
 
         The jobs.new docstring also describes in detail several important
         caveats associated with a thread-based model for background job
         execution.  Type jobs.new? for details.
 
         You can check the status of all jobs with jobs.status().
 
         The jobs variable is set by IPython into the Python builtin namespace.
         If you ever declare a variable named 'jobs', you will shadow this
         name.  You can either delete your global jobs variable to regain
         access to the job manager, or make a new name and assign it manually
         to the manager (stored in IPython's namespace).  For example, to
         assign the job manager to the Jobs name, use:
 
           Jobs = __builtins__.jobs"""
         
         self.shell.jobs.new(parameter_s,self.shell.user_ns)
         
     def magic_store(self, parameter_s=''):
         """Lightweight persistence for python variables.
 
         Example:
         
         ville@badger[~]|1> A = ['hello',10,'world']\\
         ville@badger[~]|2> %store A\\
         ville@badger[~]|3> Exit
         
         (IPython session is closed and started again...)
         
         ville@badger:~$ ipython -p pysh\\
         ville@badger[~]|1> print A
         
         ['hello', 10, 'world']
         
         Usage:
         
         %store          - Show list of all variables and their current values\\
         %store <var>    - Store the *current* value of the variable to disk\\
         %store -d <var> - Remove the variable and its value from storage\\
         %store -r       - Remove all variables from storage
         
         It should be noted that if you change the value of a variable, you
         need to %store it again if you want to persist the new value.
         
         Note also that the variables will need to be pickleable; most basic
         python types can be safely %stored.
         """
         
         opts,args = self.parse_options(parameter_s,'dr',mode='list')
         # delete
         if opts.has_key('d'):
             try:
                 todel = args[0]
             except IndexError:
                 error('You must provide the variable to forget')
             else:
                 try:
                     del self.shell.persist['S:' + todel]
                 except:
                     error("Can't delete variable '%s'" % todel)
         # reset
         elif opts.has_key('r'):
             for k in self.shell.persist.keys():
                 if k.startswith('S:'):
                     del self.shell.persist[k]
         
         # run without arguments -> list variables & values
         elif not args:
             vars = [v[2:] for v in self.shell.persist.keys()
                     if v.startswith('S:')]
             vars.sort()            
             if vars:
                 size = max(map(len,vars))
             else:
                 size = 0
                 
             print 'Stored variables and their in-memory values:'
             fmt = '%-'+str(size)+'s -> %s'
             get = self.shell.user_ns.get
             for var in vars:
                 # print 30 first characters from every var
                 print fmt % (var,repr(get(var,'<unavailable>'))[:50])
         
         # default action - store the variable
         else:
             pickled = pickle.dumps(self.shell.user_ns[args[0] ])
             self.shell.persist[ 'S:' + args[0] ] = pickled
             print "Stored '%s' (%d bytes)" % (args[0], len(pickled))
     
     def magic_bookmark(self, parameter_s=''):
         """Manage IPython's bookmark system.
 
         %bookmark <name>       - set bookmark to current dir
         %bookmark <name> <dir> - set bookmark to <dir>
         %bookmark -l           - list all bookmarks
         %bookmark -d <name>    - remove bookmark
         %bookmark -r           - remove all bookmarks
 
         You can later on access a bookmarked folder with:
           %cd -b <name>
         or simply '%cd <name>' if there is no directory called <name> AND
         there is such a bookmark defined.
 
         Your bookmarks persist through IPython sessions, but they are
         associated with each profile."""
 
         opts,args = self.parse_options(parameter_s,'drl',mode='list')
         if len(args) > 2:
             error('You can only give at most two arguments')
             return
 
         bkms = self.shell.persist.get('bookmarks',{})
             
         if opts.has_key('d'):
             try:
                 todel = args[0]
             except IndexError:
                 error('You must provide a bookmark to delete')
             else:
                 try:
                     del bkms[todel]
                 except:
                     error("Can't delete bookmark '%s'" % todel)
         elif opts.has_key('r'):
             bkms = {}
         elif opts.has_key('l'):
             bks = bkms.keys()
             bks.sort()
             if bks:
                 size = max(map(len,bks))
             else:
                 size = 0
             fmt = '%-'+str(size)+'s -> %s'
             print 'Current bookmarks:'
             for bk in bks:
                 print fmt % (bk,bkms[bk])
         else:
             if not args:
                 error("You must specify the bookmark name")
             elif len(args)==1:
                 bkms[args[0]] = os.getcwd()
             elif len(args)==2:
                 bkms[args[0]] = args[1]
         self.shell.persist['bookmarks'] = bkms
 
     def magic_pycat(self, parameter_s=''):
         """Show a syntax-highlighted file through a pager.
 
         This magic is similar to the cat utility, but it will assume the file
         to be Python source and will show it with syntax highlighting. """
         
         filename = get_py_filename(parameter_s)
         page(self.shell.colorize(file_read(filename)),
              screen_lines=self.shell.rc.screen_length)
 
 # end Magic

IPython/Prompts.py

@@ -1,583 +1,583 b''
 # -*- coding: utf-8 -*-
 """
 Classes for handling input/output prompts.
 
-$Id: Prompts.py 975 2005-12-29 23:50:22Z fperez $"""
+$Id: Prompts.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 __version__ = Release.version
 
 #****************************************************************************
 # Required modules
 import __builtin__
 import os
 import socket
 import sys
 import time
 from pprint import pprint,pformat
 
 # IPython's own
 from IPython import ColorANSI
 from IPython.Itpl import ItplNS
 from IPython.Struct import Struct
 from IPython.macro import Macro
 from IPython.genutils import *
 
 #****************************************************************************
 #Color schemes for Prompts.
 
 PromptColors = ColorANSI.ColorSchemeTable()
 InputColors = ColorANSI.InputTermColors  # just a shorthand
 Colors = ColorANSI.TermColors  # just a shorthand
 
 PromptColors.add_scheme(ColorANSI.ColorScheme(
     'NoColor',
     in_prompt  = InputColors.NoColor,  # Input prompt
     in_number  = InputColors.NoColor,  # Input prompt number
     in_prompt2 = InputColors.NoColor, # Continuation prompt
     in_normal  = InputColors.NoColor,  # color off (usu. Colors.Normal)
     
     out_prompt = Colors.NoColor, # Output prompt
     out_number = Colors.NoColor, # Output prompt number
 
     normal = Colors.NoColor  # color off (usu. Colors.Normal)
     ))
 
 # make some schemes as instances so we can copy them for modification easily:
 __PColLinux =  ColorANSI.ColorScheme(
     'Linux',
     in_prompt  = InputColors.Green,
     in_number  = InputColors.LightGreen,
     in_prompt2 = InputColors.Green,
     in_normal  = InputColors.Normal,  # color off (usu. Colors.Normal)
 
     out_prompt = Colors.Red,
     out_number = Colors.LightRed,
 
     normal = Colors.Normal
     )
 # Don't forget to enter it into the table!
 PromptColors.add_scheme(__PColLinux)
 
 # Slightly modified Linux for light backgrounds
 __PColLightBG  = __PColLinux.copy('LightBG')
 
 __PColLightBG.colors.update(
     in_prompt  = InputColors.Blue,
     in_number  = InputColors.LightBlue,
     in_prompt2 = InputColors.Blue
 )
 PromptColors.add_scheme(__PColLightBG)
 
 del Colors,InputColors
 
 #-----------------------------------------------------------------------------
 def multiple_replace(dict, text):
     """ Replace in 'text' all occurences of any key in the given
     dictionary by its corresponding value.  Returns the new string."""
 
     # Function by Xavier Defrang, originally found at:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/81330
 
     # Create a regular expression  from the dictionary keys
     regex = re.compile("(%s)" % "|".join(map(re.escape, dict.keys())))
     # For each match, look-up corresponding value in dictionary
     return regex.sub(lambda mo: dict[mo.string[mo.start():mo.end()]], text)
 
 #-----------------------------------------------------------------------------
 # Special characters that can be used in prompt templates, mainly bash-like
 
 # If $HOME isn't defined (Windows), make it an absurd string so that it can
 # never be expanded out into '~'.  Basically anything which can never be a
 # reasonable directory name will do, we just want the $HOME -> '~' operation
 # to become a no-op.  We pre-compute $HOME here so it's not done on every
 # prompt call.
 
 # FIXME:
 
 # - This should be turned into a class which does proper namespace management,
 # since the prompt specials need to be evaluated in a certain namespace.
 # Currently it's just globals, which need to be managed manually by code
 # below.
 
 # - I also need to split up the color schemes from the prompt specials
 # somehow.  I don't have a clean design for that quite yet.
 
 HOME = os.environ.get("HOME","//////:::::ZZZZZ,,,~~~")
 
 # We precompute a few more strings here for the prompt_specials, which are
 # fixed once ipython starts.  This reduces the runtime overhead of computing
 # prompt strings.
 USER           = os.environ.get("USER")
 HOSTNAME       = socket.gethostname()
 HOSTNAME_SHORT = HOSTNAME.split(".")[0]
 ROOT_SYMBOL    = "$#"[os.name=='nt' or os.getuid()==0]
 
 prompt_specials_color = {
     # Prompt/history count
     '%n' : '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
     '\\#': '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
     # Prompt/history count, with the actual digits replaced by dots.  Used
     # mainly in continuation prompts (prompt_in2)
     '\\D': '${"."*len(str(self.cache.prompt_count))}',
     # Current working directory
     '\\w': '${os.getcwd()}',
     # Current time
     '\\t' : '${time.strftime("%H:%M:%S")}',
     # Basename of current working directory.
     # (use os.sep to make this portable across OSes)
     '\\W' : '${os.getcwd().split("%s")[-1]}' % os.sep,
     # These X<N> are an extension to the normal bash prompts.  They return
     # N terms of the path, after replacing $HOME with '~'
     '\\X0': '${os.getcwd().replace("%s","~")}' % HOME,
     '\\X1': '${self.cwd_filt(1)}',
     '\\X2': '${self.cwd_filt(2)}',
     '\\X3': '${self.cwd_filt(3)}',
     '\\X4': '${self.cwd_filt(4)}',
     '\\X5': '${self.cwd_filt(5)}',
     # Y<N> are similar to X<N>, but they show '~' if it's the directory
     # N+1 in the list.  Somewhat like %cN in tcsh.
     '\\Y0': '${self.cwd_filt2(0)}',
     '\\Y1': '${self.cwd_filt2(1)}',
     '\\Y2': '${self.cwd_filt2(2)}',
     '\\Y3': '${self.cwd_filt2(3)}',
     '\\Y4': '${self.cwd_filt2(4)}',
     '\\Y5': '${self.cwd_filt2(5)}',
     # Hostname up to first .
     '\\h': HOSTNAME_SHORT,
     # Full hostname
     '\\H': HOSTNAME,
     # Username of current user
     '\\u': USER,
     # Escaped '\'
     '\\\\': '\\',
     # Newline
     '\\n': '\n',
     # Carriage return
     '\\r': '\r',
     # Release version
     '\\v': __version__,
     # Root symbol ($ or #)
     '\\$': ROOT_SYMBOL,
     }
 
 # A copy of the prompt_specials dictionary but with all color escapes removed,
 # so we can correctly compute the prompt length for the auto_rewrite method.
 prompt_specials_nocolor = prompt_specials_color.copy()
 prompt_specials_nocolor['%n'] = '${self.cache.prompt_count}'
 prompt_specials_nocolor['\\#'] = '${self.cache.prompt_count}'
 
 # Add in all the InputTermColors color escapes as valid prompt characters.
 # They all get added as \\C_COLORNAME, so that we don't have any conflicts
 # with a color name which may begin with a letter used by any other of the
 # allowed specials.  This of course means that \\C will never be allowed for
 # anything else.
 input_colors = ColorANSI.InputTermColors
 for _color in dir(input_colors):
     if _color[0] != '_':
         c_name = '\\C_'+_color
         prompt_specials_color[c_name] = getattr(input_colors,_color)
         prompt_specials_nocolor[c_name] = ''
 
 # we default to no color for safety.  Note that prompt_specials is a global
 # variable used by all prompt objects.
 prompt_specials = prompt_specials_nocolor
 
 #-----------------------------------------------------------------------------
 def str_safe(arg):
     """Convert to a string, without ever raising an exception.
 
     If str(arg) fails, <ERROR: ... > is returned, where ... is the exception
     error message."""
 
     try:
         out = str(arg)
     except UnicodeError:
         try:
             out = arg.encode('utf_8','replace')
         except Exception,msg:
             # let's keep this little duplication here, so that the most common
             # case doesn't suffer from a double try wrapping.
             out = '<ERROR: %s>' % msg
     except Exception,msg:
         out = '<ERROR: %s>' % msg
     return out
 
 class BasePrompt:
     """Interactive prompt similar to Mathematica's."""
     def __init__(self,cache,sep,prompt,pad_left=False):
 
         # Hack: we access information about the primary prompt through the
         # cache argument.  We need this, because we want the secondary prompt
         # to be aligned with the primary one.  Color table info is also shared
         # by all prompt classes through the cache.  Nice OO spaghetti code!
         self.cache = cache
         self.sep = sep
         
         # regexp to count the number of spaces at the end of a prompt
         # expression, useful for prompt auto-rewriting
         self.rspace = re.compile(r'(\s*)$')
         # Flag to left-pad prompt strings to match the length of the primary
         # prompt
         self.pad_left = pad_left
         # Set template to create each actual prompt (where numbers change)
         self.p_template = prompt
         self.set_p_str()
 
     def set_p_str(self):
         """ Set the interpolating prompt strings.
 
         This must be called every time the color settings change, because the
         prompt_specials global may have changed."""
 
         import os,time  # needed in locals for prompt string handling
         loc = locals()
         self.p_str = ItplNS('%s%s%s' %
                             ('${self.sep}${self.col_p}',
                              multiple_replace(prompt_specials, self.p_template),
                              '${self.col_norm}'),self.cache.user_ns,loc)
         
         self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
                                                      self.p_template),
                                     self.cache.user_ns,loc)
 
     def write(self,msg):  # dbg
         sys.stdout.write(msg)
         return ''
 
     def __str__(self):
         """Return a string form of the prompt.
 
         This for is useful for continuation and output prompts, since it is
         left-padded to match lengths with the primary one (if the
         self.pad_left attribute is set)."""
 
         out_str = str_safe(self.p_str)
         if self.pad_left:
             # We must find the amount of padding required to match lengths,
             # taking the color escapes (which are invisible on-screen) into
             # account.
             esc_pad = len(out_str) - len(str_safe(self.p_str_nocolor))
             format = '%%%ss' % (len(str(self.cache.last_prompt))+esc_pad)
             return format % out_str
         else:
             return out_str
 
     # these path filters are put in as methods so that we can control the
     # namespace where the prompt strings get evaluated
     def cwd_filt(self,depth):
         """Return the last depth elements of the current working directory.
 
         $HOME is always replaced with '~'.
         If depth==0, the full path is returned."""
 
         cwd = os.getcwd().replace(HOME,"~")
         out = os.sep.join(cwd.split(os.sep)[-depth:])
         if out:
             return out
         else:
             return os.sep
 
     def cwd_filt2(self,depth):
         """Return the last depth elements of the current working directory.
 
         $HOME is always replaced with '~'.
         If depth==0, the full path is returned."""
 
         cwd = os.getcwd().replace(HOME,"~").split(os.sep)
         if '~' in cwd and len(cwd) == depth+1:
             depth += 1
         out = os.sep.join(cwd[-depth:])
         if out:
             return out
         else:
             return os.sep
 
 class Prompt1(BasePrompt):
     """Input interactive prompt similar to Mathematica's."""
 
     def __init__(self,cache,sep='\n',prompt='In [\\#]: ',pad_left=True):
         BasePrompt.__init__(self,cache,sep,prompt,pad_left)
 
     def set_colors(self):
         self.set_p_str()
         Colors = self.cache.color_table.active_colors # shorthand
         self.col_p = Colors.in_prompt
         self.col_num = Colors.in_number
         self.col_norm = Colors.in_normal
         # We need a non-input version of these escapes for the '--->'
         # auto-call prompts used in the auto_rewrite() method.
         self.col_p_ni = self.col_p.replace('\001','').replace('\002','') 
         self.col_norm_ni = Colors.normal        
         
     def __str__(self):
         self.cache.prompt_count += 1
         self.cache.last_prompt = str_safe(self.p_str_nocolor).split('\n')[-1]
         return str_safe(self.p_str)
 
     def auto_rewrite(self):
         """Print a string of the form '--->' which lines up with the previous
         input string. Useful for systems which re-write the user input when
         handling automatically special syntaxes."""
 
         curr = str(self.cache.last_prompt)
         nrspaces = len(self.rspace.search(curr).group())
         return '%s%s>%s%s' % (self.col_p_ni,'-'*(len(curr)-nrspaces-1),
                               ' '*nrspaces,self.col_norm_ni)
 
 class PromptOut(BasePrompt):
     """Output interactive prompt similar to Mathematica's."""
 
     def __init__(self,cache,sep='',prompt='Out[\\#]: ',pad_left=True):
         BasePrompt.__init__(self,cache,sep,prompt,pad_left)
         if not self.p_template:
             self.__str__ = lambda: ''
 
     def set_colors(self):
         self.set_p_str()
         Colors = self.cache.color_table.active_colors # shorthand
         self.col_p = Colors.out_prompt
         self.col_num = Colors.out_number
         self.col_norm = Colors.normal
 
 class Prompt2(BasePrompt):
     """Interactive continuation prompt."""
     
     def __init__(self,cache,prompt='   .\\D.: ',pad_left=True):
         self.cache = cache
         self.p_template = prompt
         self.pad_left = pad_left
         self.set_p_str()
 
     def set_p_str(self):
         import os,time  # needed in locals for prompt string handling
         loc = locals()
         self.p_str = ItplNS('%s%s%s' %
                             ('${self.col_p2}',
                              multiple_replace(prompt_specials, self.p_template),
                              '$self.col_norm'),
                             self.cache.user_ns,loc)
         self.p_str_nocolor = ItplNS(multiple_replace(prompt_specials_nocolor,
                                                      self.p_template),
                                     self.cache.user_ns,loc)
 
     def set_colors(self):
         self.set_p_str()
         Colors = self.cache.color_table.active_colors
         self.col_p2 = Colors.in_prompt2
         self.col_norm = Colors.in_normal
         # FIXME (2004-06-16) HACK: prevent crashes for users who haven't
         # updated their prompt_in2 definitions.  Remove eventually.
         self.col_p = Colors.out_prompt
         self.col_num = Colors.out_number
 
 #-----------------------------------------------------------------------------
 class CachedOutput:
     """Class for printing output from calculations while keeping a cache of
     reults. It dynamically creates global variables prefixed with _ which
     contain these results.
 
     Meant to be used as a sys.displayhook replacement, providing numbered
     prompts and cache services.
 
     Initialize with initial and final values for cache counter (this defines
     the maximum size of the cache."""
 
     def __init__(self,shell,cache_size,Pprint,
                  colors='NoColor',input_sep='\n',
                  output_sep='\n',output_sep2='',
                  ps1 = None, ps2 = None,ps_out = None,pad_left=True):
 
         cache_size_min = 20
         if cache_size <= 0:
             self.do_full_cache = 0
             cache_size = 0
         elif cache_size < cache_size_min:
             self.do_full_cache = 0
             cache_size = 0
             warn('caching was disabled (min value for cache size is %s).' %
                  cache_size_min,level=3)
         else:
             self.do_full_cache = 1
 
         self.cache_size = cache_size
         self.input_sep = input_sep
 
         # we need a reference to the user-level namespace
         self.shell = shell
         self.user_ns = shell.user_ns
         # and to the user's input
         self.input_hist = shell.input_hist
         # and to the user's logger, for logging output
         self.logger = shell.logger
 
         # Set input prompt strings and colors
         if cache_size == 0:
             if ps1.find('%n') > -1 or ps1.find('\\#') > -1: ps1 = '>>> '
             if ps2.find('%n') > -1 or ps2.find('\\#') > -1: ps2 = '... '
         self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
         self.ps2_str = self._set_prompt_str(ps2,'   .\\D.: ','... ')
         self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
 
         self.color_table = PromptColors
         self.prompt1 = Prompt1(self,sep=input_sep,prompt=self.ps1_str,
                                pad_left=pad_left)
         self.prompt2 = Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
         self.prompt_out = PromptOut(self,sep='',prompt=self.ps_out_str,
                                     pad_left=pad_left)
         self.set_colors(colors)
 
         # other more normal stuff
         # b/c each call to the In[] prompt raises it by 1, even the first.
         self.prompt_count = 0
         self.cache_count = 1
         # Store the last prompt string each time, we need it for aligning
         # continuation and auto-rewrite prompts
         self.last_prompt = ''
         self.entries = [None]  # output counter starts at 1 for the user
         self.Pprint = Pprint
         self.output_sep = output_sep
         self.output_sep2 = output_sep2
         self._,self.__,self.___ = '','',''
         self.pprint_types = map(type,[(),[],{}])
         
         # these are deliberately global:
         to_user_ns = {'_':self._,'__':self.__,'___':self.___}
         self.user_ns.update(to_user_ns)
 
     def _set_prompt_str(self,p_str,cache_def,no_cache_def):
         if p_str is None:
             if self.do_full_cache:
                 return cache_def
             else:
                 return no_cache_def
         else:
             return p_str
                 
     def set_colors(self,colors):
         """Set the active color scheme and configure colors for the three
         prompt subsystems."""
 
         # FIXME: the prompt_specials global should be gobbled inside this
         # class instead.  Do it when cleaning up the whole 3-prompt system.
         global prompt_specials
         if colors.lower()=='nocolor':
             prompt_specials = prompt_specials_nocolor
         else:
             prompt_specials = prompt_specials_color
         
         self.color_table.set_active_scheme(colors)
         self.prompt1.set_colors()
         self.prompt2.set_colors()
         self.prompt_out.set_colors()
 
     def __call__(self,arg=None):
         """Printing with history cache management.
         
         This is invoked everytime the interpreter needs to print, and is
         activated by setting the variable sys.displayhook to it."""
 
         # If something injected a '_' variable in __builtin__, delete
         # ipython's automatic one so we don't clobber that.  gettext() in
         # particular uses _, so we need to stay away from it.
         if '_' in __builtin__.__dict__:
             try:
                 del self.user_ns['_']
             except KeyError:
                 pass
         if arg is not None:
             cout_write = Term.cout.write # fast lookup
             # first handle the cache and counters
             # but avoid recursive reference when displaying _oh/Out
             if arg is not self.user_ns['_oh']:
                 self.update(arg)
             # do not print output if input ends in ';'
             if self.input_hist[self.prompt_count].endswith(';\n'):
                 return
             # don't use print, puts an extra space
             cout_write(self.output_sep)
             if self.do_full_cache:
                 cout_write(str(self.prompt_out))
 
             if isinstance(arg,Macro):
                 print 'Executing Macro...'
                 # in case the macro takes a long time to execute
                 Term.cout.flush()
                 self.shell.runlines(arg.value)
                 return None
 
             # and now call a possibly user-defined print mechanism
             self.display(arg)
             if self.logger.log_output:
                 self.logger.log_write(repr(arg),'output')
             cout_write(self.output_sep2)
             Term.cout.flush()
 
     def _display(self,arg):
         """Default printer method, uses pprint.
 
         This can be over-ridden by the users to implement special formatting
         of certain types of output."""
 
         if self.Pprint:
             out = pformat(arg)
             if '\n' in out:
                 # So that multi-line strings line up with the left column of
                 # the screen, instead of having the output prompt mess up
                 # their first line.                
                 Term.cout.write('\n')
             print >>Term.cout, out
         else:
             print >>Term.cout, arg
 
     # Assign the default display method:
     display = _display
 
     def update(self,arg):
         #print '***cache_count', self.cache_count # dbg
         if self.cache_count >= self.cache_size and self.do_full_cache:
             self.flush()
         # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
         # we cause buggy behavior for things like gettext).
         if '_' not in __builtin__.__dict__:
             self.___ = self.__
             self.__ = self._
             self._ = arg
             self.user_ns.update({'_':self._,'__':self.__,'___':self.___})
             
         # hackish access to top-level  namespace to create _1,_2... dynamically
         to_main = {}
         if self.do_full_cache:
             self.cache_count += 1
             self.entries.append(arg)
             new_result = '_'+`self.prompt_count`
             to_main[new_result] = self.entries[-1]
         self.user_ns.update(to_main)
         self.user_ns['_oh'][self.prompt_count] = arg
 
     def flush(self):
         if not self.do_full_cache:
             raise ValueError,"You shouldn't have reached the cache flush "\
                   "if full caching is not enabled!"
         warn('Output cache limit (currently '+\
               `self.cache_count`+' entries) hit.\n'
              'Flushing cache and resetting history counter...\n'
              'The only history variables available will be _,__,___ and _1\n'
              'with the current result.')
         # delete auto-generated vars from global namespace
         for n in range(1,self.prompt_count + 1):
             key = '_'+`n`
             try:
                 del self.user_ns[key]
             except: pass
         self.prompt_count = 1
         self.cache_count = 1

IPython/Release.py

@@ -1,76 +1,76 b''
 # -*- coding: utf-8 -*-
 """Release data for the IPython project.
 
-$Id: Release.py 992 2006-01-04 18:35:40Z fperez $"""
+$Id: Release.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2005 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #       Copyright (c) 2001 Janko Hauser <[e-mail]> and Nathaniel Gray
 #       <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 # Name of the package for release purposes.  This is the name which labels
 # the tarballs and RPMs made by distutils, so it's best to lowercase it.
 name = 'ipython'
 
 # For versions with substrings (like 0.6.16.svn), use an extra . to separate
 # the new substring.  We have to avoid using either dashes or underscores,
 # because bdist_rpm does not accept dashes (an RPM) convention, and
 # bdist_deb does not accept underscores (a Debian convention).
 
 version = '0.7.0.rc8'
 
-revision = '$Revision: 992 $'
+revision = '$Revision: 994 $'
 
 description = "An enhanced interactive Python shell."
 
 long_description = \
 """
 IPython provides a replacement for the interactive Python interpreter with
 extra functionality.
 
 Main features:
 
  * Comprehensive object introspection.
 
  * Input history, persistent across sessions.
 
  * Caching of output results during a session with automatically generated
    references.
 
  * Readline based name completion.
 
  * Extensible system of 'magic' commands for controlling the environment and
    performing many tasks related either to IPython or the operating system.
 
  * Configuration system with easy switching between different setups (simpler
    than changing $PYTHONSTARTUP environment variables every time).
 
  * Session logging and reloading.
 
  * Extensible syntax processing for special purpose situations.
 
  * Access to the system shell with user-extensible alias system.
 
  * Easily embeddable in other Python programs.
 
  * Integrated access to the pdb debugger and the Python profiler. """
 
 license = 'BSD'
 
 authors = {'Fernando' : ('Fernando Perez','[e-mail]'),
            'Janko'    : ('Janko Hauser','[e-mail]'),
            'Nathan'   : ('Nathaniel Gray','[e-mail]')
            }
 
 url = 'http://ipython.scipy.org'
 
 download_url = 'http://ipython.scipy.org/dist'
 
 platforms = ['Linux','Mac OSX','Windows XP/2000/NT','Windows 95/98/ME']
 
 keywords = ['Interactive','Interpreter','Shell']

IPython/Shell.py

@@ -1,917 +1,917 b''
 # -*- coding: utf-8 -*-
 """IPython Shell classes.
 
 All the matplotlib support code was co-developed with John Hunter,
 matplotlib's author.
 
-$Id: Shell.py 993 2006-01-04 19:51:01Z fperez $"""
+$Id: Shell.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 # Code begins
 import __main__
 import __builtin__
 import os
 import sys
 import signal
 import threading
 
 import IPython
 from IPython import ultraTB
 from IPython.genutils import Term,warn,error,flag_calls
 from IPython.iplib import InteractiveShell
 from IPython.ipmaker import make_IPython
 from IPython.Magic import Magic
 from IPython.Struct import Struct
 
 # global flag to pass around information about Ctrl-C without exceptions
 KBINT = False
 
 # global flag to turn on/off Tk support.
 USE_TK = False
 
 #-----------------------------------------------------------------------------
 # This class is trivial now, but I want to have it in to publish a clean
 # interface. Later when the internals are reorganized, code that uses this
 # shouldn't have to change.
 
 class IPShell:
     """Create an IPython instance."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=InteractiveShell):
         self.IP = make_IPython(argv,user_ns=user_ns,user_global_ns=user_global_ns,
                                debug=debug,shell_class=shell_class)
 
     def mainloop(self,sys_exit=0,banner=None):
         self.IP.mainloop(banner)
         if sys_exit:
             sys.exit()
 
 #-----------------------------------------------------------------------------
 class IPShellEmbed:
     """Allow embedding an IPython shell into a running program.
 
     Instances of this class are callable, with the __call__ method being an
     alias to the embed() method of an InteractiveShell instance.
 
     Usage (see also the example-embed.py file for a running example):
 
     ipshell = IPShellEmbed([argv,banner,exit_msg,rc_override])
 
     - argv: list containing valid command-line options for IPython, as they
     would appear in sys.argv[1:].
 
     For example, the following command-line options:
 
       $ ipython -prompt_in1 'Input <\\#>' -colors LightBG
 
     would be passed in the argv list as:
 
       ['-prompt_in1','Input <\\#>','-colors','LightBG']
 
     - banner: string which gets printed every time the interpreter starts.
 
     - exit_msg: string which gets printed every time the interpreter exits.
 
     - rc_override: a dict or Struct of configuration options such as those
     used by IPython. These options are read from your ~/.ipython/ipythonrc
     file when the Shell object is created. Passing an explicit rc_override
     dict with any options you want allows you to override those values at
     creation time without having to modify the file. This way you can create
     embeddable instances configured in any way you want without editing any
     global files (thus keeping your interactive IPython configuration
     unchanged).
 
     Then the ipshell instance can be called anywhere inside your code:
     
     ipshell(header='') -> Opens up an IPython shell.
 
     - header: string printed by the IPython shell upon startup. This can let
     you know where in your code you are when dropping into the shell. Note
     that 'banner' gets prepended to all calls, so header is used for
     location-specific information.
 
     For more details, see the __call__ method below.
 
     When the IPython shell is exited with Ctrl-D, normal program execution
     resumes.
 
     This functionality was inspired by a posting on comp.lang.python by cmkl
     <[e-mail]> on Dec. 06/01 concerning similar uses of pyrepl, and
     by the IDL stop/continue commands."""
 
     def __init__(self,argv=None,banner='',exit_msg=None,rc_override=None):
         """Note that argv here is a string, NOT a list."""
         self.set_banner(banner)
         self.set_exit_msg(exit_msg)
         self.set_dummy_mode(0)
 
         # sys.displayhook is a global, we need to save the user's original
         # Don't rely on __displayhook__, as the user may have changed that.
         self.sys_displayhook_ori = sys.displayhook
 
         # save readline completer status
         try:
             #print 'Save completer',sys.ipcompleter  # dbg
             self.sys_ipcompleter_ori = sys.ipcompleter
         except:
             pass # not nested with IPython
         
         # FIXME. Passing user_ns breaks namespace handling.
         #self.IP = make_IPython(argv,user_ns=__main__.__dict__)
         self.IP = make_IPython(argv,rc_override=rc_override,embedded=True)
 
         # copy our own displayhook also
         self.sys_displayhook_embed = sys.displayhook
         # and leave the system's display hook clean
         sys.displayhook = self.sys_displayhook_ori
         # don't use the ipython crash handler so that user exceptions aren't
         # trapped
         sys.excepthook = ultraTB.FormattedTB(color_scheme = self.IP.rc.colors,
                                              mode = self.IP.rc.xmode,
                                              call_pdb = self.IP.rc.pdb)
         self.restore_system_completer()
 
     def restore_system_completer(self):
         """Restores the readline completer which was in place.
 
         This allows embedded IPython within IPython not to disrupt the
         parent's completion.
         """
         
         try:
             self.IP.readline.set_completer(self.sys_ipcompleter_ori)
             sys.ipcompleter = self.sys_ipcompleter_ori
         except:
             pass
 
     def __call__(self,header='',local_ns=None,global_ns=None,dummy=None):
         """Activate the interactive interpreter.
 
         __call__(self,header='',local_ns=None,global_ns,dummy=None) -> Start
         the interpreter shell with the given local and global namespaces, and
         optionally print a header string at startup.
 
         The shell can be globally activated/deactivated using the
         set/get_dummy_mode methods. This allows you to turn off a shell used
         for debugging globally.
 
         However, *each* time you call the shell you can override the current
         state of dummy_mode with the optional keyword parameter 'dummy'. For
         example, if you set dummy mode on with IPShell.set_dummy_mode(1), you
         can still have a specific call work by making it as IPShell(dummy=0).
 
         The optional keyword parameter dummy controls whether the call
         actually does anything.  """
 
         # Allow the dummy parameter to override the global __dummy_mode
         if dummy or (dummy != 0 and self.__dummy_mode):
             return
 
         # Set global subsystems (display,completions) to our values
         sys.displayhook = self.sys_displayhook_embed
         if self.IP.has_readline:
             self.IP.readline.set_completer(self.IP.Completer.complete)
 
         if self.banner and header:
             format = '%s\n%s\n'
         else:
             format = '%s%s\n'
         banner =  format % (self.banner,header)
 
         # Call the embedding code with a stack depth of 1 so it can skip over
         # our call and get the original caller's namespaces.
         self.IP.embed_mainloop(banner,local_ns,global_ns,stack_depth=1)
 
         if self.exit_msg:
             print self.exit_msg
             
         # Restore global systems (display, completion)
         sys.displayhook = self.sys_displayhook_ori
         self.restore_system_completer()
     
     def set_dummy_mode(self,dummy):
         """Sets the embeddable shell's dummy mode parameter.
 
         set_dummy_mode(dummy): dummy = 0 or 1.
 
         This parameter is persistent and makes calls to the embeddable shell
         silently return without performing any action. This allows you to
         globally activate or deactivate a shell you're using with a single call.
 
         If you need to manually"""
 
         if dummy not in [0,1,False,True]:
             raise ValueError,'dummy parameter must be boolean'
         self.__dummy_mode = dummy
 
     def get_dummy_mode(self):
         """Return the current value of the dummy mode parameter.
         """
         return self.__dummy_mode
     
     def set_banner(self,banner):
         """Sets the global banner.
 
         This banner gets prepended to every header printed when the shell
         instance is called."""
 
         self.banner = banner
 
     def set_exit_msg(self,exit_msg):
         """Sets the global exit_msg.
 
         This exit message gets printed upon exiting every time the embedded
         shell is called. It is None by default. """
 
         self.exit_msg = exit_msg
 
 #-----------------------------------------------------------------------------
 def sigint_handler (signum,stack_frame):
     """Sigint handler for threaded apps.
 
     This is a horrible hack to pass information about SIGINT _without_ using
     exceptions, since I haven't been able to properly manage cross-thread
     exceptions in GTK/WX.  In fact, I don't think it can be done (or at least
     that's my understanding from a c.l.py thread where this was discussed)."""
 
     global KBINT
     
     print '\nKeyboardInterrupt - Press <Enter> to continue.',
     Term.cout.flush()
     # Set global flag so that runsource can know that Ctrl-C was hit
     KBINT = True
 
 class MTInteractiveShell(InteractiveShell):
     """Simple multi-threaded shell."""
 
     # Threading strategy taken from:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/65109, by Brian
     # McErlean and John Finlay.  Modified with corrections by Antoon Pardon,
     # from the pygtk mailing list, to avoid lockups with system calls.
 
     # class attribute to indicate whether the class supports threads or not.
     # Subclasses with thread support should override this as needed.
     isthreaded = True
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None,banner2='',**kw):
         """Similar to the normal InteractiveShell, but with threading control"""
         
         InteractiveShell.__init__(self,name,usage,rc,user_ns,
                                   user_global_ns,banner2)
 
         # Locking control variable
         self.thread_ready = threading.Condition()
 
         # Stuff to do at closing time
         self._kill = False
         on_kill = kw.get('on_kill')
         if on_kill is None:
             on_kill = []
         # Check that all things to kill are callable:
         for t in on_kill:
             if not callable(t):
                 raise TypeError,'on_kill must be a list of callables'
         self.on_kill = on_kill
 
     def runsource(self, source, filename="<input>", symbol="single"):
         """Compile and run some source in the interpreter.
 
         Modified version of code.py's runsource(), to handle threading issues.
         See the original for full docstring details."""
 
         global KBINT
         
         # If Ctrl-C was typed, we reset the flag and return right away
         if KBINT:
             KBINT = False
             return False
         
         try:
             code = self.compile(source, filename, symbol)
         except (OverflowError, SyntaxError, ValueError):
             # Case 1
             self.showsyntaxerror(filename)
             return False
 
         if code is None:
             # Case 2
             return True
 
         # Case 3
         # Store code in self, so the execution thread can handle it
         self.thread_ready.acquire()
         self.code_to_run = code
         self.thread_ready.wait()  # Wait until processed in timeout interval
         self.thread_ready.release()
 
         return False
 
     def runcode(self):
         """Execute a code object.
 
         Multithreaded wrapper around IPython's runcode()."""
 
         # lock thread-protected stuff
         self.thread_ready.acquire()
 
         # Install sigint handler
         try:
             signal.signal(signal.SIGINT, sigint_handler)
         except SystemError:
             # This happens under Windows, which seems to have all sorts
             # of problems with signal handling.  Oh well...
             pass
 
         if self._kill:
             print >>Term.cout, 'Closing threads...',
             Term.cout.flush()
             for tokill in self.on_kill:
                 tokill()
             print >>Term.cout, 'Done.'
 
         # Run pending code by calling parent class
         if self.code_to_run is not None:
             self.thread_ready.notify()
             InteractiveShell.runcode(self,self.code_to_run)
             
         # We're done with thread-protected variables
         self.thread_ready.release()
         # This MUST return true for gtk threading to work
         return True
 
     def kill (self):
         """Kill the thread, returning when it has been shut down."""
         self.thread_ready.acquire()
         self._kill = True
         self.thread_ready.release()
 
 class MatplotlibShellBase:
     """Mixin class to provide the necessary modifications to regular IPython
     shell classes for matplotlib support.
 
     Given Python's MRO, this should be used as the FIRST class in the
     inheritance hierarchy, so that it overrides the relevant methods."""
     
     def _matplotlib_config(self,name):
         """Return various items needed to setup the user's shell with matplotlib"""
 
         # Initialize matplotlib to interactive mode always
         import matplotlib
         from matplotlib import backends
         matplotlib.interactive(True)
 
         def use(arg):
             """IPython wrapper for matplotlib's backend switcher.
 
             In interactive use, we can not allow switching to a different
             interactive backend, since thread conflicts will most likely crash
             the python interpreter.  This routine does a safety check first,
             and refuses to perform a dangerous switch.  It still allows
             switching to non-interactive backends."""
 
             if arg in backends.interactive_bk and arg != self.mpl_backend:
                 m=('invalid matplotlib backend switch.\n'
                    'This script attempted to switch to the interactive '
                    'backend: `%s`\n'
                    'Your current choice of interactive backend is: `%s`\n\n'
                    'Switching interactive matplotlib backends at runtime\n'
                    'would crash the python interpreter, '
                    'and IPython has blocked it.\n\n'
                    'You need to either change your choice of matplotlib backend\n'
                    'by editing your .matplotlibrc file, or run this script as a \n'
                    'standalone file from the command line, not using IPython.\n' %
                    (arg,self.mpl_backend) )
                 raise RuntimeError, m
             else:
                 self.mpl_use(arg)
                 self.mpl_use._called = True
         
         self.matplotlib = matplotlib
         self.mpl_backend = matplotlib.rcParams['backend']
 
         # we also need to block switching of interactive backends by use()
         self.mpl_use = matplotlib.use
         self.mpl_use._called = False
         # overwrite the original matplotlib.use with our wrapper
         matplotlib.use = use
 
 
         # This must be imported last in the matplotlib series, after
         # backend/interactivity choices have been made
         try:
             import matplotlib.pylab as pylab
             self.pylab = pylab
             self.pylab_name = 'pylab'
         except ImportError:
             import matplotlib.matlab as matlab            
             self.pylab = matlab
             self.pylab_name = 'matlab'
 
         self.pylab.show._needmain = False
         # We need to detect at runtime whether show() is called by the user.
         # For this, we wrap it into a decorator which adds a 'called' flag.
         self.pylab.draw_if_interactive = flag_calls(self.pylab.draw_if_interactive)
 
         # Build a user namespace initialized with matplotlib/matlab features.
         user_ns = {'__name__':'__main__',
                    '__builtins__' : __builtin__ }
 
         # Be careful not to remove the final \n in the code string below, or
         # things will break badly with py22 (I think it's a python bug, 2.3 is
         # OK).
         pname = self.pylab_name # Python can't interpolate dotted var names
         exec ("import matplotlib\n"
               "import matplotlib.%(pname)s as %(pname)s\n"
               "from matplotlib.%(pname)s import *\n" % locals()) in user_ns
         
         # Build matplotlib info banner
         b="""
   Welcome to pylab, a matplotlib-based Python environment.
   For more information, type 'help(pylab)'.
 """
         return user_ns,b
 
     def mplot_exec(self,fname,*where,**kw):
         """Execute a matplotlib script.
 
         This is a call to execfile(), but wrapped in safeties to properly
         handle interactive rendering and backend switching."""
 
         #print '*** Matplotlib runner ***' # dbg
         # turn off rendering until end of script
         isInteractive = self.matplotlib.rcParams['interactive']
         self.matplotlib.interactive(False)
         self.safe_execfile(fname,*where,**kw)
         self.matplotlib.interactive(isInteractive)
         # make rendering call now, if the user tried to do it
         if self.pylab.draw_if_interactive.called:
             self.pylab.draw()
             self.pylab.draw_if_interactive.called = False
                 
         # if a backend switch was performed, reverse it now
         if self.mpl_use._called:
             self.matplotlib.rcParams['backend'] = self.mpl_backend
         
     def magic_run(self,parameter_s=''):
         Magic.magic_run(self,parameter_s,runner=self.mplot_exec)
 
     # Fix the docstring so users see the original as well
     magic_run.__doc__ = "%s\n%s" % (Magic.magic_run.__doc__,
                                     "\n        *** Modified %run for Matplotlib,"
                                     " with proper interactive handling ***")
 
 # Now we provide 2 versions of a matplotlib-aware IPython base shells, single
 # and multithreaded.  Note that these are meant for internal use, the IPShell*
 # classes below are the ones meant for public consumption.
 
 class MatplotlibShell(MatplotlibShellBase,InteractiveShell):
     """Single-threaded shell with matplotlib support."""
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None,**kw):
         user_ns,b2 = self._matplotlib_config(name)
         InteractiveShell.__init__(self,name,usage,rc,user_ns,user_global_ns,
                                   banner2=b2,**kw)
 
 class MatplotlibMTShell(MatplotlibShellBase,MTInteractiveShell):
     """Multi-threaded shell with matplotlib support."""
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns=None,user_global_ns=None, **kw):
         user_ns,b2 = self._matplotlib_config(name)
         MTInteractiveShell.__init__(self,name,usage,rc,user_ns,user_global_ns,
                                     banner2=b2,**kw)
 
 #-----------------------------------------------------------------------------
 # Utility functions for the different GUI enabled IPShell* classes.
 
 def get_tk():
     """Tries to import Tkinter and returns a withdrawn Tkinter root
     window.  If Tkinter is already imported or not available, this
     returns None.  This function calls `hijack_tk` underneath.
     """
     if not USE_TK or sys.modules.has_key('Tkinter'):
         return None
     else:
         try:
             import Tkinter
         except ImportError:
             return None
         else:
             hijack_tk()
             r = Tkinter.Tk()
             r.withdraw()
             return r
 
 def hijack_tk():
     """Modifies Tkinter's mainloop with a dummy so when a module calls
     mainloop, it does not block.
 
     """
     def misc_mainloop(self, n=0):
         pass
     def tkinter_mainloop(n=0):
         pass
     
     import Tkinter
     Tkinter.Misc.mainloop = misc_mainloop
     Tkinter.mainloop = tkinter_mainloop
 
 def update_tk(tk):
     """Updates the Tkinter event loop.  This is typically called from
     the respective WX or GTK mainloops.
     """    
     if tk:
         tk.update()
 
 def hijack_wx():
     """Modifies wxPython's MainLoop with a dummy so user code does not
     block IPython.  The hijacked mainloop function is returned.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     import wxPython
     ver = wxPython.__version__
     orig_mainloop = None
     if ver[:3] >= '2.5':
         import wx
         if hasattr(wx, '_core_'): core = getattr(wx, '_core_')
         elif hasattr(wx, '_core'): core = getattr(wx, '_core')
         else: raise AttributeError('Could not find wx core module')
         orig_mainloop = core.PyApp_MainLoop
         core.PyApp_MainLoop = dummy_mainloop
     elif ver[:3] == '2.4':
         orig_mainloop = wxPython.wxc.wxPyApp_MainLoop
         wxPython.wxc.wxPyApp_MainLoop = dummy_mainloop
     else:
         warn("Unable to find either wxPython version 2.4 or >= 2.5.")
     return orig_mainloop
 
 def hijack_gtk():
     """Modifies pyGTK's mainloop with a dummy so user code does not
     block IPython.  This function returns the original `gtk.mainloop`
     function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     import gtk
     if gtk.pygtk_version >= (2,4,0): orig_mainloop = gtk.main
     else:                            orig_mainloop = gtk.mainloop
     gtk.mainloop = dummy_mainloop
     gtk.main = dummy_mainloop
     return orig_mainloop
 
 #-----------------------------------------------------------------------------
 # The IPShell* classes below are the ones meant to be run by external code as
 # IPython instances.  Note that unless a specific threading strategy is
 # desired, the factory function start() below should be used instead (it
 # selects the proper threaded class).
 
 class IPShellGTK(threading.Thread):
     """Run a gtk mainloop() in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     GTK timeout callback."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=MTInteractiveShell):
 
         import gtk
         
         self.gtk = gtk
         self.gtk_mainloop = hijack_gtk()
 
         # Allows us to use both Tk and GTK.
         self.tk = get_tk()
         
         if gtk.pygtk_version >= (2,4,0): mainquit = self.gtk.main_quit
         else:                            mainquit = self.gtk.mainquit
 
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[mainquit])
 
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
 
         threading.Thread.__init__(self)
 
     def run(self):
         self.IP.mainloop(self._banner)
         self.IP.kill()
 
     def mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         if self.gtk.pygtk_version >= (2,4,0):
             import gobject
             gobject.timeout_add(self.TIMEOUT, self.on_timer)
         else:
             self.gtk.timeout_add(self.TIMEOUT, self.on_timer)
 
         if sys.platform != 'win32':
             try:
                 if self.gtk.gtk_version[0] >= 2:
                     self.gtk.threads_init()
             except AttributeError:
                 pass
             except RuntimeError:
                 error('Your pyGTK likely has not been compiled with '
                       'threading support.\n'
                       'The exception printout is below.\n'
                       'You can either rebuild pyGTK with threads, or '
                       'try using \n'
                       'matplotlib with a different backend (like Tk or WX).\n'
                       'Note that matplotlib will most likely not work in its '
                       'current state!')
                 self.IP.InteractiveTB()
         self.start()
         self.gtk.threads_enter()
         self.gtk_mainloop()
         self.gtk.threads_leave()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         return self.IP.runcode()
         
 
 class IPShellWX(threading.Thread):
     """Run a wx mainloop() in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     GTK timeout callback."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=1,shell_class=MTInteractiveShell):
 
         import wxPython.wx as wx
 
         threading.Thread.__init__(self)
         self.wx = wx
         self.wx_mainloop = hijack_wx()
 
         # Allows us to use both Tk and GTK.
         self.tk = get_tk()
         
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[self.wxexit])
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
 
         self.app = None
 
     def wxexit(self, *args):
         if self.app is not None:
             self.app.agent.timer.Stop()
             self.app.ExitMainLoop()
 
     def run(self):
         self.IP.mainloop(self._banner)
         self.IP.kill()
 
     def mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         self.start()
 
         class TimerAgent(self.wx.wxMiniFrame):
             wx = self.wx
             IP = self.IP
             tk = self.tk
             def __init__(self, parent, interval):
                 style = self.wx.wxDEFAULT_FRAME_STYLE | self.wx.wxTINY_CAPTION_HORIZ
                 self.wx.wxMiniFrame.__init__(self, parent, -1, ' ', pos=(200, 200),
                                              size=(100, 100),style=style)
                 self.Show(False)
                 self.interval = interval
                 self.timerId = self.wx.wxNewId()                                
 
             def StartWork(self):
                 self.timer = self.wx.wxTimer(self, self.timerId)
                 self.wx.EVT_TIMER(self,  self.timerId, self.OnTimer)
                 self.timer.Start(self.interval)
 
             def OnTimer(self, event):
                 update_tk(self.tk)
                 self.IP.runcode()
 
         class App(self.wx.wxApp):
             wx = self.wx
             TIMEOUT = self.TIMEOUT
             def OnInit(self):
                 'Create the main window and insert the custom frame'
                 self.agent = TimerAgent(None, self.TIMEOUT)
                 self.agent.Show(self.wx.false)
                 self.agent.StartWork()
                 return self.wx.true
         
         self.app = App(redirect=False)
         self.wx_mainloop(self.app)
         self.join()
 
 
 class IPShellQt(threading.Thread):
     """Run a Qt event loop in a separate thread.
     
     Python commands can be passed to the thread where they will be executed.
     This is implemented by periodically checking for passed code using a
     Qt timer / slot."""
     
     TIMEOUT = 100 # Millisecond interval between timeouts.
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,
                  debug=0,shell_class=MTInteractiveShell):
         
         import qt
 
         class newQApplication:
             def __init__( self ):
                 self.QApplication = qt.QApplication
                 
             def __call__( *args, **kwargs ):
                 return qt.qApp
 
             def exec_loop( *args, **kwargs ):
                 pass
 
             def __getattr__( self, name ):
                 return getattr( self.QApplication, name )
           
         qt.QApplication = newQApplication()
 
         # Allows us to use both Tk and QT.
         self.tk = get_tk()
 
         self.IP = make_IPython(argv,user_ns=user_ns,
                                user_global_ns=user_global_ns,
                                debug=debug,
                                shell_class=shell_class,
                                on_kill=[qt.qApp.exit])
 
         # HACK: slot for banner in self; it will be passed to the mainloop
         # method only and .run() needs it.  The actual value will be set by
         # .mainloop().
         self._banner = None 
         
         threading.Thread.__init__(self)
 
     def run(self):
         self.IP.mainloop(self._banner)
         self.IP.kill()
 
     def mainloop(self,sys_exit=0,banner=None):
 
         import qt
 
         self._banner = banner
 
         if qt.QApplication.startingUp():
           a = qt.QApplication.QApplication(sys.argv)
         self.timer = qt.QTimer()
         qt.QObject.connect( self.timer, qt.SIGNAL( 'timeout()' ), self.on_timer )
 
         self.start()
         self.timer.start( self.TIMEOUT, True )
         while True:
             if self.IP._kill: break
             qt.qApp.exec_loop()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         result = self.IP.runcode()
         self.timer.start( self.TIMEOUT, True )
         return result
 
 # A set of matplotlib public IPython shell classes, for single-threaded
 # (Tk* and FLTK* backends) and multithreaded (GTK* and WX* backends) use.
 class IPShellMatplotlib(IPShell):
     """Subclass IPShell with MatplotlibShell as the internal shell.
 
     Single-threaded class, meant for the Tk* and FLTK* backends.
 
     Having this on a separate class simplifies the external driver code."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShell.__init__(self,argv,user_ns,user_global_ns,debug,
                          shell_class=MatplotlibShell)
 
 class IPShellMatplotlibGTK(IPShellGTK):
     """Subclass IPShellGTK with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the GTK* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellGTK.__init__(self,argv,user_ns,user_global_ns,debug,
                             shell_class=MatplotlibMTShell)
 
 class IPShellMatplotlibWX(IPShellWX):
     """Subclass IPShellWX with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the WX* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellWX.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
 
 class IPShellMatplotlibQt(IPShellQt):
     """Subclass IPShellQt with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the Qt* backends."""
     
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellQt.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
 
 #-----------------------------------------------------------------------------
 # Factory functions to actually start the proper thread-aware shell
 
 def _matplotlib_shell_class():
     """Factory function to handle shell class selection for matplotlib.
 
     The proper shell class to use depends on the matplotlib backend, since
     each backend requires a different threading strategy."""
 
     try:
         import matplotlib
     except ImportError:
         error('matplotlib could NOT be imported!  Starting normal IPython.')
         sh_class = IPShell
     else:
         backend = matplotlib.rcParams['backend']
         if backend.startswith('GTK'):
             sh_class = IPShellMatplotlibGTK
         elif backend.startswith('WX'):
             sh_class = IPShellMatplotlibWX
         elif backend.startswith('Qt'):
             sh_class = IPShellMatplotlibQt
         else:
             sh_class = IPShellMatplotlib
     #print 'Using %s with the %s backend.' % (sh_class,backend) # dbg
     return sh_class
 
 # This is the one which should be called by external code.
 def start():
     """Return a running shell instance, dealing with threading options.
 
     This is a factory function which will instantiate the proper IPython shell
     based on the user's threading choice.  Such a selector is needed because
     different GUI toolkits require different thread handling details."""
 
     global USE_TK
     # Crude sys.argv hack to extract the threading options.
     argv = sys.argv
     if len(argv) > 1:
         if len(argv) > 2:
             arg2 = argv[2]
             if arg2.endswith('-tk'):
                 USE_TK = True
         arg1 = argv[1]
         if arg1.endswith('-gthread'):
             shell = IPShellGTK
         elif arg1.endswith( '-qthread' ):
             shell = IPShellQt
         elif arg1.endswith('-wthread'):
             shell = IPShellWX
         elif arg1.endswith('-pylab'):
             shell = _matplotlib_shell_class()
         else:
             shell = IPShell
     else:
         shell = IPShell
     return shell()
 
 # Some aliases for backwards compatibility
 IPythonShell = IPShell
 IPythonShellEmbed = IPShellEmbed
 #************************ End of file <Shell.py> ***************************

IPython/background_jobs.py

@@ -1,496 +1,496 b''
 # -*- coding: utf-8 -*-
 """Manage background (threaded) jobs conveniently from an interactive shell.
 
 This module provides a BackgroundJobManager class.  This is the main class
 meant for public usage, it implements an object which can create and manage
 new background jobs.
 
 It also provides the actual job classes managed by these BackgroundJobManager
 objects, see their docstrings below.
 
 
 This system was inspired by discussions with B. Granger and the
 BackgroundCommand class described in the book Python Scripting for
 Computational Science, by H. P. Langtangen:
 
 http://folk.uio.no/hpl/scripting
 
 (although ultimately no code from this text was used, as IPython's system is a
 separate implementation).
 
-$Id: background_jobs.py 958 2005-12-27 23:17:51Z fperez $
+$Id: background_jobs.py 994 2006-01-08 08:29:44Z fperez $
 """
 
 #*****************************************************************************
-#       Copyright (C) 2005 Fernando Perez <[e-mail]>
+#       Copyright (C) 2005-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 # Code begins
 import sys
 import threading
 
 from IPython.ultraTB import AutoFormattedTB
 from IPython.genutils import warn,error
 
 class BackgroundJobManager:
     """Class to manage a pool of backgrounded threaded jobs.
 
     Below, we assume that 'jobs' is a BackgroundJobManager instance.
     
     Usage summary (see the method docstrings for details):
 
       jobs.new(...) -> start a new job
       
       jobs() or jobs.status() -> print status summary of all jobs
 
       jobs[N] -> returns job number N.
 
       foo = jobs[N].result -> assign to variable foo the result of job N
 
       jobs[N].traceback() -> print the traceback of dead job N
 
       jobs.remove(N) -> remove (finished) job N
 
       jobs.flush_finished() -> remove all finished jobs
       
     As a convenience feature, BackgroundJobManager instances provide the
     utility result and traceback methods which retrieve the corresponding
     information from the jobs list:
 
       jobs.result(N) <--> jobs[N].result
       jobs.traceback(N) <--> jobs[N].traceback()
 
     While this appears minor, it allows you to use tab completion
     interactively on the job manager instance.
 
     In interactive mode, IPython provides the magic fuction %bg for quick
     creation of backgrounded expression-based jobs. Type bg? for details."""
 
     def __init__(self):
         # Lists for job management
         self.jobs_run  = []
         self.jobs_comp = []
         self.jobs_dead = []
         # A dict of all jobs, so users can easily access any of them
         self.jobs_all = {}
         # For reporting
         self._comp_report = []
         self._dead_report = []
         # Store status codes locally for fast lookups
         self._s_created   = BackgroundJobBase.stat_created_c
         self._s_running   = BackgroundJobBase.stat_running_c
         self._s_completed = BackgroundJobBase.stat_completed_c
         self._s_dead      = BackgroundJobBase.stat_dead_c
 
     def new(self,func_or_exp,*args,**kwargs):
         """Add a new background job and start it in a separate thread.
 
         There are two types of jobs which can be created:
 
         1. Jobs based on expressions which can be passed to an eval() call.
         The expression must be given as a string.  For example:
 
           job_manager.new('myfunc(x,y,z=1)'[,glob[,loc]])
 
         The given expression is passed to eval(), along with the optional
         global/local dicts provided.  If no dicts are given, they are
         extracted automatically from the caller's frame.
         
         A Python statement is NOT a valid eval() expression.  Basically, you
         can only use as an eval() argument something which can go on the right
         of an '=' sign and be assigned to a variable.
 
         For example,"print 'hello'" is not valid, but '2+3' is.
 
         2. Jobs given a function object, optionally passing additional
         positional arguments:
 
           job_manager.new(myfunc,x,y)
 
         The function is called with the given arguments.
 
         If you need to pass keyword arguments to your function, you must
         supply them as a dict named kw:
 
           job_manager.new(myfunc,x,y,kw=dict(z=1))
 
         The reason for this assymmetry is that the new() method needs to
         maintain access to its own keywords, and this prevents name collisions
         between arguments to new() and arguments to your own functions.
 
         In both cases, the result is stored in the job.result field of the
         background job object.
 
 
         Notes and caveats:
 
         1. All threads running share the same standard output.  Thus, if your
         background jobs generate output, it will come out on top of whatever
         you are currently writing.  For this reason, background jobs are best
         used with silent functions which simply return their output.
 
         2. Threads also all work within the same global namespace, and this
         system does not lock interactive variables.  So if you send job to the
         background which operates on a mutable object for a long time, and
         start modifying that same mutable object interactively (or in another
         backgrounded job), all sorts of bizarre behaviour will occur.
 
         3. If a background job is spending a lot of time inside a C extension
         module which does not release the Python Global Interpreter Lock
         (GIL), this will block the IPython prompt.  This is simply because the
         Python interpreter can only switch between threads at Python
         bytecodes.  While the execution is inside C code, the interpreter must
         simply wait unless the extension module releases the GIL.
 
         4. There is no way, due to limitations in the Python threads library,
         to kill a thread once it has started."""
         
         if callable(func_or_exp):
             kw  = kwargs.get('kw',{})
             job = BackgroundJobFunc(func_or_exp,*args,**kw)
         elif isinstance(func_or_exp,basestring):
             if not args:
                 frame = sys._getframe(1)
                 glob, loc = frame.f_globals, frame.f_locals
             elif len(args)==1:
                 glob = loc = args[0]
             elif len(args)==2:
                 glob,loc = args
             else:
                 raise ValueError,\
                       'Expression jobs take at most 2 args (globals,locals)'
             job = BackgroundJobExpr(func_or_exp,glob,loc)
         else:
             raise
         jkeys = self.jobs_all.keys()
         if jkeys:
             job.num = max(jkeys)+1
         else:
             job.num = 0
         self.jobs_run.append(job)
         self.jobs_all[job.num] = job
         print 'Starting job # %s in a separate thread.' % job.num
         job.start()
         return job
 
     def __getitem__(self,key):
         return self.jobs_all[key]
 
     def __call__(self):
         """An alias to self.status(),
 
         This allows you to simply call a job manager instance much like the
         Unix jobs shell command."""
 
         return self.status()
 
     def _update_status(self):
         """Update the status of the job lists.
 
         This method moves finished jobs to one of two lists:
           - self.jobs_comp: jobs which completed successfully
           - self.jobs_dead: jobs which finished but died.
 
         It also copies those jobs to corresponding _report lists.  These lists
         are used to report jobs completed/dead since the last update, and are
         then cleared by the reporting function after each call."""
         
         run,comp,dead = self._s_running,self._s_completed,self._s_dead
         jobs_run = self.jobs_run
         for num in range(len(jobs_run)):
             job  = jobs_run[num]
             stat = job.stat_code
             if stat == run:
                 continue
             elif stat == comp:
                 self.jobs_comp.append(job)
                 self._comp_report.append(job)
                 jobs_run[num] = False
             elif stat == dead:
                 self.jobs_dead.append(job)
                 self._dead_report.append(job)
                 jobs_run[num] = False
         self.jobs_run = filter(None,self.jobs_run)
 
     def _group_report(self,group,name):
         """Report summary for a given job group.
 
         Return True if the group had any elements."""
 
         if group:
             print '%s jobs:' % name
             for job in group:
                 print '%s : %s' % (job.num,job)
             print
             return True
 
     def _group_flush(self,group,name):
         """Flush a given job group
 
         Return True if the group had any elements."""
 
         njobs = len(group)
         if njobs:
             plural = {1:''}.setdefault(njobs,'s')
             print 'Flushing %s %s job%s.' % (njobs,name,plural)
             group[:] = []
             return True
         
     def _status_new(self):
         """Print the status of newly finished jobs.
 
         Return True if any new jobs are reported.
 
         This call resets its own state every time, so it only reports jobs
         which have finished since the last time it was called."""
 
         self._update_status()
         new_comp = self._group_report(self._comp_report,'Completed')
         new_dead = self._group_report(self._dead_report,
                                       'Dead, call job.traceback() for details')
         self._comp_report[:] = []
         self._dead_report[:] = []
         return new_comp or new_dead
                 
     def status(self,verbose=0):
         """Print a status of all jobs currently being managed."""
 
         self._update_status()
         self._group_report(self.jobs_run,'Running')
         self._group_report(self.jobs_comp,'Completed')
         self._group_report(self.jobs_dead,'Dead')
         # Also flush the report queues
         self._comp_report[:] = []
         self._dead_report[:] = []
 
     def remove(self,num):
         """Remove a finished (completed or dead) job."""
 
         try:
             job = self.jobs_all[num]
         except KeyError:
             error('Job #%s not found' % num)
         else:
             stat_code = job.stat_code
             if stat_code == self._s_running:
                 error('Job #%s is still running, it can not be removed.' % num)
                 return
             elif stat_code == self._s_completed:
                 self.jobs_comp.remove(job)
             elif stat_code == self._s_dead:
                 self.jobs_dead.remove(job)
 
     def flush_finished(self):
         """Flush all jobs finished (completed and dead) from lists.
 
         Running jobs are never flushed.
 
         It first calls _status_new(), to update info. If any jobs have
         completed since the last _status_new() call, the flush operation
         aborts."""
 
         if self._status_new():
             error('New jobs completed since last '\
                   '_status_new(), aborting flush.')
             return
 
         # Remove the finished jobs from the master dict
         jobs_all = self.jobs_all
         for job in self.jobs_comp+self.jobs_dead:
             del(jobs_all[job.num])
 
         # Now flush these lists completely
         fl_comp = self._group_flush(self.jobs_comp,'Completed')
         fl_dead = self._group_flush(self.jobs_dead,'Dead')
         if not (fl_comp or fl_dead):
             print 'No jobs to flush.'
 
     def result(self,num):
         """result(N) -> return the result of job N."""
         try:
             return self.jobs_all[num].result
         except KeyError:
             error('Job #%s not found' % num)
 
     def traceback(self,num):
         try:
             self.jobs_all[num].traceback()
         except KeyError:
             error('Job #%s not found' % num)
 
 
 class BackgroundJobBase(threading.Thread):
     """Base class to build BackgroundJob classes.
 
     The derived classes must implement:
 
     - Their own __init__, since the one here raises NotImplementedError.  The
     derived constructor must call self._init() at the end, to provide common
     initialization.
 
     - A strform attribute used in calls to __str__.
 
     - A call() method, which will make the actual execution call and must
     return a value to be held in the 'result' field of the job object."""
 
     # Class constants for status, in string and as numerical codes (when
     # updating jobs lists, we don't want to do string comparisons).  This will
     # be done at every user prompt, so it has to be as fast as possible
     stat_created   = 'Created'; stat_created_c = 0
     stat_running   = 'Running'; stat_running_c = 1
     stat_completed = 'Completed'; stat_completed_c = 2
     stat_dead      = 'Dead (Exception), call job.traceback() for details'
     stat_dead_c = -1
 
     def __init__(self):
         raise NotImplementedError, \
               "This class can not be instantiated directly."
 
     def _init(self):
         """Common initialization for all BackgroundJob objects"""
         
         for attr in ['call','strform']:
             assert hasattr(self,attr), "Missing attribute <%s>" % attr
         
         # The num tag can be set by an external job manager
         self.num = None
       
         self.status    = BackgroundJobBase.stat_created
         self.stat_code = BackgroundJobBase.stat_created_c
         self.finished  = False
         self.result    = '<BackgroundJob has not completed>'
         # reuse the ipython traceback handler if we can get to it, otherwise
         # make a new one
         try:
             self._make_tb = __IPYTHON__.InteractiveTB.text
         except:
             self._make_tb = AutoFormattedTB(mode = 'Context',
                                            color_scheme='NoColor',
                                            tb_offset = 1).text
         # Hold a formatted traceback if one is generated.
         self._tb = None
         
         threading.Thread.__init__(self)
 
     def __str__(self):
         return self.strform
 
     def __repr__(self):
         return '<BackgroundJob: %s>' % self.strform
 
     def traceback(self):
         print self._tb
         
     def run(self):
         try:
             self.status    = BackgroundJobBase.stat_running
             self.stat_code = BackgroundJobBase.stat_running_c
             self.result    = self.call()
         except:
             self.status    = BackgroundJobBase.stat_dead
             self.stat_code = BackgroundJobBase.stat_dead_c
             self.finished  = None
             self.result    = ('<BackgroundJob died, call job.traceback() for details>')
             self._tb       = self._make_tb()
         else:
             self.status    = BackgroundJobBase.stat_completed
             self.stat_code = BackgroundJobBase.stat_completed_c
             self.finished  = True
 
 class BackgroundJobExpr(BackgroundJobBase):
     """Evaluate an expression as a background job (uses a separate thread)."""
 
     def __init__(self,expression,glob=None,loc=None):
         """Create a new job from a string which can be fed to eval().
 
         global/locals dicts can be provided, which will be passed to the eval
         call."""
 
         # fail immediately if the given expression can't be compiled
         self.code = compile(expression,'<BackgroundJob compilation>','eval')
                 
         if glob is None:
             glob = {}
         if loc is None:
             loc = {}
             
         self.expression = self.strform = expression
         self.glob = glob
         self.loc = loc
         self._init()
         
     def call(self):
         return eval(self.code,self.glob,self.loc)
 
 class BackgroundJobFunc(BackgroundJobBase):
     """Run a function call as a background job (uses a separate thread)."""
 
     def __init__(self,func,*args,**kwargs):
         """Create a new job from a callable object.
 
         Any positional arguments and keyword args given to this constructor
         after the initial callable are passed directly to it."""
 
         assert callable(func),'first argument must be callable'
         
         if args is None:
             args = []
         if kwargs is None:
             kwargs = {}
         
         self.func = func
         self.args = args
         self.kwargs = kwargs
         # The string form will only include the function passed, because
         # generating string representations of the arguments is a potentially
         # _very_ expensive operation (e.g. with large arrays).
         self.strform = str(func)
         self._init()
 
     def call(self):
         return self.func(*self.args,**self.kwargs)
 
 
 if __name__=='__main__':
 
     import time
 
     def sleepfunc(interval=2,*a,**kw):
         args = dict(interval=interval,
                     args=a,
                     kwargs=kw)
         time.sleep(interval)
         return args
 
     def diefunc(interval=2,*a,**kw):
         time.sleep(interval)
         die
 
     def printfunc(interval=1,reps=5):
         for n in range(reps):
             time.sleep(interval)
             print 'In the background...'
 
     jobs = BackgroundJobManager()
     # first job will have # 0
     jobs.new(sleepfunc,4)
     jobs.new(sleepfunc,kw={'reps':2})
     # This makes a job which will die
     jobs.new(diefunc,1)
     jobs.new('printfunc(1,3)')
 
     # after a while, you can get the traceback of a dead job.  Run the line
     # below again interactively until it prints a traceback (check the status
     # of the job):
     print jobs[1].status
     jobs[1].traceback()
     
     # Run this line again until the printed result changes
     print "The result of job #0 is:",jobs[0].result

IPython/completer.py

@@ -1,556 +1,556 b''
 """Word completion for IPython.
 
 This module is a fork of the rlcompleter module in the Python standard
 library.  The original enhancements made to rlcompleter have been sent
 upstream and were accepted as of Python 2.3, but we need a lot more
 functionality specific to IPython, so this module will continue to live as an
 IPython-specific utility.
 
 ---------------------------------------------------------------------------
 Original rlcompleter documentation:
 
 This requires the latest extension to the readline module (the
 completes keywords, built-ins and globals in __main__; when completing
 NAME.NAME..., it evaluates (!) the expression up to the last dot and
 completes its attributes.
 
 It's very cool to do "import string" type "string.", hit the
 completion key (twice), and see the list of names defined by the
 string module!
 
 Tip: to use the tab key as the completion key, call
 
     readline.parse_and_bind("tab: complete")
 
 Notes:
 
 - Exceptions raised by the completer function are *ignored* (and
 generally cause the completion to fail).  This is a feature -- since
 readline sets the tty device in raw (or cbreak) mode, printing a
 traceback wouldn't work well without some complicated hoopla to save,
 reset and restore the tty state.
 
 - The evaluation of the NAME.NAME... form may cause arbitrary
 application defined code to be executed if an object with a
 __getattr__ hook is found.  Since it is the responsibility of the
 application (or the user) to enable this feature, I consider this an
 acceptable risk.  More complicated expressions (e.g. function calls or
 indexing operations) are *not* evaluated.
 
 - GNU readline is also used by the built-in functions input() and
 raw_input(), and thus these also benefit/suffer from the completer
 features.  Clearly an interactive application can benefit by
 specifying its own completer function and using raw_input() for all
 its input.
 
 - When the original stdin is not a tty device, GNU readline is never
 used, and this module (and the readline module) are silently inactive.
 
 """
 
 #*****************************************************************************
 #
 # Since this file is essentially a minimally modified copy of the rlcompleter
 # module which is part of the standard Python distribution, I assume that the
 # proper procedure is to maintain its copyright as belonging to the Python
 # Software Foundation (in addition to my own, for all new code).
 #
 #       Copyright (C) 2001 Python Software Foundation, www.python.org
-#       Copyright (C) 2001-2005 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #
 #*****************************************************************************
 
 import __builtin__
 import __main__
 import glob
 import keyword
 import os
 import re
 import readline
 import sys
 import types
 
 # Python 2.4 offers sets as a builtin
 try:
     set([1,2])
 except NameError:
     from sets import Set as set
 
 
 from IPython.genutils import shlex_split
 
 __all__ = ['Completer','IPCompleter']
 
 def get_class_members(cls):
     ret = dir(cls)
     if hasattr(cls,'__bases__'):
         for base in cls.__bases__:
             ret.extend(get_class_members(base))
     return ret
 
 class Completer:
     def __init__(self,namespace=None,global_namespace=None):
         """Create a new completer for the command line.
 
         Completer([namespace,global_namespace]) -> completer instance.
 
         If unspecified, the default namespace where completions are performed
         is __main__ (technically, __main__.__dict__). Namespaces should be
         given as dictionaries.
 
         An optional second namespace can be given.  This allows the completer
         to handle cases where both the local and global scopes need to be
         distinguished.
 
         Completer instances should be used as the completion mechanism of
         readline via the set_completer() call:
 
         readline.set_completer(Completer(my_namespace).complete)
         """
 
         # some minimal strict typechecks.  For some core data structures, I
         # want actual basic python types, not just anything that looks like
         # one.  This is especially true for namespaces.
         for ns in (namespace,global_namespace):
             if ns is not None and type(ns) != types.DictType:
                 raise TypeError,'namespace must be a dictionary'
 
         # Don't bind to namespace quite yet, but flag whether the user wants a
         # specific namespace or to use __main__.__dict__. This will allow us
         # to bind to __main__.__dict__ at completion time, not now.
         if namespace is None:
             self.use_main_ns = 1
         else:
             self.use_main_ns = 0
             self.namespace = namespace
 
         # The global namespace, if given, can be bound directly
         if global_namespace is None:
             self.global_namespace = {}
         else:
             self.global_namespace = global_namespace
 
     def complete(self, text, state):
         """Return the next possible completion for 'text'.
 
         This is called successively with state == 0, 1, 2, ... until it
         returns None.  The completion should begin with 'text'.
 
         """
         if self.use_main_ns:
             self.namespace = __main__.__dict__
             
         if state == 0:
             if "." in text:
                 self.matches = self.attr_matches(text)
             else:
                 self.matches = self.global_matches(text)
         try:
             return self.matches[state]
         except IndexError:
             return None
 
     def global_matches(self, text):
         """Compute matches when text is a simple name.
 
         Return a list of all keywords, built-in functions and names currently
         defined in self.namespace or self.global_namespace that match.
 
         """
         matches = []
         match_append = matches.append
         n = len(text)
         for lst in [keyword.kwlist,
                     __builtin__.__dict__.keys(),
                     self.namespace.keys(),
                     self.global_namespace.keys()]:
             for word in lst:
                 if word[:n] == text and word != "__builtins__":
                     match_append(word)
         return matches
 
     def attr_matches(self, text):
         """Compute matches when text contains a dot.
 
         Assuming the text is of the form NAME.NAME....[NAME], and is
         evaluatable in self.namespace or self.global_namespace, it will be
         evaluated and its attributes (as revealed by dir()) are used as
         possible completions.  (For class instances, class members are are
         also considered.)
 
         WARNING: this can still invoke arbitrary C code, if an object
         with a __getattr__ hook is evaluated.
 
         """
         import re
 
         # Another option, seems to work great. Catches things like ''.<tab>
         m = re.match(r"(\S+(\.\w+)*)\.(\w*)$", text)
 
         if not m:
             return []
         
         expr, attr = m.group(1, 3)
         try:
             object = eval(expr, self.namespace)
         except:
             object = eval(expr, self.global_namespace)
 
         # Start building the attribute list via dir(), and then complete it
         # with a few extra special-purpose calls.
         words = dir(object)
 
         if hasattr(object,'__class__'):
             words.append('__class__')
             words.extend(get_class_members(object.__class__))
 
         # this is the 'dir' function for objects with Enthought's traits
         if hasattr(object, 'trait_names'):
             words.extend(object.trait_names())
             # eliminate possible duplicates, as some traits may also appear as
             # normal attributes in the dir() call.
             words = set(words)
 
         # filter out non-string attributes which may be stuffed by dir() calls
         # and poor coding in third-party modules
         words = [w for w in words
                  if isinstance(w, basestring) and w != "__builtins__"]
         # Build match list to return
         n = len(attr)
         return ["%s.%s" % (expr, w) for w in words if w[:n] == attr ]
 
 class IPCompleter(Completer):
     """Extension of the completer class with IPython-specific features"""
 
     def __init__(self,shell,namespace=None,global_namespace=None,
                  omit__names=0,alias_table=None):
         """IPCompleter() -> completer
 
         Return a completer object suitable for use by the readline library
         via readline.set_completer().
 
         Inputs:
 
         - shell: a pointer to the ipython shell itself.  This is needed
         because this completer knows about magic functions, and those can
         only be accessed via the ipython instance.
 
         - namespace: an optional dict where completions are performed.
 
         - global_namespace: secondary optional dict for completions, to
         handle cases (such as IPython embedded inside functions) where
         both Python scopes are visible.
 
         - The optional omit__names parameter sets the completer to omit the
         'magic' names (__magicname__) for python objects unless the text
         to be completed explicitly starts with one or more underscores.
 
         - If alias_table is supplied, it should be a dictionary of aliases
         to complete. """
 
         Completer.__init__(self,namespace,global_namespace)
         self.magic_prefix = shell.name+'.magic_'
         self.magic_escape = shell.ESC_MAGIC
         self.readline = readline
         delims = self.readline.get_completer_delims()
         delims = delims.replace(self.magic_escape,'')
         self.readline.set_completer_delims(delims)
         self.get_line_buffer = self.readline.get_line_buffer
         self.omit__names = omit__names
         self.merge_completions = shell.rc.readline_merge_completions
 
         if alias_table is None:
             alias_table = {}
         self.alias_table = alias_table
         # Regexp to split filenames with spaces in them
         self.space_name_re = re.compile(r'([^\\] )')
         # Hold a local ref. to glob.glob for speed
         self.glob = glob.glob
 
         # Determine if we are running on 'dumb' terminals, like (X)Emacs
         # buffers, to avoid completion problems.
         term = os.environ.get('TERM','xterm')
         self.dumb_terminal = term in ['dumb','emacs']
         
         # Special handling of backslashes needed in win32 platforms
         if sys.platform == "win32":
             self.clean_glob = self._clean_glob_win32
         else:
             self.clean_glob = self._clean_glob
         self.matchers = [self.python_matches,
                          self.file_matches,
                          self.alias_matches,
                          self.python_func_kw_matches]
 
     # Code contributed by Alex Schmolck, for ipython/emacs integration
     def all_completions(self, text):
         """Return all possible completions for the benefit of emacs."""
 
         completions = []
         comp_append = completions.append
         try:
             for i in xrange(sys.maxint):
                 res = self.complete(text, i)
 
                 if not res: break
 
                 comp_append(res)
         #XXX workaround for ``notDefined.<tab>``
         except NameError:
             pass
         return completions
     # /end Alex Schmolck code.
 
     def _clean_glob(self,text):
         return self.glob("%s*" % text)
 
     def _clean_glob_win32(self,text):
         return [f.replace("\\","/")
                 for f in self.glob("%s*" % text)]            
 
     def file_matches(self, text):
         """Match filneames, expanding ~USER type strings.
 
         Most of the seemingly convoluted logic in this completer is an
         attempt to handle filenames with spaces in them.  And yet it's not
         quite perfect, because Python's readline doesn't expose all of the
         GNU readline details needed for this to be done correctly.
 
         For a filename with a space in it, the printed completions will be
         only the parts after what's already been typed (instead of the
         full completions, as is normally done).  I don't think with the
         current (as of Python 2.3) Python readline it's possible to do
         better."""
 
         #print 'Completer->file_matches: <%s>' % text # dbg
 
         # chars that require escaping with backslash - i.e. chars
         # that readline treats incorrectly as delimiters, but we
         # don't want to treat as delimiters in filename matching
         # when escaped with backslash
 
         protectables = ' ()[]{}'
 
         def protect_filename(s):
             return "".join([(ch in protectables and '\\' + ch or ch)
                             for ch in s])
 
         lbuf = self.get_line_buffer()[:self.readline.get_endidx()]
         open_quotes = 0  # track strings with open quotes
         try:
             lsplit = shlex_split(lbuf)[-1]
         except ValueError:
             # typically an unmatched ", or backslash without escaped char.
             if lbuf.count('"')==1:
                 open_quotes = 1
                 lsplit = lbuf.split('"')[-1]
             elif lbuf.count("'")==1:
                 open_quotes = 1
                 lsplit = lbuf.split("'")[-1]
             else:
                 return None
         except IndexError:
             # tab pressed on empty line
             lsplit = ""
 
         if lsplit != protect_filename(lsplit):
             # if protectables are found, do matching on the whole escaped
             # name
             has_protectables = 1
             text0,text = text,lsplit
         else:
             has_protectables = 0
             text = os.path.expanduser(text)
 
         if text == "":
             return [protect_filename(f) for f in self.glob("*")]
 
         m0 = self.clean_glob(text.replace('\\',''))
         if has_protectables:
             # If we had protectables, we need to revert our changes to the
             # beginning of filename so that we don't double-write the part
             # of the filename we have so far
             len_lsplit = len(lsplit)
             matches = [text0 + protect_filename(f[len_lsplit:]) for f in m0]
         else:
             if open_quotes:
                 # if we have a string with an open quote, we don't need to
                 # protect the names at all (and we _shouldn't_, as it
                 # would cause bugs when the filesystem call is made).
                 matches = m0
             else:
                 matches = [protect_filename(f) for f in m0]
         if len(matches) == 1 and os.path.isdir(matches[0]):
             # Takes care of links to directories also.  Use '/'
             # explicitly, even under Windows, so that name completions
             # don't end up escaped.
             matches[0] += '/'
         return matches
 
     def alias_matches(self, text):
         """Match internal system aliases"""
         #print 'Completer->alias_matches:',text # dbg
         text = os.path.expanduser(text)
         aliases =  self.alias_table.keys()
         if text == "":
             return aliases
         else:
             return [alias for alias in aliases if alias.startswith(text)]
 
     def python_matches(self,text):
         """Match attributes or global python names"""
         #print 'Completer->python_matches' # dbg
         if "." in text:
             try:
                 matches = self.attr_matches(text)
                 if text.endswith('.') and self.omit__names:
                     if self.omit__names == 1:
                         # true if txt is _not_ a __ name, false otherwise:
                         no__name = (lambda txt:
                                     re.match(r'.*\.__.*?__',txt) is None)
                     else:
                         # true if txt is _not_ a _ name, false otherwise:
                         no__name = (lambda txt:
                                     re.match(r'.*\._.*?',txt) is None)
                     matches = filter(no__name, matches)
             except NameError:
                 # catches <undefined attributes>.<tab>
                 matches = []
         else:
             matches = self.global_matches(text)
             # this is so completion finds magics when automagic is on:
             if matches == [] and not text.startswith(os.sep):
                 matches = self.attr_matches(self.magic_prefix+text)
         return matches
 
     def _default_arguments(self, obj):
         """Return the list of default arguments of obj if it is callable,
         or empty list otherwise."""
 
         if not (inspect.isfunction(obj) or inspect.ismethod(obj)):
             # for classes, check for __init__,__new__
             if inspect.isclass(obj):
                 obj = (getattr(obj,'__init__',None) or
                        getattr(obj,'__new__',None))
             # for all others, check if they are __call__able
             elif hasattr(obj, '__call__'):
                 obj = obj.__call__
             # XXX: is there a way to handle the builtins ?
         try:
             args,_,_1,defaults = inspect.getargspec(obj)
             if defaults:
                 return args[-len(defaults):]
         except TypeError: pass
         return []
 
     def python_func_kw_matches(self,text):
         """Match named parameters (kwargs) of the last open function"""
 
         if "." in text: # a parameter cannot be dotted
             return []
         try: regexp = self.__funcParamsRegex
         except AttributeError:
             regexp = self.__funcParamsRegex = re.compile(r'''
                 '.*?' |    # single quoted strings or
                 ".*?" |    # double quoted strings or
                 \w+   |    # identifier
                 \S         # other characters
                 ''', re.VERBOSE | re.DOTALL)
         # 1. find the nearest identifier that comes before an unclosed
         # parenthesis e.g. for "foo (1+bar(x), pa", the candidate is "foo"
         tokens = regexp.findall(self.get_line_buffer())
         tokens.reverse()
         iterTokens = iter(tokens); openPar = 0
         for token in iterTokens:
             if token == ')':
                 openPar -= 1
             elif token == '(':
                 openPar += 1
                 if openPar > 0:
                     # found the last unclosed parenthesis
                     break
         else:
             return []
         # 2. Concatenate dotted names ("foo.bar" for "foo.bar(x, pa" )
         ids = []
         isId = re.compile(r'\w+$').match
         while True:
             try:
                 ids.append(iterTokens.next())
                 if not isId(ids[-1]):
                     ids.pop(); break
                 if not iterTokens.next() == '.':
                     break
             except StopIteration:
                 break
         # lookup the candidate callable matches either using global_matches
         # or attr_matches for dotted names
         if len(ids) == 1:
             callableMatches = self.global_matches(ids[0])
         else:
             callableMatches = self.attr_matches('.'.join(ids[::-1]))
         argMatches = []
         for callableMatch in callableMatches:
             try: namedArgs = self._default_arguments(eval(callableMatch,
                                                          self.namespace))
             except: continue
             for namedArg in namedArgs:
                 if namedArg.startswith(text):
                     argMatches.append("%s=" %namedArg)
         return argMatches
 
     def complete(self, text, state):
         """Return the next possible completion for 'text'.
 
         This is called successively with state == 0, 1, 2, ... until it
         returns None.  The completion should begin with 'text'.  """
 
         #print '\n*** COMPLETE: <%s> (%s)' % (text,state)  # dbg
 
         # if there is only a tab on a line with only whitespace, instead
         # of the mostly useless 'do you want to see all million
         # completions' message, just do the right thing and give the user
         # his tab!  Incidentally, this enables pasting of tabbed text from
         # an editor (as long as autoindent is off).
 
         # don't apply this on 'dumb' terminals, such as emacs buffers, so we
         # don't interfere with their own tab-completion mechanism.
         if not (self.dumb_terminal or self.get_line_buffer().strip()):
             self.readline.insert_text('\t')
             return None
 
         magic_escape = self.magic_escape
         magic_prefix = self.magic_prefix
 
         try:
             if text.startswith(magic_escape):
                 text = text.replace(magic_escape,magic_prefix)
             elif text.startswith('~'):
                 text = os.path.expanduser(text)
             if state == 0:
                 # Extend the list of completions with the results of each
                 # matcher, so we return results to the user from all
                 # namespaces.
                 if self.merge_completions:
                     self.matches = []
                     for matcher in self.matchers:
                         self.matches.extend(matcher(text))
                 else:
                     for matcher in self.matchers:
                         self.matches = matcher(text)
                         if self.matches:
                             break
 
             try:
                 return self.matches[state].replace(magic_prefix,magic_escape)
             except IndexError:
                 return None
         except:
             #from IPython.ultraTB import AutoFormattedTB; # dbg
             #tb=AutoFormattedTB('Verbose');tb() #dbg
 
             # If completion fails, don't annoy the user.
             return None

IPython/demo.py

@@ -1,309 +1,309 b''
 """Module for interactive demos using IPython.
 
 This module implements a single class, Demo, for running Python scripts
 interactively in IPython for demonstrations.  With very simple markup (a few
 tags in comments), you can control points where the script stops executing and
 returns control to IPython.
 
 The file is run in its own empty namespace (though you can pass it a string of
 arguments as if in a command line environment, and it will see those as
 sys.argv).  But at each stop, the global IPython namespace is updated with the
 current internal demo namespace, so you can work interactively with the data
 accumulated so far.
 
 By default, each block of code is printed (with syntax highlighting) before
 executing it and you have to confirm execution.  This is intended to show the
 code to an audience first so you can discuss it, and only proceed with
 execution once you agree.  There are a few tags which allow you to modify this
 behavior.
 
 The supported tags are:
 
 # <demo> --- stop ---
 
   Defines block boundaries, the points where IPython stops execution of the
   file and returns to the interactive prompt.
 
 # <demo> silent
 
   Make a block execute silently (and hence automatically).  Typically used in
   cases where you have some boilerplate or initialization code which you need
   executed but do not want to be seen in the demo.
   
 # <demo> auto
 
   Make a block execute automatically, but still being printed.  Useful for
   simple code which does not warrant discussion, since it avoids the extra
   manual confirmation.
 
 # <demo> auto_all
 
   This tag can _only_ be in the first block, and if given it overrides the
   individual auto tags to make the whole demo fully automatic (no block asks
   for confirmation).  It can also be given at creation time (or the attribute
   set later) to override what's in the file.
 
 While _any_ python file can be run as a Demo instance, if there are no stop
 tags the whole file will run in a single block (no different that calling
 first %pycat and then %run).  The minimal markup to make this useful is to
 place a set of stop tags; the other tags are only there to let you fine-tune
 the execution.
 
 This is probably best explained with the simple example file below.  You can
 copy this into a file named ex_demo.py, and try running it via:
 
 from IPython.demo import Demo
 d = Demo('ex_demo.py')
 d()  <--- Call the d object (omit the parens if you have autocall on).
 
 Each time you call the demo object, it runs the next block.  The demo object
 has a few useful methods for navigation, like again(), jump(), seek() and
 back().  It can be reset for a new run via reset() or reloaded from disk (in
 case you've edited the source) via reload().  See their docstrings below.
 
 #################### EXAMPLE DEMO <ex_demo.py> ###############################
 '''A simple interactive demo to illustrate the use of IPython's Demo class.'''
 
 print 'Hello, welcome to an interactive IPython demo.'
 
 # The mark below defines a block boundary, which is a point where IPython will
 # stop execution and return to the interactive prompt.
 # Note that in actual interactive execution, 
 # <demo> --- stop ---
 
 x = 1
 y = 2
 
 # <demo> --- stop ---
 
 # the mark below makes this block as silent
 # <demo> silent
 
 print 'This is a silent block, which gets executed but not printed.'
 
 # <demo> --- stop ---
 # <demo> auto
 print 'This is an automatic block.'
 print 'It is executed without asking for confirmation, but printed.'
 z = x+y
 
 print 'z=',x
 
 # <demo> --- stop ---
 # This is just another normal block.
 print 'z is now:', z
 
 print 'bye!'
 ################### END EXAMPLE DEMO <ex_demo.py> ############################
 
 WARNING: this module uses Python 2.3 features, so it won't work in 2.2
 environments.
 """
 #*****************************************************************************
-#       Copyright (C) 2005 Fernando Perez. <[e-mail]>
+#     Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #
 #*****************************************************************************
 
 import exceptions
 import re
 import sys
 
 from IPython.PyColorize import Parser
 from IPython.genutils import marquee, shlex_split, file_read
 
 __all__ = ['Demo','DemoError']
 
 class DemoError(exceptions.Exception): pass
 
 def re_mark(mark):
     return re.compile(r'^\s*#\s+<demo>\s+%s\s*$' % mark,re.MULTILINE)
 
 class Demo:
 
     re_stop     = re_mark('---\s?stop\s?---')
     re_silent   = re_mark('silent')
     re_auto     = re_mark('auto')
     re_auto_all = re_mark('auto_all')
 
     def __init__(self,fname,arg_str='',auto_all=None):
         """Make a new demo object.  To run the demo, simply call the object.
 
         See the module docstring for full details and an example (you can use
         IPython.Demo? in IPython to see it).
 
         Inputs:
         
           - fname = filename.
 
         Optional inputs:
 
           - arg_str(''): a string of arguments, internally converted to a list
           just like sys.argv, so the demo script can see a similar
           environment.
 
           - auto_all(None): global flag to run all blocks automatically without
           confirmation.  This attribute overrides the block-level tags and
           applies to the whole demo.  It is an attribute of the object, and
           can be changed at runtime simply by reassigning it to a boolean
           value.
           """
 
         self.fname    = fname
         self.sys_argv = [fname] + shlex_split(arg_str)
         self.auto_all = auto_all
         
         # get a few things from ipython.  While it's a bit ugly design-wise,
         # it ensures that things like color scheme and the like are always in
         # sync with the ipython mode being used.  This class is only meant to
         # be used inside ipython anyways,  so it's OK.
         self.ip_showtb   = __IPYTHON__.showtraceback
         self.ip_ns       = __IPYTHON__.user_ns
         self.ip_colorize = __IPYTHON__.pycolorize
 
         # load user data and initialize data structures
         self.reload()
 
     def reload(self):
         """Reload source from disk and initialize state."""
         # read data and parse into blocks
         self.src     = file_read(self.fname)
         src_b        = [b.strip() for b in self.re_stop.split(self.src) if b]
         self._silent = [bool(self.re_silent.findall(b)) for b in src_b]
         self._auto   = [bool(self.re_auto.findall(b)) for b in src_b]
 
         # if auto_all is not given (def. None), we read it from the file
         if self.auto_all is None:
             self.auto_all = bool(self.re_auto_all.findall(src_b[0]))
         else:
             self.auto_all = bool(self.auto_all)
 
         # Clean the sources from all markup so it doesn't get displayed when
         # running the demo
         src_blocks = []
         auto_strip = lambda s: self.re_auto.sub('',s)
         for i,b in enumerate(src_b):
             if self._auto[i]:
                 src_blocks.append(auto_strip(b))
             else:
                 src_blocks.append(b)
         # remove the auto_all marker
         src_blocks[0] = self.re_auto_all.sub('',src_blocks[0])
 
         self.nblocks = len(src_blocks)
         self.src_blocks = src_blocks
 
         # also build syntax-highlighted source
         self.src_blocks_colored = map(self.ip_colorize,self.src_blocks)
 
         # ensure clean namespace and seek offset
         self.reset()
 
     def reset(self):
         """Reset the namespace and seek pointer to restart the demo"""
         self.user_ns     = {}
         self.finished    = False
         self.block_index = 0
 
     def _validate_index(self,index):
         if index<0 or index>=self.nblocks:
             raise ValueError('invalid block index %s' % index)
 
     def seek(self,index):
         """Move the current seek pointer to the given block"""
         self._validate_index(index)
         self.block_index = index
         self.finished = False
 
     def back(self,num=1):
         """Move the seek pointer back num blocks (default is 1)."""
         self.seek(self.block_index-num)
 
     def jump(self,num):
         """Jump a given number of blocks relative to the current one."""
         self.seek(self.block_index+num)
 
     def again(self):
         """Move the seek pointer back one block and re-execute."""
         self.back(1)
         self()
 
     def show(self,index=None):
         """Show a single block on screen"""
         if index is None:
             if self.finished:
                 print 'Demo finished.  Use reset() if you want to rerun it.'
                 return
             index = self.block_index
         else:
             self._validate_index(index)
         print marquee('<%s> block # %s (%s remaining)' %
                       (self.fname,index,self.nblocks-index-1))
         print self.src_blocks_colored[index],
 
     def show_all(self):
         """Show entire demo on screen, block by block"""
 
         fname = self.fname
         nblocks = self.nblocks
         silent = self._silent
         for index,block in enumerate(self.src_blocks_colored):
             if silent[index]:
                 print marquee('<%s> SILENT block # %s (%s remaining)' %
                               (fname,index,nblocks-index-1))
             else:
                 print marquee('<%s> block # %s (%s remaining)' %
                               (fname,index,nblocks-index-1))
             print block,
             
     def __call__(self,index=None):
         """run a block of the demo.
 
         If index is given, it should be an integer >=1 and <= nblocks.  This
         means that the calling convention is one off from typical Python
         lists.  The reason for the inconsistency is that the demo always
         prints 'Block n/N, and N is the total, so it would be very odd to use
         zero-indexing here."""
 
         if index is None and self.finished:
             print 'Demo finished.  Use reset() if you want to rerun it.'
             return
         if index is None:
             index = self.block_index
         self._validate_index(index)
         try:
             next_block = self.src_blocks[index]
             self.block_index += 1
             if self._silent[index]:
                 print marquee('Executing silent block # %s (%s remaining)' %
                               (index,self.nblocks-index-1))
             else:
                 self.show(index)
                 if self.auto_all or self._auto[index]:
                     print marquee('output')
                 else:
                     print marquee('Press <q> to quit, <Enter> to execute...'),
                     ans = raw_input().strip()
                     if ans:
                         print marquee('Block NOT executed')
                         return
             try:
                 save_argv = sys.argv
                 sys.argv = self.sys_argv
                 exec next_block in self.user_ns
             finally:
                 sys.argv = save_argv
             
         except:
             self.ip_showtb(filename=self.fname)
         else:
             self.ip_ns.update(self.user_ns)
 
         if self.block_index == self.nblocks:
             print
             print marquee(' END OF DEMO ')
             print marquee('Use reset() if you want to rerun it.')
             self.finished = True
 

IPython/excolors.py

@@ -1,109 +1,109 b''
 # -*- coding: utf-8 -*-
 """
 Color schemes for exception handling code in IPython.
 
 $Id: Prompts.py 638 2005-07-18 03:01:41Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2005 Fernando Perez <[e-mail]>
+#       Copyright (C) 2005-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 __version__ = Release.version
 
 #****************************************************************************
 # Required modules
 from IPython.ColorANSI import ColorSchemeTable, TermColors, ColorScheme
 
 ExceptionColors = ColorSchemeTable()
 
 # Populate it with color schemes
 C = TermColors # shorthand and local lookup
 ExceptionColors.add_scheme(ColorScheme(
     'NoColor',
     # The color to be used for the top line
     topline = C.NoColor,
 
     # The colors to be used in the traceback
     filename = C.NoColor,
     lineno = C.NoColor,
     name = C.NoColor,
     vName = C.NoColor,
     val = C.NoColor,
     em = C.NoColor,
     
     # Emphasized colors for the last frame of the traceback
     normalEm = C.NoColor,
     filenameEm = C.NoColor,
     linenoEm = C.NoColor,
     nameEm = C.NoColor,
     valEm = C.NoColor,
     
     # Colors for printing the exception
     excName = C.NoColor,
     line = C.NoColor,
     caret = C.NoColor,
     Normal = C.NoColor
     ))
 
 # make some schemes as instances so we can copy them for modification easily
 ExceptionColors.add_scheme(ColorScheme(
     'Linux',
     # The color to be used for the top line
     topline = C.LightRed,
 
     # The colors to be used in the traceback
     filename = C.Green,
     lineno = C.Green,
     name = C.Purple,
     vName = C.Cyan,
     val = C.Green,
     em = C.LightCyan,
 
     # Emphasized colors for the last frame of the traceback
     normalEm = C.LightCyan,
     filenameEm = C.LightGreen,
     linenoEm = C.LightGreen,
     nameEm = C.LightPurple,
     valEm = C.LightBlue,
 
     # Colors for printing the exception
     excName = C.LightRed,
     line = C.Yellow,
     caret = C.White,
     Normal = C.Normal
     ))
 
 # For light backgrounds, swap dark/light colors
 ExceptionColors.add_scheme(ColorScheme(
     'LightBG',
     # The color to be used for the top line
     topline = C.Red,
     
     # The colors to be used in the traceback
     filename = C.LightGreen,
     lineno = C.LightGreen,
     name = C.LightPurple,
     vName = C.Cyan,
     val = C.LightGreen,
     em = C.Cyan,
 
     # Emphasized colors for the last frame of the traceback
     normalEm = C.Cyan,
     filenameEm = C.Green,
     linenoEm = C.Green,
     nameEm = C.Purple,
     valEm = C.Blue,
 
     # Colors for printing the exception
     excName = C.Red,
     #line = C.Brown,  # brown often is displayed as yellow
     line = C.Red,
     caret = C.Normal,
     Normal = C.Normal
     ))

IPython/genutils.py

@@ -1,1717 +1,1717 b''
 # -*- coding: utf-8 -*-
 """
 General purpose utilities.
 
 This is a grab-bag of stuff I find useful in most programs I write. Some of
 these things are also convenient when working at the command line.
 
-$Id: genutils.py 990 2006-01-04 06:59:02Z fperez $"""
+$Id: genutils.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from __future__ import generators # 2.2 compatibility
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 #****************************************************************************
 # required modules from the Python standard library
 import __main__
 import commands
 import os
 import re
 import shlex
 import shutil
 import sys
 import tempfile
 import time
 import types
 
 # Other IPython utilities
 from IPython.Itpl import Itpl,itpl,printpl
 from IPython import DPyGetOpt
 
 if os.name == "nt":
     from IPython.winconsole import get_console_size
 
 # Build objects which appeared in Python 2.3 for 2.2, to make ipython
 # 2.2-friendly
 try:
     basestring
 except NameError:
     import types
     basestring = (types.StringType, types.UnicodeType)
     True = 1==1
     False = 1==0
 
     def enumerate(obj):
         i = -1
         for item in obj:
             i += 1
             yield i, item
 
     # add these to the builtin namespace, so that all modules find them
     import __builtin__
     __builtin__.basestring = basestring
     __builtin__.True = True
     __builtin__.False = False
     __builtin__.enumerate = enumerate
 
 # Try to use shlex.split for converting an input string into a sys.argv-type
 # list.  This appeared in Python 2.3, so here's a quick backport for 2.2.
 try:
     shlex_split = shlex.split
 except AttributeError:
     _quotesre = re.compile(r'[\'"](.*)[\'"]')
     _wordchars = ('abcdfeghijklmnopqrstuvwxyz'
                   'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.~*?'
                   'ßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ'
                   'ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ%s'
                   % os.sep)
     
     def shlex_split(s):
         """Simplified backport to Python 2.2 of shlex.split().
 
         This is a quick and dirty hack, since the shlex module under 2.2 lacks
         several of the features needed to really match the functionality of
         shlex.split() in 2.3."""
 
         lex = shlex.shlex(StringIO(s))
         # Try to get options, extensions and path separators as characters
         lex.wordchars = _wordchars
         lex.commenters = ''
         # Make a list out of the lexer by hand, since in 2.2 it's not an
         # iterator.
         lout = []
         while 1:
             token = lex.get_token()
             if token == '':
                 break
             # Try to handle quoted tokens correctly
             quotes = _quotesre.match(token)
             if quotes:
                 token = quotes.group(1)
             lout.append(token)
         return lout
 
 #****************************************************************************
 # Exceptions
 class Error(Exception):
     """Base class for exceptions in this module."""
     pass
 
 #----------------------------------------------------------------------------
 class IOStream:
     def __init__(self,stream,fallback):
         if not hasattr(stream,'write') or not hasattr(stream,'flush'):
             stream = fallback
         self.stream = stream
         self._swrite = stream.write
         self.flush = stream.flush
 
     def write(self,data):
         try:
             self._swrite(data)
         except:
             try:
                 # print handles some unicode issues which may trip a plain
                 # write() call.  Attempt to emulate write() by using a
                 # trailing comma
                 print >> self.stream, data,
             except:
                 # if we get here, something is seriously broken.
                 print >> sys.stderr, \
                       'ERROR - failed to write data to stream:', stream
         
 class IOTerm:
     """ Term holds the file or file-like objects for handling I/O operations.
 
     These are normally just sys.stdin, sys.stdout and sys.stderr but for
     Windows they can can replaced to allow editing the strings before they are
     displayed."""
 
     # In the future, having IPython channel all its I/O operations through
     # this class will make it easier to embed it into other environments which
     # are not a normal terminal (such as a GUI-based shell)
     def __init__(self,cin=None,cout=None,cerr=None):
         self.cin  = IOStream(cin,sys.stdin)
         self.cout = IOStream(cout,sys.stdout)
         self.cerr = IOStream(cerr,sys.stderr)
         
 # Global variable to be used for all I/O
 Term = IOTerm()
 
 # Windows-specific code to load Gary Bishop's readline and configure it
 # automatically for the users
 # Note: os.name on cygwin returns posix, so this should only pick up 'native'
 # windows.  Cygwin returns 'cygwin' for sys.platform.
 if os.name == 'nt':
     try:
         import readline
     except ImportError:
         pass
     else:
         try:
             _out = readline.GetOutputFile()
         except AttributeError:
             pass
         else:
             # Remake Term to use the readline i/o facilities
             Term = IOTerm(cout=_out,cerr=_out)
             del _out
 
 #****************************************************************************
 # Generic warning/error printer, used by everything else
 def warn(msg,level=2,exit_val=1):
     """Standard warning printer. Gives formatting consistency.
 
     Output is sent to Term.cerr (sys.stderr by default).
     
     Options:
     
     -level(2): allows finer control:
       0 -> Do nothing, dummy function.
       1 -> Print message.
       2 -> Print 'WARNING:' + message. (Default level).
       3 -> Print 'ERROR:' + message.
       4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
 
     -exit_val (1): exit value returned by sys.exit() for a level 4
     warning. Ignored for all other levels."""
     
     if level>0:
         header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
         print >> Term.cerr, '%s%s' % (header[level],msg)
         if level == 4:
             print >> Term.cerr,'Exiting.\n'
             sys.exit(exit_val)
 
 def info(msg):
     """Equivalent to warn(msg,level=1)."""
 
     warn(msg,level=1)
 
 def error(msg):
     """Equivalent to warn(msg,level=3)."""
 
     warn(msg,level=3)
 
 def fatal(msg,exit_val=1):
     """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
 
     warn(msg,exit_val=exit_val,level=4)
 
 
 # useful for debugging
 def debugp(expr):
     """Print the value of an expression from the caller's frame.
     
     Takes an expression, evaluates it in the caller's frame and prints both
     the given expression and the resulting value.  The input must be of a form
     suitable for eval()."""
     
     cf = sys._getframe(1)
     print '[DBG] %s -> %r' % (expr,eval(expr,cf.f_globals,cf.f_locals))
 
 #----------------------------------------------------------------------------
 StringTypes = types.StringTypes
 
 # Basic timing functionality
 
 # If possible (Unix), use the resource module instead of time.clock()
 try:
     import resource
     def clock():
         """clock() -> floating point number
 
         Return the CPU time in seconds (user time only, system time is
         ignored) since the start of the process.  This is done via a call to
         resource.getrusage, so it avoids the wraparound problems in
         time.clock()."""
         
         return resource.getrusage(resource.RUSAGE_SELF)[0]
     
     def clock2():
         """clock2() -> (t_user,t_system)
 
         Similar to clock(), but return a tuple of user/system times."""
         return resource.getrusage(resource.RUSAGE_SELF)[:2]
 
 except ImportError:
     clock = time.clock
     def clock2():
         """Under windows, system CPU time can't be measured.
 
         This just returns clock() and zero."""
         return time.clock(),0.0
 
 def timings_out(reps,func,*args,**kw):
     """timings_out(reps,func,*args,**kw) -> (t_total,t_per_call,output)
 
     Execute a function reps times, return a tuple with the elapsed total
     CPU time in seconds, the time per call and the function's output.
 
     Under Unix, the return value is the sum of user+system time consumed by
     the process, computed via the resource module.  This prevents problems
     related to the wraparound effect which the time.clock() function has.
     
     Under Windows the return value is in wall clock seconds. See the
     documentation for the time module for more details."""
 
     reps = int(reps)
     assert reps >=1, 'reps must be >= 1'
     if reps==1:
         start = clock()
         out = func(*args,**kw)
         tot_time = clock()-start
     else:
         rng = xrange(reps-1) # the last time is executed separately to store output
         start = clock()
         for dummy in rng: func(*args,**kw)
         out = func(*args,**kw)  # one last time
         tot_time = clock()-start
     av_time = tot_time / reps
     return tot_time,av_time,out
 
 def timings(reps,func,*args,**kw):
     """timings(reps,func,*args,**kw) -> (t_total,t_per_call)
 
     Execute a function reps times, return a tuple with the elapsed total CPU
     time in seconds and the time per call. These are just the first two values
     in timings_out()."""
 
     return timings_out(reps,func,*args,**kw)[0:2]
 
 def timing(func,*args,**kw):
     """timing(func,*args,**kw) -> t_total
 
     Execute a function once, return the elapsed total CPU time in
     seconds. This is just the first value in timings_out()."""
 
     return timings_out(1,func,*args,**kw)[0]
 
 #****************************************************************************
 # file and system
 
 def system(cmd,verbose=0,debug=0,header=''):
     """Execute a system command, return its exit status.
 
     Options:
 
     - verbose (0): print the command to be executed.
     
     - debug (0): only print, do not actually execute.
 
     - header (''): Header to print on screen prior to the executed command (it
     is only prepended to the command, no newlines are added).
 
     Note: a stateful version of this function is available through the
     SystemExec class."""
 
     stat = 0
     if verbose or debug: print header+cmd
     sys.stdout.flush()
     if not debug: stat = os.system(cmd)
     return stat
 
 # This function is used by ipython in a lot of places to make system calls.
 # We need it to be slightly different under win32, due to the vagaries of
 # 'network shares'.  A win32 override is below.
 
 def shell(cmd,verbose=0,debug=0,header=''):
     """Execute a command in the system shell, always return None.
 
     Options:
 
     - verbose (0): print the command to be executed.
     
     - debug (0): only print, do not actually execute.
 
     - header (''): Header to print on screen prior to the executed command (it
     is only prepended to the command, no newlines are added).
 
     Note: this is similar to genutils.system(), but it returns None so it can
     be conveniently used in interactive loops without getting the return value
     (typically 0) printed many times."""
 
     stat = 0
     if verbose or debug: print header+cmd
     # flush stdout so we don't mangle python's buffering
     sys.stdout.flush()
     if not debug:
         os.system(cmd)
 
 # override shell() for win32 to deal with network shares
 if os.name in ('nt','dos'):
 
     shell_ori = shell
 
     def shell(cmd,verbose=0,debug=0,header=''):
         if os.getcwd().startswith(r"\\"):
             path = os.getcwd()
             # change to c drive (cannot be on UNC-share when issuing os.system,
             # as cmd.exe cannot handle UNC addresses)
             os.chdir("c:")
             # issue pushd to the UNC-share and then run the command
             try:
                 shell_ori('"pushd %s&&"'%path+cmd,verbose,debug,header)
             finally:
                 os.chdir(path)
         else:
             shell_ori(cmd,verbose,debug,header)
 
     shell.__doc__ = shell_ori.__doc__
 
 def getoutput(cmd,verbose=0,debug=0,header='',split=0):
     """Dummy substitute for perl's backquotes.
 
     Executes a command and returns the output.
 
     Accepts the same arguments as system(), plus:
 
     - split(0): if true, the output is returned as a list split on newlines.
 
     Note: a stateful version of this function is available through the
     SystemExec class."""
 
     if verbose or debug: print header+cmd
     if not debug:
         output = commands.getoutput(cmd)
         if split:
             return output.split('\n')
         else:
             return output
 
 def getoutputerror(cmd,verbose=0,debug=0,header='',split=0):
     """Return (standard output,standard error) of executing cmd in a shell.
 
     Accepts the same arguments as system(), plus:
 
     - split(0): if true, each of stdout/err is returned as a list split on
     newlines.
 
     Note: a stateful version of this function is available through the
     SystemExec class."""
 
     if verbose or debug: print header+cmd
     if not cmd:
         if split:
             return [],[]
         else:
             return '',''
     if not debug:
         pin,pout,perr = os.popen3(cmd)
         tout = pout.read().rstrip()
         terr = perr.read().rstrip()
         pin.close()
         pout.close()
         perr.close()
         if split:
             return tout.split('\n'),terr.split('\n')
         else:
             return tout,terr
 
 # for compatibility with older naming conventions
 xsys = system
 bq = getoutput
 
 class SystemExec:
     """Access the system and getoutput functions through a stateful interface.
 
     Note: here we refer to the system and getoutput functions from this
     library, not the ones from the standard python library.
     
     This class offers the system and getoutput functions as methods, but the
     verbose, debug and header parameters can be set for the instance (at
     creation time or later) so that they don't need to be specified on each
     call.
 
     For efficiency reasons, there's no way to override the parameters on a
     per-call basis other than by setting instance attributes. If you need
     local overrides, it's best to directly call system() or getoutput().
 
     The following names are provided as alternate options:
      - xsys: alias to system
      - bq: alias to getoutput
 
     An instance can then be created as:
      >>> sysexec = SystemExec(verbose=1,debug=0,header='Calling: ')
 
     And used as:
      >>> sysexec.xsys('pwd')
      >>> dirlist = sysexec.bq('ls -l')
     """
     
     def __init__(self,verbose=0,debug=0,header='',split=0):
         """Specify the instance's values for verbose, debug and header."""
         setattr_list(self,'verbose debug header split')
 
     def system(self,cmd):
         """Stateful interface to system(), with the same keyword parameters."""
 
         system(cmd,self.verbose,self.debug,self.header)
 
     def shell(self,cmd):
         """Stateful interface to shell(), with the same keyword parameters."""
 
         shell(cmd,self.verbose,self.debug,self.header)
 
     xsys = system  # alias
 
     def getoutput(self,cmd):
         """Stateful interface to getoutput()."""
 
         return getoutput(cmd,self.verbose,self.debug,self.header,self.split)
 
     def getoutputerror(self,cmd):
         """Stateful interface to getoutputerror()."""
 
         return getoutputerror(cmd,self.verbose,self.debug,self.header,self.split)
 
     bq = getoutput  # alias
 
 #-----------------------------------------------------------------------------
 def mutex_opts(dict,ex_op):
     """Check for presence of mutually exclusive keys in a dict.
 
     Call: mutex_opts(dict,[[op1a,op1b],[op2a,op2b]...]"""
     for op1,op2 in ex_op:
         if op1 in dict and op2 in dict:
             raise ValueError,'\n*** ERROR in Arguments *** '\
                   'Options '+op1+' and '+op2+' are mutually exclusive.'
 
 #-----------------------------------------------------------------------------
 def get_py_filename(name):
     """Return a valid python filename in the current directory.
 
     If the given name is not a file, it adds '.py' and searches again.
     Raises IOError with an informative message if the file isn't found."""
 
     name = os.path.expanduser(name)
     if not os.path.isfile(name) and not name.endswith('.py'):
         name += '.py'
     if os.path.isfile(name):
         return name
     else:
         raise IOError,'File `%s` not found.' % name
 
 #-----------------------------------------------------------------------------
 def filefind(fname,alt_dirs = None):
     """Return the given filename either in the current directory, if it
     exists, or in a specified list of directories.
 
     ~ expansion is done on all file and directory names.
 
     Upon an unsuccessful search, raise an IOError exception."""
 
     if alt_dirs is None:
         try:
             alt_dirs = get_home_dir()
         except HomeDirError:
             alt_dirs = os.getcwd()
     search = [fname] + list_strings(alt_dirs)
     search = map(os.path.expanduser,search)
     #print 'search list for',fname,'list:',search  # dbg
     fname = search[0]
     if os.path.isfile(fname):
         return fname
     for direc in search[1:]:
         testname = os.path.join(direc,fname)
         #print 'testname',testname  # dbg
         if os.path.isfile(testname):
             return testname
     raise IOError,'File' + `fname` + \
           ' not found in current or supplied directories:' + `alt_dirs`
 
 #----------------------------------------------------------------------------
 def file_read(filename):
     """Read a file and close it.  Returns the file source."""
     fobj=open(filename,'r');
     source = fobj.read();
     fobj.close()
     return source
 
 #----------------------------------------------------------------------------
 def target_outdated(target,deps):
     """Determine whether a target is out of date.
 
     target_outdated(target,deps) -> 1/0
 
     deps: list of filenames which MUST exist.
     target: single filename which may or may not exist.
 
     If target doesn't exist or is older than any file listed in deps, return
     true, otherwise return false.
     """
     try:
         target_time = os.path.getmtime(target)
     except os.error:
         return 1
     for dep in deps:
         dep_time = os.path.getmtime(dep)
         if dep_time > target_time:
             #print "For target",target,"Dep failed:",dep # dbg
             #print "times (dep,tar):",dep_time,target_time # dbg
             return 1
     return 0
 
 #-----------------------------------------------------------------------------
 def target_update(target,deps,cmd):
     """Update a target with a given command given a list of dependencies.
 
     target_update(target,deps,cmd) -> runs cmd if target is outdated.
 
     This is just a wrapper around target_outdated() which calls the given
     command if target is outdated."""
 
     if target_outdated(target,deps):
         xsys(cmd)
 
 #----------------------------------------------------------------------------
 def unquote_ends(istr):
     """Remove a single pair of quotes from the endpoints of a string."""
 
     if not istr:
         return istr
     if (istr[0]=="'" and istr[-1]=="'") or \
        (istr[0]=='"' and istr[-1]=='"'):
         return istr[1:-1]
     else:
         return istr
 
 #----------------------------------------------------------------------------
 def process_cmdline(argv,names=[],defaults={},usage=''):
     """ Process command-line options and arguments.
 
     Arguments:
 
     - argv: list of arguments, typically sys.argv.
     
     - names: list of option names. See DPyGetOpt docs for details on options
     syntax.
 
     - defaults: dict of default values.
 
     - usage: optional usage notice to print if a wrong argument is passed.
 
     Return a dict of options and a list of free arguments."""
 
     getopt = DPyGetOpt.DPyGetOpt()
     getopt.setIgnoreCase(0)
     getopt.parseConfiguration(names)
 
     try:
         getopt.processArguments(argv)
     except:
         print usage
         warn(`sys.exc_value`,level=4)
 
     defaults.update(getopt.optionValues)
     args = getopt.freeValues
     
     return defaults,args
 
 #----------------------------------------------------------------------------
 def optstr2types(ostr):
     """Convert a string of option names to a dict of type mappings.
 
     optstr2types(str) -> {None:'string_opts',int:'int_opts',float:'float_opts'}
 
     This is used to get the types of all the options in a string formatted
     with the conventions of DPyGetOpt. The 'type' None is used for options
     which are strings (they need no further conversion). This function's main
     use is to get a typemap for use with read_dict().
     """
 
     typeconv = {None:'',int:'',float:''}
     typemap = {'s':None,'i':int,'f':float}
     opt_re = re.compile(r'([\w]*)([^:=]*:?=?)([sif]?)')
 
     for w in ostr.split():
         oname,alias,otype = opt_re.match(w).groups()
         if otype == '' or alias == '!':   # simple switches are integers too
             otype = 'i'
         typeconv[typemap[otype]] += oname + ' '
     return typeconv
 
 #----------------------------------------------------------------------------
 def read_dict(filename,type_conv=None,**opt):
 
     """Read a dictionary of key=value pairs from an input file, optionally
     performing conversions on the resulting values.
 
     read_dict(filename,type_conv,**opt) -> dict
 
     Only one value per line is accepted, the format should be
      # optional comments are ignored
      key value\n
 
     Args:
 
       - type_conv: A dictionary specifying which keys need to be converted to
       which types. By default all keys are read as strings. This dictionary
       should have as its keys valid conversion functions for strings
       (int,long,float,complex, or your own).  The value for each key
       (converter) should be a whitespace separated string containing the names
       of all the entries in the file to be converted using that function. For
       keys to be left alone, use None as the conversion function (only needed
       with purge=1, see below).
 
       - opt: dictionary with extra options as below (default in parens)
 
         purge(0): if set to 1, all keys *not* listed in type_conv are purged out
         of the dictionary to be returned. If purge is going to be used, the
         set of keys to be left as strings also has to be explicitly specified
         using the (non-existent) conversion function None.
 
         fs(None): field separator. This is the key/value separator to be used
         when parsing the file. The None default means any whitespace [behavior
         of string.split()].
 
         strip(0): if 1, strip string values of leading/trailinig whitespace.
 
         warn(1): warning level if requested keys are not found in file.
           - 0: silently ignore.
           - 1: inform but proceed.
           - 2: raise KeyError exception.
 
         no_empty(0): if 1, remove keys with whitespace strings as a value.
 
         unique([]): list of keys (or space separated string) which can't be
         repeated. If one such key is found in the file, each new instance
         overwrites the previous one. For keys not listed here, the behavior is
         to make a list of all appearances.
 
     Example:
     If the input file test.ini has:
       i 3
       x 4.5
       y 5.5
       s hi ho
     Then:
 
     >>> type_conv={int:'i',float:'x',None:'s'}
     >>> read_dict('test.ini')
     {'i': '3', 's': 'hi ho', 'x': '4.5', 'y': '5.5'}
     >>> read_dict('test.ini',type_conv)
     {'i': 3, 's': 'hi ho', 'x': 4.5, 'y': '5.5'}
     >>> read_dict('test.ini',type_conv,purge=1)
     {'i': 3, 's': 'hi ho', 'x': 4.5}
     """
 
     # starting config
     opt.setdefault('purge',0)
     opt.setdefault('fs',None)  # field sep defaults to any whitespace
     opt.setdefault('strip',0)
     opt.setdefault('warn',1)
     opt.setdefault('no_empty',0)
     opt.setdefault('unique','')
     if type(opt['unique']) in StringTypes:
         unique_keys = qw(opt['unique'])
     elif type(opt['unique']) in (types.TupleType,types.ListType):
         unique_keys = opt['unique']
     else:
         raise ValueError, 'Unique keys must be given as a string, List or Tuple'
 
     dict = {}
     # first read in table of values as strings
     file = open(filename,'r')
     for line in file.readlines():
         line = line.strip()
         if len(line) and line[0]=='#': continue
         if len(line)>0:
             lsplit = line.split(opt['fs'],1)
             try:
                 key,val = lsplit
             except ValueError:
                 key,val = lsplit[0],''
             key = key.strip()
             if opt['strip']: val = val.strip()
             if val == "''" or val == '""': val = ''
             if opt['no_empty'] and (val=='' or val.isspace()):
                 continue
             # if a key is found more than once in the file, build a list
             # unless it's in the 'unique' list. In that case, last found in file
             # takes precedence. User beware.
             try:
                 if dict[key] and key in unique_keys:
                     dict[key] = val
                 elif type(dict[key]) is types.ListType:
                     dict[key].append(val)
                 else:
                     dict[key] = [dict[key],val]
             except KeyError:
                 dict[key] = val
     # purge if requested
     if opt['purge']:
         accepted_keys = qwflat(type_conv.values())
         for key in dict.keys():
             if key in accepted_keys: continue
             del(dict[key])
     # now convert if requested
     if type_conv==None: return dict
     conversions = type_conv.keys()
     try: conversions.remove(None)
     except: pass
     for convert in conversions:
         for val in qw(type_conv[convert]):
             try:
                 dict[val] = convert(dict[val])
             except KeyError,e:
                 if opt['warn'] == 0:
                     pass
                 elif opt['warn'] == 1:
                     print >>sys.stderr, 'Warning: key',val,\
                           'not found in file',filename
                 elif opt['warn'] == 2:
                     raise KeyError,e
                 else:
                     raise ValueError,'Warning level must be 0,1 or 2'
 
     return dict
 
 #----------------------------------------------------------------------------
 def flag_calls(func):
     """Wrap a function to detect and flag when it gets called.
 
     This is a decorator which takes a function and wraps it in a function with
     a 'called' attribute. wrapper.called is initialized to False.
 
     The wrapper.called attribute is set to False right before each call to the
     wrapped function, so if the call fails it remains False.  After the call
     completes, wrapper.called is set to True and the output is returned.
 
     Testing for truth in wrapper.called allows you to determine if a call to
     func() was attempted and succeeded."""
     
     def wrapper(*args,**kw):
         wrapper.called = False
         out = func(*args,**kw)
         wrapper.called = True
         return out
 
     wrapper.called = False
     wrapper.__doc__ = func.__doc__
     return wrapper
 
 #----------------------------------------------------------------------------
 class HomeDirError(Error):
     pass
 
 def get_home_dir():
     """Return the closest possible equivalent to a 'home' directory.
 
     We first try $HOME.  Absent that, on NT it's $HOMEDRIVE\$HOMEPATH.
 
     Currently only Posix and NT are implemented, a HomeDirError exception is
     raised for all other OSes. """
 
     isdir = os.path.isdir
     env = os.environ
     try:
         homedir = env['HOME']
         if not isdir(homedir):
             # in case a user stuck some string which does NOT resolve to a
             # valid path, it's as good as if we hadn't foud it
             raise KeyError
         return homedir
     except KeyError:
         if os.name == 'posix':
             raise HomeDirError,'undefined $HOME, IPython can not proceed.'
         elif os.name == 'nt':
             # For some strange reason, win9x returns 'nt' for os.name.
             try:
                 homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
                 if not isdir(homedir):
                     homedir = os.path.join(env['USERPROFILE'])
                     if not isdir(homedir):
                         raise HomeDirError
                 return homedir
             except:
                 try:
                     # Use the registry to get the 'My Documents' folder.
                     import _winreg as wreg
                     key = wreg.OpenKey(wreg.HKEY_CURRENT_USER,
                                        "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
                     homedir = wreg.QueryValueEx(key,'Personal')[0]
                     key.Close()
                     if not isdir(homedir):
                         e = ('Invalid "Personal" folder registry key '
                              'typically "My Documents".\n'
                              'Value: %s\n'
                              'This is not a valid directory on your system.' %
                              homedir)
                         raise HomeDirError(e)
                     return homedir
                 except HomeDirError:
                     raise
                 except:
                     return 'C:\\'
         elif os.name == 'dos':
             # Desperate, may do absurd things in classic MacOS. May work under DOS.
             return 'C:\\'
         else:
             raise HomeDirError,'support for your operating system not implemented.'
 
 #****************************************************************************
 # strings and text
 
 class LSString(str):
     """String derivative with a special access attributes.
 
     These are normal strings, but with the special attributes:
 
         .l (or .list) : value as list (split on newlines).
         .n (or .nlstr): original value (the string itself).
         .s (or .spstr): value as whitespace-separated string.
         
     Any values which require transformations are computed only once and
     cached.
 
     Such strings are very useful to efficiently interact with the shell, which
     typically only understands whitespace-separated options for commands."""
 
     def get_list(self):
         try:
             return self.__list
         except AttributeError:
             self.__list = self.split('\n')
             return self.__list
 
     l = list = property(get_list)
 
     def get_spstr(self):
         try:
             return self.__spstr
         except AttributeError:
             self.__spstr = self.replace('\n',' ')
             return self.__spstr
 
     s = spstr = property(get_spstr)
 
     def get_nlstr(self):
         return self
 
     n = nlstr = property(get_nlstr)
 
 #----------------------------------------------------------------------------
 class SList(list):
     """List derivative with a special access attributes.
 
     These are normal lists, but with the special attributes:
 
         .l (or .list) : value as list (the list itself).
         .n (or .nlstr): value as a string, joined on newlines.
         .s (or .spstr): value as a string, joined on spaces.
 
     Any values which require transformations are computed only once and
     cached."""
 
     def get_list(self):
         return self
 
     l = list = property(get_list)
 
     def get_spstr(self):
         try:
             return self.__spstr
         except AttributeError:
             self.__spstr = ' '.join(self)
             return self.__spstr
 
     s = spstr = property(get_spstr)
 
     def get_nlstr(self):
         try:
             return self.__nlstr
         except AttributeError:
             self.__nlstr = '\n'.join(self)
             return self.__nlstr
 
     n = nlstr = property(get_nlstr)
 
 #----------------------------------------------------------------------------
 # This can be replaced with an isspace() call once we drop 2.2 compatibility
 _isspace_match = re.compile(r'^\s+$').match
 def isspace(s):
     return bool(_isspace_match(s))
 
 #----------------------------------------------------------------------------
 def esc_quotes(strng):
     """Return the input string with single and double quotes escaped out"""
 
     return strng.replace('"','\\"').replace("'","\\'")
 
 #----------------------------------------------------------------------------
 def raw_input_multi(header='', ps1='==> ', ps2='..> ',terminate_str = '.'):
     """Take multiple lines of input.
 
     A list with each line of input as a separate element is returned when a
     termination string is entered (defaults to a single '.'). Input can also
     terminate via EOF (^D in Unix, ^Z-RET in Windows).
 
     Lines of input which end in \\ are joined into single entries (and a
     secondary continuation prompt is issued as long as the user terminates
     lines with \\). This allows entering very long strings which are still
     meant to be treated as single entities.
     """
 
     try:
         if header:
             header += '\n'
         lines = [raw_input(header + ps1)]
     except EOFError:
         return []
     terminate = [terminate_str]
     try:
         while lines[-1:] != terminate:
             new_line = raw_input(ps1)
             while new_line.endswith('\\'):
                 new_line = new_line[:-1] + raw_input(ps2)
             lines.append(new_line)
                 
         return lines[:-1]  # don't return the termination command
     except EOFError:
         print
         return lines
 
 #----------------------------------------------------------------------------
 def raw_input_ext(prompt='',  ps2='... '):
     """Similar to raw_input(), but accepts extended lines if input ends with \\."""
 
     line = raw_input(prompt)
     while line.endswith('\\'):
         line = line[:-1] + raw_input(ps2)
     return line
 
 #----------------------------------------------------------------------------
 def ask_yes_no(prompt,default=None):
     """Asks a question and returns an integer 1/0 (y/n) answer.
 
     If default is given (one of 'y','n'), it is used if the user input is
     empty. Otherwise the question is repeated until an answer is given.
     If EOF occurs 20 times consecutively, the default answer is assumed,
     or if there is no default, an exception is raised to prevent infinite
     loops.
 
     Valid answers are: y/yes/n/no (match is not case sensitive)."""
 
     answers = {'y':True,'n':False,'yes':True,'no':False}
     ans = None
     eofs, max_eofs = 0, 20
     while ans not in answers.keys():
         try:
             ans = raw_input(prompt+' ').lower()
             if not ans:  # response was an empty string
                 ans = default
             eofs = 0
         except (EOFError,KeyboardInterrupt):
             eofs = eofs + 1
             if eofs >= max_eofs:
                 if default in answers.keys():
                     ans = default
                 else:
                     raise
             
     return answers[ans]
 
 #----------------------------------------------------------------------------
 def marquee(txt='',width=78,mark='*'):
     """Return the input string centered in a 'marquee'."""
     if not txt:
         return (mark*width)[:width]
     nmark = (width-len(txt)-2)/len(mark)/2
     if nmark < 0: nmark =0
     marks = mark*nmark
     return '%s %s %s' % (marks,txt,marks)
 
 #----------------------------------------------------------------------------
 class EvalDict:
     """
     Emulate a dict which evaluates its contents in the caller's frame.
 
     Usage:
     >>>number = 19
     >>>text = "python"
     >>>print "%(text.capitalize())s %(number/9.0).1f rules!" % EvalDict()
     """
 
     # This version is due to [e-mail] on c.l.py, and is basically a
     # modified (shorter) version of:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/66018 by
     # Skip Montanaro ([e-mail]).
 
     def __getitem__(self, name):
         frame = sys._getframe(1)
         return eval(name, frame.f_globals, frame.f_locals)
 
 EvalString = EvalDict  # for backwards compatibility
 #----------------------------------------------------------------------------
 def qw(words,flat=0,sep=None,maxsplit=-1):
     """Similar to Perl's qw() operator, but with some more options.
 
     qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
 
     words can also be a list itself, and with flat=1, the output will be
     recursively flattened. Examples:
 
     >>> qw('1 2')
     ['1', '2']
     >>> qw(['a b','1 2',['m n','p q']])
     [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
     >>> qw(['a b','1 2',['m n','p q']],flat=1)
     ['a', 'b', '1', '2', 'm', 'n', 'p', 'q']    """
 
     if type(words) in StringTypes:
         return [word.strip() for word in words.split(sep,maxsplit)
                 if word and not word.isspace() ]
     if flat:
         return flatten(map(qw,words,[1]*len(words)))
     return map(qw,words)
 
 #----------------------------------------------------------------------------
 def qwflat(words,sep=None,maxsplit=-1):
     """Calls qw(words) in flat mode. It's just a convenient shorthand."""
     return qw(words,1,sep,maxsplit)
 
 #----------------------------------------------------------------------------
 def qw_lol(indata):
     """qw_lol('a b') -> [['a','b']],
     otherwise it's just a call to qw().
 
     We need this to make sure the modules_some keys *always* end up as a
     list of lists."""
 
     if type(indata) in StringTypes:
         return [qw(indata)]
     else:
         return qw(indata)
 
 #-----------------------------------------------------------------------------
 def list_strings(arg):
     """Always return a list of strings, given a string or list of strings
     as input."""
 
     if type(arg) in StringTypes: return [arg]
     else: return arg
 
 #----------------------------------------------------------------------------
 def grep(pat,list,case=1):
     """Simple minded grep-like function.
     grep(pat,list) returns occurrences of pat in list, None on failure.
 
     It only does simple string matching, with no support for regexps. Use the
     option case=0 for case-insensitive matching."""
 
     # This is pretty crude. At least it should implement copying only references
     # to the original data in case it's big. Now it copies the data for output.
     out=[]
     if case:
         for term in list:
             if term.find(pat)>-1: out.append(term)
     else:
         lpat=pat.lower()
         for term in list:
             if term.lower().find(lpat)>-1: out.append(term)
 
     if len(out): return out
     else: return None
 
 #----------------------------------------------------------------------------
 def dgrep(pat,*opts):
     """Return grep() on dir()+dir(__builtins__).
 
     A very common use of grep() when working interactively."""
 
     return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
 
 #----------------------------------------------------------------------------
 def idgrep(pat):
     """Case-insensitive dgrep()"""
 
     return dgrep(pat,0)
 
 #----------------------------------------------------------------------------
 def igrep(pat,list):
     """Synonym for case-insensitive grep."""
 
     return grep(pat,list,case=0)
 
 #----------------------------------------------------------------------------
 def indent(str,nspaces=4,ntabs=0):
     """Indent a string a given number of spaces or tabstops.
     
     indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
     """
     if str is None:
         return
     ind = '\t'*ntabs+' '*nspaces
     outstr = '%s%s' % (ind,str.replace(os.linesep,os.linesep+ind))
     if outstr.endswith(os.linesep+ind):
         return outstr[:-len(ind)]
     else:
         return outstr
     
 #-----------------------------------------------------------------------------
 def native_line_ends(filename,backup=1):
     """Convert (in-place) a file to line-ends native to the current OS.
 
     If the optional backup argument is given as false, no backup of the
     original file is left.  """
 
     backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
 
     bak_filename = filename + backup_suffixes[os.name]
 
     original = open(filename).read()
     shutil.copy2(filename,bak_filename)
     try:
         new = open(filename,'wb')
         new.write(os.linesep.join(original.splitlines()))
         new.write(os.linesep) # ALWAYS put an eol at the end of the file
         new.close()
     except:
         os.rename(bak_filename,filename)
     if not backup:
         try:
             os.remove(bak_filename)
         except:
             pass
     
 #----------------------------------------------------------------------------
 def get_pager_cmd(pager_cmd = None):
     """Return a pager command.
 
     Makes some attempts at finding an OS-correct one."""
     
     if os.name == 'posix':
         default_pager_cmd = 'less -r'  # -r for color control sequences
     elif os.name in ['nt','dos']:
         default_pager_cmd = 'type'
 
     if pager_cmd is None:
         try:
             pager_cmd = os.environ['PAGER']
         except:
             pager_cmd = default_pager_cmd
     return pager_cmd
 
 #-----------------------------------------------------------------------------
 def get_pager_start(pager,start):
     """Return the string for paging files with an offset.
 
     This is the '+N' argument which less and more (under Unix) accept.
     """
 
     if pager in ['less','more']:
         if start:
             start_string = '+' + str(start)
         else:
             start_string = ''
     else:
         start_string = ''
     return start_string
 
 #----------------------------------------------------------------------------
 if os.name == "nt":
     import msvcrt
     def page_more():
         """ Smart pausing between pages
 
         @return:    True if need print more lines, False if quit
         """
         Term.cout.write('---Return to continue, q to quit--- ')
         ans = msvcrt.getch()
         if ans in ("q", "Q"):
             result = False
         else:
             result = True
         Term.cout.write("\b"*37 + " "*37 + "\b"*37)
         return result
 else:
     def page_more():
         ans = raw_input('---Return to continue, q to quit--- ')
         if ans.lower().startswith('q'):
             return False
         else:
             return True
 
 esc_re = re.compile(r"(\x1b[^m]+m)")
 
 def page_dumb(strng,start=0,screen_lines=25):
     """Very dumb 'pager' in Python, for when nothing else works.
 
     Only moves forward, same interface as page(), except for pager_cmd and
     mode."""
 
     out_ln  = strng.splitlines()[start:]
     screens = chop(out_ln,screen_lines-1)
     if len(screens) == 1:
         print >>Term.cout, os.linesep.join(screens[0])
     else:
         last_escape = ""
         for scr in screens[0:-1]:
             hunk = os.linesep.join(scr)
             print >>Term.cout, last_escape + hunk
             if not page_more():
                 return
             esc_list = esc_re.findall(hunk)
             if len(esc_list) > 0:
                 last_escape = esc_list[-1]
         print >>Term.cout, last_escape + os.linesep.join(screens[-1])
 
 #----------------------------------------------------------------------------
 def page(strng,start=0,screen_lines=0,pager_cmd = None):
     """Print a string, piping through a pager after a certain length.
 
     The screen_lines parameter specifies the number of *usable* lines of your
     terminal screen (total lines minus lines you need to reserve to show other
     information).
 
     If you set screen_lines to a number <=0, page() will try to auto-determine
     your screen size and will only use up to (screen_size+screen_lines) for
     printing, paging after that. That is, if you want auto-detection but need
     to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
     auto-detection without any lines reserved simply use screen_lines = 0.
 
     If a string won't fit in the allowed lines, it is sent through the
     specified pager command. If none given, look for PAGER in the environment,
     and ultimately default to less.
 
     If no system pager works, the string is sent through a 'dumb pager'
     written in python, very simplistic.
     """
     
     # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
     TERM = os.environ.get('TERM','dumb')
     if TERM in ['dumb','emacs'] and os.name != 'nt':
         print strng
         return
     # chop off the topmost part of the string we don't want to see
     str_lines = strng.split(os.linesep)[start:]
     str_toprint = os.linesep.join(str_lines)
     num_newlines = len(str_lines)
     len_str = len(str_toprint)
     
     # Dumb heuristics to guesstimate number of on-screen lines the string
     # takes.  Very basic, but good enough for docstrings in reasonable
     # terminals. If someone later feels like refining it, it's not hard.
     numlines = max(num_newlines,int(len_str/80)+1)
 
     if os.name == "nt":
         screen_lines_def = get_console_size(defaulty=25)[1]
     else:
         screen_lines_def = 25 # default value if we can't auto-determine
 
     # auto-determine screen size
     if screen_lines <= 0:
         if TERM=='xterm':
             try:
                 import curses
                 if hasattr(curses,'initscr'):
                     use_curses = 1
                 else:
                     use_curses = 0
             except ImportError:
                 use_curses = 0
         else:
             # curses causes problems on many terminals other than xterm.
             use_curses = 0
         if use_curses:
                 scr = curses.initscr()
                 screen_lines_real,screen_cols = scr.getmaxyx()
                 curses.endwin()
                 screen_lines += screen_lines_real
                 #print '***Screen size:',screen_lines_real,'lines x',\
                 #screen_cols,'columns.' # dbg
         else:
                 screen_lines += screen_lines_def
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :
         #print '*** normal print'  # dbg
         print >>Term.cout, str_toprint
     else:
         # Try to open pager and default to internal one if that fails.
         # All failure modes are tagged as 'retval=1', to match the return
         # value of a failed system command.  If any intermediate attempt
         # sets retval to 1, at the end we resort to our own page_dumb() pager.
         pager_cmd = get_pager_cmd(pager_cmd)
         pager_cmd += ' ' + get_pager_start(pager_cmd,start)
         if os.name == 'nt':
             if pager_cmd.startswith('type'):
                 # The default WinXP 'type' command is failing on complex strings.
                 retval = 1
             else:
                 tmpname = tempfile.mktemp('.txt')
                 tmpfile = file(tmpname,'wt')
                 tmpfile.write(strng)
                 tmpfile.close()
                 cmd = "%s < %s" % (pager_cmd,tmpname)
                 if os.system(cmd):
                   retval = 1
                 else:
                   retval = None
                 os.remove(tmpname)
         else:
             try:
                 retval = None
                 # if I use popen4, things hang. No idea why.
                 #pager,shell_out = os.popen4(pager_cmd)
                 pager = os.popen(pager_cmd,'w')
                 pager.write(strng)
                 pager.close()
                 retval = pager.close()  # success returns None
             except IOError,msg:  # broken pipe when user quits
                 if msg.args == (32,'Broken pipe'):
                     retval = None
                 else:
                     retval = 1
             except OSError:
                 # Other strange problems, sometimes seen in Win2k/cygwin
                 retval = 1
         if retval is not None:
             page_dumb(strng,screen_lines=screen_lines)
 
 #----------------------------------------------------------------------------
 def page_file(fname,start = 0, pager_cmd = None):
     """Page a file, using an optional pager command and starting line.
     """
 
     pager_cmd = get_pager_cmd(pager_cmd)
     pager_cmd += ' ' + get_pager_start(pager_cmd,start)
 
     try:
         if os.environ['TERM'] in ['emacs','dumb']:
             raise EnvironmentError
         xsys(pager_cmd + ' ' + fname)
     except:
         try:
             if start > 0:
                 start -= 1
             page(open(fname).read(),start)
         except:
             print 'Unable to show file',`fname`
 
 #----------------------------------------------------------------------------
 def snip_print(str,width = 75,print_full = 0,header = ''):
     """Print a string snipping the midsection to fit in width.
 
     print_full: mode control:
       - 0: only snip long strings
       - 1: send to page() directly.
       - 2: snip long strings and ask for full length viewing with page()
     Return 1 if snipping was necessary, 0 otherwise."""
 
     if print_full == 1:
         page(header+str)
         return 0
 
     print header,
     if len(str) < width:
         print str
         snip = 0
     else:
         whalf = int((width -5)/2)
         print str[:whalf] + ' <...> ' + str[-whalf:]
         snip = 1
     if snip and print_full == 2:
         if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
             page(str)
     return snip
 
 #****************************************************************************
 # lists, dicts and structures
 
 def belong(candidates,checklist):
     """Check whether a list of items appear in a given list of options.
 
     Returns a list of 1 and 0, one for each candidate given."""
 
     return [x in checklist for x in candidates]
 
 #----------------------------------------------------------------------------
 def uniq_stable(elems):
     """uniq_stable(elems) -> list
 
     Return from an iterable, a list of all the unique elements in the input,
     but maintaining the order in which they first appear.
 
     A naive solution to this problem which just makes a dictionary with the
     elements as keys fails to respect the stability condition, since
     dictionaries are unsorted by nature.
 
     Note: All elements in the input must be valid dictionary keys for this
     routine to work, as it internally uses a dictionary for efficiency
     reasons."""
     
     unique = []
     unique_dict = {}
     for nn in elems:
         if nn not in unique_dict:
             unique.append(nn)
             unique_dict[nn] = None
     return unique
 
 #----------------------------------------------------------------------------
 class NLprinter:
     """Print an arbitrarily nested list, indicating index numbers.
 
     An instance of this class called nlprint is available and callable as a
     function.
     
     nlprint(list,indent=' ',sep=': ') -> prints indenting each level by 'indent'
     and using 'sep' to separate the index from the value. """
 
     def __init__(self):
         self.depth = 0
     
     def __call__(self,lst,pos='',**kw):
         """Prints the nested list numbering levels."""
         kw.setdefault('indent',' ')
         kw.setdefault('sep',': ')
         kw.setdefault('start',0)
         kw.setdefault('stop',len(lst))
         # we need to remove start and stop from kw so they don't propagate
         # into a recursive call for a nested list.
         start = kw['start']; del kw['start']
         stop = kw['stop']; del kw['stop']
         if self.depth == 0 and 'header' in kw.keys():
             print kw['header']
             
         for idx in range(start,stop):
             elem = lst[idx]
             if type(elem)==type([]):
                 self.depth += 1
                 self.__call__(elem,itpl('$pos$idx,'),**kw)
                 self.depth -= 1
             else:
                 printpl(kw['indent']*self.depth+'$pos$idx$kw["sep"]$elem')
 
 nlprint = NLprinter()
 #----------------------------------------------------------------------------
 def all_belong(candidates,checklist):
     """Check whether a list of items ALL appear in a given list of options.
 
     Returns a single 1 or 0 value."""
 
     return 1-(0 in [x in checklist for x in candidates])
 
 #----------------------------------------------------------------------------
 def sort_compare(lst1,lst2,inplace = 1):
     """Sort and compare two lists.
 
     By default it does it in place, thus modifying the lists. Use inplace = 0
     to avoid that (at the cost of temporary copy creation)."""
     if not inplace:
         lst1 = lst1[:]
         lst2 = lst2[:]
     lst1.sort(); lst2.sort()
     return lst1 == lst2
 
 #----------------------------------------------------------------------------
 def mkdict(**kwargs):
     """Return a dict from a keyword list.
 
     It's just syntactic sugar for making ditcionary creation more convenient:
     # the standard way
     >>>data = { 'red' : 1, 'green' : 2, 'blue' : 3 }
     # a cleaner way
     >>>data = dict(red=1, green=2, blue=3)
 
     If you need more than this, look at the Struct() class."""
 
     return kwargs
 
 #----------------------------------------------------------------------------
 def list2dict(lst):
     """Takes a list of (key,value) pairs and turns it into a dict."""
 
     dic = {}
     for k,v in lst: dic[k] = v
     return dic
 
 #----------------------------------------------------------------------------
 def list2dict2(lst,default=''):
     """Takes a list and turns it into a dict.
     Much slower than list2dict, but more versatile. This version can take
     lists with sublists of arbitrary length (including sclars)."""
 
     dic = {}
     for elem in lst:
         if type(elem) in (types.ListType,types.TupleType):
             size = len(elem)
             if  size == 0:
                 pass
             elif size == 1:
                 dic[elem] = default
             else:
                 k,v = elem[0], elem[1:]
                 if len(v) == 1: v = v[0]
                 dic[k] = v
         else:
             dic[elem] = default
     return dic
 
 #----------------------------------------------------------------------------
 def flatten(seq):
     """Flatten a list of lists (NOT recursive, only works for 2d lists)."""
 
     # bug in python??? (YES. Fixed in 2.2, let's leave the kludgy fix in).
 
     # if the x=0 isn't made, a *global* variable x is left over after calling
     # this function, with the value of the last element in the return
     # list. This does seem like a bug big time to me.
 
     # the problem is fixed with the x=0, which seems to force the creation of
     # a local name
 
     x = 0 
     return [x for subseq in seq for x in subseq]
 
 #----------------------------------------------------------------------------
 def get_slice(seq,start=0,stop=None,step=1):
     """Get a slice of a sequence with variable step. Specify start,stop,step."""
     if stop == None:
         stop = len(seq)
     item = lambda i: seq[i]
     return map(item,xrange(start,stop,step))
 
 #----------------------------------------------------------------------------
 def chop(seq,size):
     """Chop a sequence into chunks of the given size."""
     chunk = lambda i: seq[i:i+size]
     return map(chunk,xrange(0,len(seq),size))
 
 #----------------------------------------------------------------------------
 def with(object, **args):
     """Set multiple attributes for an object, similar to Pascal's with.
 
     Example:
     with(jim,
          born = 1960,
          haircolour = 'Brown',
          eyecolour = 'Green')
 
     Credit: Greg Ewing, in
     http://mail.python.org/pipermail/python-list/2001-May/040703.html"""
 
     object.__dict__.update(args)
 
 #----------------------------------------------------------------------------
 def setattr_list(obj,alist,nspace = None):
     """Set a list of attributes for an object taken from a namespace.
 
     setattr_list(obj,alist,nspace) -> sets in obj all the attributes listed in
     alist with their values taken from nspace, which must be a dict (something
     like locals() will often do) If nspace isn't given, locals() of the
     *caller* is used, so in most cases you can omit it.
 
     Note that alist can be given as a string, which will be automatically
     split into a list on whitespace. If given as a list, it must be a list of
     *strings* (the variable names themselves), not of variables."""
 
     # this grabs the local variables from the *previous* call frame -- that is
     # the locals from the function that called setattr_list().
     # - snipped from weave.inline()
     if nspace is None:
         call_frame = sys._getframe().f_back
         nspace = call_frame.f_locals
 
     if type(alist) in StringTypes:
         alist = alist.split()
     for attr in alist:
         val = eval(attr,nspace)
         setattr(obj,attr,val)
 
 #----------------------------------------------------------------------------
 def getattr_list(obj,alist,*args):
     """getattr_list(obj,alist[, default]) -> attribute list.
 
     Get a list of named attributes for an object. When a default argument is
     given, it is returned when the attribute doesn't exist; without it, an
     exception is raised in that case.
 
     Note that alist can be given as a string, which will be automatically
     split into a list on whitespace. If given as a list, it must be a list of
     *strings* (the variable names themselves), not of variables."""
 
     if type(alist) in StringTypes:
         alist = alist.split()
     if args:
         if len(args)==1:
             default = args[0]
             return map(lambda attr: getattr(obj,attr,default),alist)
         else:
             raise ValueError,'getattr_list() takes only one optional argument'
     else:
         return map(lambda attr: getattr(obj,attr),alist)
     
 #----------------------------------------------------------------------------
 def map_method(method,object_list,*argseq,**kw):
     """map_method(method,object_list,*args,**kw) -> list
 
     Return a list of the results of applying the methods to the items of the
     argument sequence(s).  If more than one sequence is given, the method is
     called with an argument list consisting of the corresponding item of each
     sequence. All sequences must be of the same length.
 
     Keyword arguments are passed verbatim to all objects called.
 
     This is Python code, so it's not nearly as fast as the builtin map()."""
 
     out_list = []
     idx = 0
     for object in object_list:
         try:
             handler = getattr(object, method)
         except AttributeError:
             out_list.append(None)
         else:
             if argseq:
                 args = map(lambda lst:lst[idx],argseq)
                 #print 'ob',object,'hand',handler,'ar',args # dbg
                 out_list.append(handler(args,**kw))
             else:
                 out_list.append(handler(**kw))
         idx += 1
     return out_list
 
 #----------------------------------------------------------------------------
 def import_fail_info(mod_name,fns=None):
     """Inform load failure for a module."""
 
     if fns == None:
         warn("Loading of %s failed.\n" % (mod_name,))
     else:
         warn("Loading of %s from %s failed.\n" % (fns,mod_name))
 
 #----------------------------------------------------------------------------
 # Proposed popitem() extension, written as a method
 
 class NotGiven: pass
 
 def popkey(dct,key,default=NotGiven):
     """Return dct[key] and delete dct[key].
 
     If default is given, return it if dct[key] doesn't exist, otherwise raise
     KeyError.  """
 
     try:
         val = dct[key]
     except KeyError:
         if default is NotGiven:
             raise
         else:
             return default
     else:
         del dct[key]
         return val
 #*************************** end of file <genutils.py> **********************
 

IPython/iplib.py

@@ -1,2153 +1,2163 b''
 # -*- coding: utf-8 -*-
 """
 IPython -- An enhanced Interactive Python
 
 Requires Python 2.1 or newer.
 
 This file contains all the classes and helper functions specific to IPython.
 
-$Id: iplib.py 993 2006-01-04 19:51:01Z fperez $
+$Id: iplib.py 994 2006-01-08 08:29:44Z fperez $
 """
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
-#       Copyright (C) 2001-2005 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #
 # Note: this code originally subclassed code.InteractiveConsole from the
 # Python standard library.  Over time, all of that class has been copied
 # verbatim here for modifications which could not be accomplished by
 # subclassing.  At this point, there are no dependencies at all on the code
 # module anymore (it is not even imported).  The Python License (sec. 2)
 # allows for this, but it's always nice to acknowledge credit where credit is
 # due.
 #*****************************************************************************
 
 #****************************************************************************
 # Modules and globals
 
 from __future__ import generators  # for 2.2 backwards-compatibility
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % \
               ( Release.authors['Janko'] + Release.authors['Fernando'] )
 __license__ = Release.license
 __version__ = Release.version
 
 # Python standard modules
 import __main__
 import __builtin__
 import StringIO
 import bdb
 import cPickle as pickle
 import codeop
 import exceptions
 import glob
 import inspect
 import keyword
 import new
 import os
 import pdb
 import pydoc
 import re
 import shutil
 import string
 import sys
 import tempfile
 import traceback
 import types
 
 from pprint import pprint, pformat
 
 # IPython's own modules
 import IPython
 from IPython import OInspect,PyColorize,ultraTB
 from IPython.ColorANSI import ColorScheme,ColorSchemeTable  # too long names
 from IPython.FakeModule import FakeModule
 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
 from IPython.Logger import Logger
 from IPython.Magic import Magic
 from IPython.Prompts import CachedOutput
 from IPython.Struct import Struct
 from IPython.background_jobs import BackgroundJobManager
 from IPython.usage import cmd_line_usage,interactive_usage
 from IPython.genutils import *
 
+# Globals
+
 # store the builtin raw_input globally, and use this always, in case user code
 # overwrites it (like wx.py.PyShell does)
 raw_input_original = raw_input
 
 # compiled regexps for autoindent management
 ini_spaces_re = re.compile(r'^(\s+)')
 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
 
+
 #****************************************************************************
 # Some utility function definitions
 
 def softspace(file, newvalue):
     """Copied from code.py, to remove the dependency"""
     oldvalue = 0
     try:
         oldvalue = file.softspace
     except AttributeError:
         pass
     try:
         file.softspace = newvalue
     except (AttributeError, TypeError):
         # "attribute-less object" or "read-only attributes"
         pass
     return oldvalue
 
-#****************************************************************************
-
 
 #****************************************************************************
 # Local use exceptions
 class SpaceInInput(exceptions.Exception): pass
 
+
 #****************************************************************************
 # Local use classes
 class Bunch: pass
 
 class Undefined: pass
 
 class InputList(list):
     """Class to store user input.
 
     It's basically a list, but slices return a string instead of a list, thus
     allowing things like (assuming 'In' is an instance):
 
     exec In[4:7]
 
     or
 
     exec In[5:9] + In[14] + In[21:25]"""
 
     def __getslice__(self,i,j):
         return ''.join(list.__getslice__(self,i,j))
 
 class SyntaxTB(ultraTB.ListTB):
     """Extension which holds some state: the last exception value"""
 
     def __init__(self,color_scheme = 'NoColor'):
         ultraTB.ListTB.__init__(self,color_scheme)
         self.last_syntax_error = None
 
     def __call__(self, etype, value, elist):
         self.last_syntax_error = value
         ultraTB.ListTB.__call__(self,etype,value,elist)
 
     def clear_err_state(self):
         """Return the current error state and clear it"""
         e = self.last_syntax_error
         self.last_syntax_error = None
         return e
 
 #****************************************************************************
 # Main IPython class
 
 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
 # until a full rewrite is made.  I've cleaned all cross-class uses of
 # attributes and methods, but too much user code out there relies on the
 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
 #
 # But at least now, all the pieces have been separated and we could, in
 # principle, stop using the mixin.  This will ease the transition to the
 # chainsaw branch.
 
 # For reference, the following is the list of 'self.foo' uses in the Magic
 # class as of 2005-12-28.  These are names we CAN'T use in the main ipython
 # class, to prevent clashes.
 
 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
 #  'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
 #  'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
 #  'self.value']
 
 class InteractiveShell(object,Magic):
     """An enhanced console for Python."""
 
     # class attribute to indicate whether the class supports threads or not.
     # Subclasses with thread support should override this as needed.
     isthreaded = False
 
     def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
                  user_ns = None,user_global_ns=None,banner2='',
                  custom_exceptions=((),None),embedded=False):
 
         # some minimal strict typechecks.  For some core data structures, I
         # want actual basic python types, not just anything that looks like
         # one.  This is especially true for namespaces.
         for ns in (user_ns,user_global_ns):
             if ns is not None and type(ns) != types.DictType:
                 raise TypeError,'namespace must be a dictionary'
 
         # Job manager (for jobs run as background threads)
         self.jobs = BackgroundJobManager()
 
         # track which builtins we add, so we can clean up later
         self.builtins_added = {}
         # This method will add the necessary builtins for operation, but
         # tracking what it did via the builtins_added dict.
         self.add_builtins()
 
         # Do the intuitively correct thing for quit/exit: we remove the
         # builtins if they exist, and our own magics will deal with this
         try:
             del __builtin__.exit, __builtin__.quit
         except AttributeError:
             pass
 
         # Store the actual shell's name
         self.name = name
 
         # We need to know whether the instance is meant for embedding, since
         # global/local namespaces need to be handled differently in that case
         self.embedded = embedded
 
         # command compiler
         self.compile = codeop.CommandCompiler()
 
         # User input buffer
         self.buffer = []
 
         # Default name given in compilation of code
         self.filename = '<ipython console>'
 
         # Make an empty namespace, which extension writers can rely on both
         # existing and NEVER being used by ipython itself.  This gives them a
         # convenient location for storing additional information and state
         # their extensions may require, without fear of collisions with other
         # ipython names that may develop later.
         self.meta = Bunch()
 
         # Create the namespace where the user will operate.  user_ns is
         # normally the only one used, and it is passed to the exec calls as
         # the locals argument.  But we do carry a user_global_ns namespace
         # given as the exec 'globals' argument,  This is useful in embedding
         # situations where the ipython shell opens in a context where the
         # distinction between locals and globals is meaningful.
 
         # FIXME. For some strange reason, __builtins__ is showing up at user
         # level as a dict instead of a module. This is a manual fix, but I
         # should really track down where the problem is coming from. Alex
         # Schmolck reported this problem first.
 
         # A useful post by Alex Martelli on this topic:
         # Re: inconsistent value from __builtins__
         # Von: Alex Martelli <[e-mail]>
         # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
         # Gruppen: comp.lang.python
 
         # Michael Hohn <[e-mail]> wrote:
         # > >>> print type(builtin_check.get_global_binding('__builtins__'))
         # > <type 'dict'>
         # > >>> print type(__builtins__)
         # > <type 'module'>
         # > Is this difference in return value intentional?
 
         # Well, it's documented that '__builtins__' can be either a dictionary
         # or a module, and it's been that way for a long time. Whether it's
         # intentional (or sensible), I don't know. In any case, the idea is
         # that if you need to access the built-in namespace directly, you
         # should start with "import __builtin__" (note, no 's') which will
         # definitely give you a module. Yeah, it's somewhat confusing:-(.
         
         if user_ns is None:
             # Set __name__ to __main__ to better match the behavior of the
             # normal interpreter.
             user_ns = {'__name__'     :'__main__',
                        '__builtins__' : __builtin__,
                        }
             
         if user_global_ns is None:
             user_global_ns = {}
 
         # Assign namespaces
         # This is the namespace where all normal user variables live
         self.user_ns = user_ns
         # Embedded instances require a separate namespace for globals.
         # Normally this one is unused by non-embedded instances.
         self.user_global_ns = user_global_ns
         # A namespace to keep track of internal data structures to prevent
         # them from cluttering user-visible stuff.  Will be updated later
         self.internal_ns = {}
 
         # Namespace of system aliases.  Each entry in the alias
         # table must be a 2-tuple of the form (N,name), where N is the number
         # of positional arguments of the alias.
         self.alias_table = {}
 
         # A table holding all the namespaces IPython deals with, so that
         # introspection facilities can search easily.
         self.ns_table = {'user':user_ns,
                          'user_global':user_global_ns,
                          'alias':self.alias_table,
                          'internal':self.internal_ns,
                          'builtin':__builtin__.__dict__
                          }
 
         # The user namespace MUST have a pointer to the shell itself.
         self.user_ns[name] = self
 
         # We need to insert into sys.modules something that looks like a
         # module but which accesses the IPython namespace, for shelve and
         # pickle to work interactively. Normally they rely on getting
         # everything out of __main__, but for embedding purposes each IPython
         # instance has its own private namespace, so we can't go shoving
         # everything into __main__.
 
         # note, however, that we should only do this for non-embedded
         # ipythons, which really mimic the __main__.__dict__ with their own
         # namespace.  Embedded instances, on the other hand, should not do
         # this because they need to manage the user local/global namespaces
         # only, but they live within a 'normal' __main__ (meaning, they
         # shouldn't overtake the execution environment of the script they're
         # embedded in).
 
         if not embedded:
             try:
                 main_name = self.user_ns['__name__']
             except KeyError:
                 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
             else:
                 #print "pickle hack in place"  # dbg
                 #print 'main_name:',main_name # dbg
                 sys.modules[main_name] = FakeModule(self.user_ns)
 
         # List of input with multi-line handling.
         # Fill its zero entry, user counter starts at 1
         self.input_hist = InputList(['\n'])
 
         # list of visited directories
         try:
             self.dir_hist = [os.getcwd()]
         except IOError, e:
             self.dir_hist = []
 
         # dict of output history
         self.output_hist = {}
 
         # dict of things NOT to alias (keywords, builtins and some magics)
         no_alias = {}
         no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
         for key in keyword.kwlist + no_alias_magics:
             no_alias[key] = 1
         no_alias.update(__builtin__.__dict__)
         self.no_alias = no_alias
                 
         # make global variables for user access to these
         self.user_ns['_ih'] = self.input_hist
         self.user_ns['_oh'] = self.output_hist
         self.user_ns['_dh'] = self.dir_hist
 
         # user aliases to input and output histories
         self.user_ns['In']  = self.input_hist
         self.user_ns['Out'] = self.output_hist
 
         # Object variable to store code object waiting execution.  This is
         # used mainly by the multithreaded shells, but it can come in handy in
         # other situations.  No need to use a Queue here, since it's a single
         # item which gets cleared once run.
         self.code_to_run = None
         
         # escapes for automatic behavior on the command line
         self.ESC_SHELL  = '!'
         self.ESC_HELP   = '?'
         self.ESC_MAGIC  = '%'
         self.ESC_QUOTE  = ','
         self.ESC_QUOTE2 = ';'
         self.ESC_PAREN  = '/'
 
         # And their associated handlers
         self.esc_handlers = {self.ESC_PAREN  : self.handle_auto,
                              self.ESC_QUOTE  : self.handle_auto,
                              self.ESC_QUOTE2 : self.handle_auto,
                              self.ESC_MAGIC  : self.handle_magic,
                              self.ESC_HELP   : self.handle_help,
                              self.ESC_SHELL  : self.handle_shell_escape,
                              }
 
         # class initializations
         Magic.__init__(self,self)
 
         # Python source parser/formatter for syntax highlighting
         pyformat = PyColorize.Parser().format
         self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
 
         # hooks holds pointers used for user-side customizations
         self.hooks = Struct()
         
         # Set all default hooks, defined in the IPython.hooks module.
         hooks = IPython.hooks
         for hook_name in hooks.__all__:
             self.set_hook(hook_name,getattr(hooks,hook_name))
 
         # Flag to mark unconditional exit
         self.exit_now = False
 
         self.usage_min =  """\
         An enhanced console for Python.
         Some of its features are:
         - Readline support if the readline library is present.
         - Tab completion in the local namespace.
         - Logging of input, see command-line options.
         - System shell escape via ! , eg !ls.
         - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
         - Keeps track of locally defined variables via %who, %whos.
         - Show object information with a ? eg ?x or x? (use ?? for more info).
         """
         if usage: self.usage = usage
         else: self.usage = self.usage_min
 
         # Storage
         self.rc = rc   # This will hold all configuration information
         self.pager = 'less'
         # temporary files used for various purposes.  Deleted at exit.
         self.tempfiles = []
 
         # Keep track of readline usage (later set by init_readline)
         self.has_readline = False
 
         # template for logfile headers.  It gets resolved at runtime by the
         # logstart method.
         self.loghead_tpl = \
 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
 #log# opts = %s
 #log# args = %s
 #log# It is safe to make manual edits below here.
 #log#-----------------------------------------------------------------------
 """
         # for pushd/popd management
         try:
             self.home_dir = get_home_dir()
         except HomeDirError,msg:
             fatal(msg)
 
         self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
 
         # Functions to call the underlying shell.
 
         # utility to expand user variables via Itpl
         self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
                                                  self.user_ns))
         # The first is similar to os.system, but it doesn't return a value,
         # and it allows interpolation of variables in the user's namespace.
         self.system = lambda cmd: shell(self.var_expand(cmd),
                                         header='IPython system call: ',
                                         verbose=self.rc.system_verbose)
         # These are for getoutput and getoutputerror:
         self.getoutput = lambda cmd: \
                          getoutput(self.var_expand(cmd),
                                    header='IPython system call: ',
                                    verbose=self.rc.system_verbose)
         self.getoutputerror = lambda cmd: \
                               getoutputerror(str(ItplNS(cmd.replace('#','\#'),
                                                         self.user_ns)),
                                              header='IPython system call: ',
                                              verbose=self.rc.system_verbose)
  
         # RegExp for splitting line contents into pre-char//first
         # word-method//rest.  For clarity, each group in on one line.
 
         # WARNING: update the regexp if the above escapes are changed, as they
         # are hardwired in.
 
         # Don't get carried away with trying to make the autocalling catch too
         # much:  it's better to be conservative rather than to trigger hidden
         # evals() somewhere and end up causing side effects.
 
         self.line_split = re.compile(r'^([\s*,;/])'
                                      r'([\?\w\.]+\w*\s*)'
                                      r'(\(?.*$)')
 
         # Original re, keep around for a while in case changes break something
         #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
         #                             r'(\s*[\?\w\.]+\w*\s*)'
         #                             r'(\(?.*$)')
 
         # RegExp to identify potential function names
         self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
         # RegExp to exclude strings with this start from autocalling
         self.re_exclude_auto = re.compile('^[!=()<>,\*/\+-]|^is ')
 
         # try to catch also methods for stuff in lists/tuples/dicts: off
         # (experimental). For this to work, the line_split regexp would need
         # to be modified so it wouldn't break things at '['. That line is
         # nasty enough that I shouldn't change it until I can test it _well_.
         #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
 
         # keep track of where we started running (mainly for crash post-mortem)
         self.starting_dir = os.getcwd()
 
         # Various switches which can be set
         self.CACHELENGTH = 5000  # this is cheap, it's just text
         self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
         self.banner2 = banner2
 
         # TraceBack handlers:
 
         # Syntax error handler.
         self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
         
         # The interactive one is initialized with an offset, meaning we always
         # want to remove the topmost item in the traceback, which is our own
         # internal code. Valid modes: ['Plain','Context','Verbose']
         self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
                                                      color_scheme='NoColor',
                                                      tb_offset = 1)
 
         # IPython itself shouldn't crash. This will produce a detailed
         # post-mortem if it does.  But we only install the crash handler for
         # non-threaded shells, the threaded ones use a normal verbose reporter
         # and lose the crash handler.  This is because exceptions in the main
         # thread (such as in GUI code) propagate directly to sys.excepthook,
         # and there's no point in printing crash dumps for every user exception.
         if self.isthreaded:
             sys.excepthook = ultraTB.FormattedTB()
         else:
             from IPython import CrashHandler
             sys.excepthook = CrashHandler.CrashHandler(self)
 
         # The instance will store a pointer to this, so that runtime code
         # (such as magics) can access it.  This is because during the
         # read-eval loop, it gets temporarily overwritten (to deal with GUI
         # frameworks).
         self.sys_excepthook = sys.excepthook
 
         # and add any custom exception handlers the user may have specified
         self.set_custom_exc(*custom_exceptions)
 
         # Object inspector
         self.inspector = OInspect.Inspector(OInspect.InspectColors,
                                             PyColorize.ANSICodeColors,
                                             'NoColor')
         # indentation management
         self.autoindent = False
         self.indent_current_nsp = 0
         self.indent_current = '' # actual indent string
 
         # Make some aliases automatically
         # Prepare list of shell aliases to auto-define
         if os.name == 'posix':            
             auto_alias = ('mkdir mkdir', 'rmdir rmdir',
                           'mv mv -i','rm rm -i','cp cp -i',
                           'cat cat','less less','clear clear',
                           # a better ls
                           'ls ls -F',
                           # long ls
                           'll ls -lF',
                           # color ls
                           'lc ls -F -o --color',
                           # ls normal files only
                           'lf ls -F -o --color %l | grep ^-',
                           # ls symbolic links 
                           'lk ls -F -o --color %l | grep ^l',
                           # directories or links to directories,
                           'ldir ls -F -o --color %l | grep /$',
                           # things which are executable
                           'lx ls -F -o --color %l | grep ^-..x',
                           )
         elif os.name in ['nt','dos']:
             auto_alias = ('dir dir /on', 'ls dir /on',
                           'ddir dir /ad /on', 'ldir dir /ad /on',
                           'mkdir mkdir','rmdir rmdir','echo echo',
                           'ren ren','cls cls','copy copy')
         else:
             auto_alias = ()
         self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
         # Call the actual (public) initializer
         self.init_auto_alias()
     # end __init__
 
     def post_config_initialization(self):
         """Post configuration init method
 
         This is called after the configuration files have been processed to
         'finalize' the initialization."""
 
         rc = self.rc
         
         # Load readline proper
         if rc.readline:
             self.init_readline()
 
         # log system
         self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
         # local shortcut, this is used a LOT
         self.log = self.logger.log
 
         # Initialize cache, set in/out prompts and printing system
         self.outputcache = CachedOutput(self,
                                         rc.cache_size,
                                         rc.pprint,
                                         input_sep = rc.separate_in,
                                         output_sep = rc.separate_out,
                                         output_sep2 = rc.separate_out2,
                                         ps1 = rc.prompt_in1,
                                         ps2 = rc.prompt_in2,
                                         ps_out = rc.prompt_out,
                                         pad_left = rc.prompts_pad_left)
 
         # user may have over-ridden the default print hook:
         try:
             self.outputcache.__class__.display = self.hooks.display
         except AttributeError:
             pass
 
         # I don't like assigning globally to sys, because it means when embedding
         # instances, each embedded instance overrides the previous choice. But
         # sys.displayhook seems to be called internally by exec, so I don't see a
         # way around it.
         sys.displayhook = self.outputcache
 
         # Set user colors (don't do it in the constructor above so that it
         # doesn't crash if colors option is invalid)
         self.magic_colors(rc.colors)
 
         # Set calling of pdb on exceptions
         self.call_pdb = rc.pdb
 
         # Load user aliases
         for alias in rc.alias:
             self.magic_alias(alias)
 
         # dynamic data that survives through sessions
         # XXX make the filename a config option?
         persist_base = 'persist'
         if rc.profile:
             persist_base += '_%s' % rc.profile
         self.persist_fname =  os.path.join(rc.ipythondir,persist_base)
 
         try:
             self.persist = pickle.load(file(self.persist_fname))
         except:
             self.persist = {}
         
         
         for (key, value) in [(k[2:],v) for (k,v) in self.persist.items() if k.startswith('S:')]:
             try:
                 obj = pickle.loads(value)
             except:
                 
                 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % key
                 print "The error was:",sys.exc_info()[0]
                 continue
                 
             
             self.user_ns[key] = obj
 
     def add_builtins(self):
         """Store ipython references into the builtin namespace.
 
         Some parts of ipython operate via builtins injected here, which hold a
         reference to IPython itself."""
 
         builtins_new  = dict(__IPYTHON__ = self,
                              ip_set_hook = self.set_hook,
                              jobs = self.jobs,
                              ipmagic = self.ipmagic,
                              ipalias = self.ipalias,
                              ipsystem = self.ipsystem,
                              )
         for biname,bival in builtins_new.items():
             try:
                 # store the orignal value so we can restore it
                 self.builtins_added[biname] =  __builtin__.__dict__[biname]
             except KeyError:
                 # or mark that it wasn't defined, and we'll just delete it at
                 # cleanup
                 self.builtins_added[biname] = Undefined
             __builtin__.__dict__[biname] = bival
             
         # Keep in the builtins a flag for when IPython is active.  We set it
         # with setdefault so that multiple nested IPythons don't clobber one
         # another.  Each will increase its value by one upon being activated,
         # which also gives us a way to determine the nesting level.
         __builtin__.__dict__.setdefault('__IPYTHON__active',0)
 
     def clean_builtins(self):
         """Remove any builtins which might have been added by add_builtins, or
         restore overwritten ones to their previous values."""
         for biname,bival in self.builtins_added.items():
             if bival is Undefined:
                 del __builtin__.__dict__[biname]
             else:
                 __builtin__.__dict__[biname] = bival
         self.builtins_added.clear()
     
     def set_hook(self,name,hook):
         """set_hook(name,hook) -> sets an internal IPython hook.
 
         IPython exposes some of its internal API as user-modifiable hooks.  By
         resetting one of these hooks, you can modify IPython's behavior to
         call at runtime your own routines."""
 
         # At some point in the future, this should validate the hook before it
         # accepts it.  Probably at least check that the hook takes the number
         # of args it's supposed to.
         setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
 
     def set_custom_exc(self,exc_tuple,handler):
         """set_custom_exc(exc_tuple,handler)
 
         Set a custom exception handler, which will be called if any of the
         exceptions in exc_tuple occur in the mainloop (specifically, in the
         runcode() method.
 
         Inputs:
 
           - exc_tuple: a *tuple* of valid exceptions to call the defined
           handler for.  It is very important that you use a tuple, and NOT A
           LIST here, because of the way Python's except statement works.  If
           you only want to trap a single exception, use a singleton tuple:
 
             exc_tuple == (MyCustomException,)
 
           - handler: this must be defined as a function with the following
           basic interface: def my_handler(self,etype,value,tb).
 
           This will be made into an instance method (via new.instancemethod)
           of IPython itself, and it will be called if any of the exceptions
           listed in the exc_tuple are caught.  If the handler is None, an
           internal basic one is used, which just prints basic info.
 
         WARNING: by putting in your own exception handler into IPython's main
         execution loop, you run a very good chance of nasty crashes.  This
         facility should only be used if you really know what you are doing."""
 
         assert type(exc_tuple)==type(()) , \
                "The custom exceptions must be given AS A TUPLE."
 
         def dummy_handler(self,etype,value,tb):
             print '*** Simple custom exception handler ***'
             print 'Exception type :',etype
             print 'Exception value:',value
             print 'Traceback      :',tb
             print 'Source code    :','\n'.join(self.buffer)
 
         if handler is None: handler = dummy_handler
 
         self.CustomTB = new.instancemethod(handler,self,self.__class__)
         self.custom_exceptions = exc_tuple
 
     def set_custom_completer(self,completer,pos=0):
         """set_custom_completer(completer,pos=0)
 
         Adds a new custom completer function.
 
         The position argument (defaults to 0) is the index in the completers
         list where you want the completer to be inserted."""
 
         newcomp = new.instancemethod(completer,self.Completer,
                                      self.Completer.__class__)
         self.Completer.matchers.insert(pos,newcomp)
 
     def _get_call_pdb(self):
         return self._call_pdb
 
     def _set_call_pdb(self,val):
 
         if val not in (0,1,False,True):
             raise ValueError,'new call_pdb value must be boolean'
 
         # store value in instance
         self._call_pdb = val
 
         # notify the actual exception handlers
         self.InteractiveTB.call_pdb = val
         if self.isthreaded:
             try:
                 self.sys_excepthook.call_pdb = val
             except:
                 warn('Failed to activate pdb for threaded exception handler')
 
     call_pdb = property(_get_call_pdb,_set_call_pdb,None,
                         'Control auto-activation of pdb at exceptions')
  
 
     # These special functions get installed in the builtin namespace, to
     # provide programmatic (pure python) access to magics, aliases and system
     # calls.  This is important for logging, user scripting, and more.
 
     # We are basically exposing, via normal python functions, the three
     # mechanisms in which ipython offers special call modes (magics for
     # internal control, aliases for direct system access via pre-selected
     # names, and !cmd for calling arbitrary system commands).
 
     def ipmagic(self,arg_s):
         """Call a magic function by name.
 
         Input: a string containing the name of the magic function to call and any
         additional arguments to be passed to the magic.
 
         ipmagic('name -opt foo bar') is equivalent to typing at the ipython
         prompt:
 
         In[1]: %name -opt foo bar
 
         To call a magic without arguments, simply use ipmagic('name').
 
         This provides a proper Python function to call IPython's magics in any
         valid Python code you can type at the interpreter, including loops and
         compound statements.  It is added by IPython to the Python builtin
         namespace upon initialization."""
 
         args = arg_s.split(' ',1)
         magic_name = args[0]
         if magic_name.startswith(self.ESC_MAGIC):
             magic_name = magic_name[1:]
         try:
             magic_args = args[1]
         except IndexError:
             magic_args = ''
         fn = getattr(self,'magic_'+magic_name,None)
         if fn is None:
             error("Magic function `%s` not found." % magic_name)
         else:
             magic_args = self.var_expand(magic_args)
             return fn(magic_args)
 
     def ipalias(self,arg_s):
         """Call an alias by name.
 
         Input: a string containing the name of the alias to call and any
         additional arguments to be passed to the magic.
 
         ipalias('name -opt foo bar') is equivalent to typing at the ipython
         prompt:
 
         In[1]: name -opt foo bar
 
         To call an alias without arguments, simply use ipalias('name').
 
         This provides a proper Python function to call IPython's aliases in any
         valid Python code you can type at the interpreter, including loops and
         compound statements.  It is added by IPython to the Python builtin
         namespace upon initialization."""
 
         args = arg_s.split(' ',1)
         alias_name = args[0]
         try:
             alias_args = args[1]
         except IndexError:
             alias_args = ''
         if alias_name in self.alias_table:
             self.call_alias(alias_name,alias_args)
         else:
             error("Alias `%s` not found." % alias_name)
 
     def ipsystem(self,arg_s):
         """Make a system call, using IPython."""
         self.system(arg_s)
 
     def complete(self,text):
         """Return a sorted list of all possible completions on text.
 
         Inputs:
 
           - text: a string of text to be completed on.
 
         This is a wrapper around the completion mechanism, similar to what
         readline does at the command line when the TAB key is hit.  By
         exposing it as a method, it can be used by other non-readline
         environments (such as GUIs) for text completion.
 
         Simple usage example:
 
         In [1]: x = 'hello'
 
         In [2]: __IP.complete('x.l')
         Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
         
         complete = self.Completer.complete
         state = 0
         # use a dict so we get unique keys, since ipyhton's multiple
         # completers can return duplicates.
         comps = {}
         while True:
             newcomp = complete(text,state)
             if newcomp is None:
                 break
             comps[newcomp] = 1
             state += 1
         outcomps = comps.keys()
         outcomps.sort()
         return outcomps
         
     def set_completer_frame(self, frame):
         if frame:
             self.Completer.namespace = frame.f_locals
             self.Completer.global_namespace = frame.f_globals
         else:
             self.Completer.namespace = self.user_ns
             self.Completer.global_namespace = self.user_global_ns
 
     def init_auto_alias(self):
         """Define some aliases automatically.
 
         These are ALL parameter-less aliases"""
         for alias,cmd in self.auto_alias:
             self.alias_table[alias] = (0,cmd)
 
     def alias_table_validate(self,verbose=0):
         """Update information about the alias table.
 
         In particular, make sure no Python keywords/builtins are in it."""
 
         no_alias = self.no_alias
         for k in self.alias_table.keys():
             if k in no_alias:
                 del self.alias_table[k]
                 if verbose:
                     print ("Deleting alias <%s>, it's a Python "
                            "keyword or builtin." % k)
     
     def set_autoindent(self,value=None):
         """Set the autoindent flag, checking for readline support.
 
         If called with no arguments, it acts as a toggle."""
 
         if not self.has_readline:
             if os.name == 'posix':
                 warn("The auto-indent feature requires the readline library")
             self.autoindent = 0
             return
         if value is None:
             self.autoindent = not self.autoindent
         else:
             self.autoindent = value
 
     def rc_set_toggle(self,rc_field,value=None):
         """Set or toggle a field in IPython's rc config. structure.
 
         If called with no arguments, it acts as a toggle.
 
         If called with a non-existent field, the resulting AttributeError
         exception will propagate out."""
 
         rc_val = getattr(self.rc,rc_field)
         if value is None:
             value = not rc_val
         setattr(self.rc,rc_field,value)
 
     def user_setup(self,ipythondir,rc_suffix,mode='install'):
         """Install the user configuration directory.
 
         Can be called when running for the first time or to upgrade the user's
         .ipython/ directory with the mode parameter. Valid modes are 'install'
         and 'upgrade'."""
 
         def wait():
             try:
                 raw_input("Please press <RETURN> to start IPython.")
             except EOFError:
                 print >> Term.cout
             print '*'*70
 
         cwd = os.getcwd()  # remember where we started
         glb = glob.glob
         print '*'*70
         if mode == 'install':
             print \
 """Welcome to IPython. I will try to create a personal configuration directory
 where you can customize many aspects of IPython's functionality in:\n"""
         else:
             print 'I am going to upgrade your configuration in:'
 
         print ipythondir
 
         rcdirend = os.path.join('IPython','UserConfig')
         cfg = lambda d: os.path.join(d,rcdirend)
         try:
             rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
         except IOError:
             warning = """
 Installation error. IPython's directory was not found.
 
 Check the following:
 
 The ipython/IPython directory should be in a directory belonging to your
 PYTHONPATH environment variable (that is, it should be in a directory
 belonging to sys.path). You can copy it explicitly there or just link to it.
 
 IPython will proceed with builtin defaults.
 """
             warn(warning)
             wait()
             return
 
         if mode == 'install':
             try:
                 shutil.copytree(rcdir,ipythondir)
                 os.chdir(ipythondir)
                 rc_files = glb("ipythonrc*")
                 for rc_file in rc_files:
                     os.rename(rc_file,rc_file+rc_suffix)
             except:
                 warning = """
 
 There was a problem with the installation:
 %s
 Try to correct it or contact the developers if you think it's a bug.
 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
                 warn(warning)
                 wait()
                 return
 
         elif mode == 'upgrade':
             try:
                 os.chdir(ipythondir)
             except:
                 print """
 Can not upgrade: changing to directory %s failed. Details:
 %s
 """ % (ipythondir,sys.exc_info()[1])
                 wait()
                 return
             else:
                 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
                 for new_full_path in sources:
                     new_filename = os.path.basename(new_full_path)
                     if new_filename.startswith('ipythonrc'):
                         new_filename = new_filename + rc_suffix
                     # The config directory should only contain files, skip any
                     # directories which may be there (like CVS)
                     if os.path.isdir(new_full_path):
                         continue
                     if os.path.exists(new_filename):
                         old_file = new_filename+'.old'
                         if os.path.exists(old_file):
                             os.remove(old_file)
                         os.rename(new_filename,old_file)
                     shutil.copy(new_full_path,new_filename)
         else:
             raise ValueError,'unrecognized mode for install:',`mode`
 
         # Fix line-endings to those native to each platform in the config
         # directory.
         try:
             os.chdir(ipythondir)
         except:
             print """
 Problem: changing to directory %s failed.
 Details:
 %s
 
 Some configuration files may have incorrect line endings.  This should not
 cause any problems during execution.  """ % (ipythondir,sys.exc_info()[1])
             wait()
         else:
             for fname in glb('ipythonrc*'):
                 try:
                     native_line_ends(fname,backup=0)
                 except IOError:
                     pass
 
         if mode == 'install':
             print """
 Successful installation!
 
 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
 IPython manual (there are both HTML and PDF versions supplied with the
 distribution) to make sure that your system environment is properly configured
 to take advantage of IPython's features."""
         else:
             print """
 Successful upgrade!
 
 All files in your directory:
 %(ipythondir)s
 which would have been overwritten by the upgrade were backed up with a .old
 extension.  If you had made particular customizations in those files you may
 want to merge them back into the new files.""" % locals()
         wait()
         os.chdir(cwd)
         # end user_setup()
 
     def atexit_operations(self):
         """This will be executed at the time of exit.
 
         Saving of persistent data should be performed here. """
 
         # input history
         self.savehist()
 
         # Cleanup all tempfiles left around
         for tfile in self.tempfiles:
             try:
                 os.unlink(tfile)
             except OSError:
                 pass
 
         # save the "persistent data" catch-all dictionary
         try:
             pickle.dump(self.persist, open(self.persist_fname,"w"))
         except:
             print "*** ERROR *** persistent data saving failed."
         
     def savehist(self):
         """Save input history to a file (via readline library)."""
         try:
             self.readline.write_history_file(self.histfile)
         except:
             print 'Unable to save IPython command history to file: ' + \
                   `self.histfile`
 
     def pre_readline(self):
         """readline hook to be used at the start of each line.
 
         Currently it handles auto-indent only."""
 
         self.readline.insert_text(self.indent_current)
 
     def init_readline(self):
         """Command history completion/saving/reloading."""
         try:
             import readline
         except ImportError:
             self.has_readline = 0
             self.readline = None
             # no point in bugging windows users with this every time:
             if os.name == 'posix':
                 warn('Readline services not available on this platform.')
         else:
             import atexit
             from IPython.completer import IPCompleter
             self.Completer = IPCompleter(self,
                                             self.user_ns,
                                             self.user_global_ns,
                                             self.rc.readline_omit__names,
                                             self.alias_table)
 
             # Platform-specific configuration
             if os.name == 'nt':
                 self.readline_startup_hook = readline.set_pre_input_hook
             else:
                 self.readline_startup_hook = readline.set_startup_hook
 
             # Load user's initrc file (readline config)
             inputrc_name = os.environ.get('INPUTRC')
             if inputrc_name is None:
                 home_dir = get_home_dir()
                 if home_dir is not None:
                     inputrc_name = os.path.join(home_dir,'.inputrc')
             if os.path.isfile(inputrc_name):
                 try:
                     readline.read_init_file(inputrc_name)
                 except:
                     warn('Problems reading readline initialization file <%s>'
                          % inputrc_name)
             
             self.has_readline = 1
             self.readline = readline
             # save this in sys so embedded copies can restore it properly
             sys.ipcompleter = self.Completer.complete
             readline.set_completer(self.Completer.complete)
 
             # Configure readline according to user's prefs
             for rlcommand in self.rc.readline_parse_and_bind:
                 readline.parse_and_bind(rlcommand)
 
             # remove some chars from the delimiters list
             delims = readline.get_completer_delims()
             delims = delims.translate(string._idmap,
                                       self.rc.readline_remove_delims)
             readline.set_completer_delims(delims)
             # otherwise we end up with a monster history after a while:
             readline.set_history_length(1000)
             try:
                 #print '*** Reading readline history'  # dbg
                 readline.read_history_file(self.histfile)
             except IOError:
                 pass  # It doesn't exist yet.
 
             atexit.register(self.atexit_operations)
             del atexit
 
         # Configure auto-indent for all platforms
         self.set_autoindent(self.rc.autoindent)
 
     def _should_recompile(self,e):
         """Utility routine for edit_syntax_error"""
         
         if e.filename in ('<ipython console>','<input>','<string>',
                           '<console>'):
             return False
         try:
             if not ask_yes_no('Return to editor to correct syntax error? '
                               '[Y/n] ','y'):
                 return False
         except EOFError:
             return False
-        self.hooks.fix_error_editor(e.filename,e.lineno,e.offset,e.msg)
+
+        def int0(x):
+            try:
+                return int(x)
+            except TypeError:
+                return 0
+        # always pass integer line and offset values to editor hook
+        self.hooks.fix_error_editor(e.filename,
+            int0(e.lineno),int0(e.offset),e.msg)
         return True
         
     def edit_syntax_error(self):
         """The bottom half of the syntax error handler called in the main loop.
 
         Loop until syntax error is fixed or user cancels.
         """
 
         while self.SyntaxTB.last_syntax_error:
             # copy and clear last_syntax_error
             err = self.SyntaxTB.clear_err_state()
             if not self._should_recompile(err):
                 return
             try:
                 # may set last_syntax_error again if a SyntaxError is raised
                 self.safe_execfile(err.filename,self.shell.user_ns)
             except:
                 self.showtraceback()
             else:
                 f = file(err.filename)
                 try:
                     sys.displayhook(f.read())
                 finally:
                     f.close()
 
     def showsyntaxerror(self, filename=None):
         """Display the syntax error that just occurred.
 
         This doesn't display a stack trace because there isn't one.
 
         If a filename is given, it is stuffed in the exception instead
         of what was there before (because Python's parser always uses
         "<string>" when reading from a string).
         """
         etype, value, last_traceback = sys.exc_info()
         if filename and etype is SyntaxError:
             # Work hard to stuff the correct filename in the exception
             try:
                 msg, (dummy_filename, lineno, offset, line) = value
             except:
                 # Not the format we expect; leave it alone
                 pass
             else:
                 # Stuff in the right filename
                 try:
                     # Assume SyntaxError is a class exception
                     value = SyntaxError(msg, (filename, lineno, offset, line))
                 except:
                     # If that failed, assume SyntaxError is a string
                     value = msg, (filename, lineno, offset, line)
         self.SyntaxTB(etype,value,[])
 
     def debugger(self):
         """Call the pdb debugger."""
 
         if not self.rc.pdb:
             return
         pdb.pm()
 
     def showtraceback(self,exc_tuple = None,filename=None):
         """Display the exception that just occurred."""
 
         # Though this won't be called by syntax errors in the input line,
         # there may be SyntaxError cases whith imported code.
         if exc_tuple is None:
             type, value, tb = sys.exc_info()
         else:
             type, value, tb = exc_tuple
         if type is SyntaxError:
             self.showsyntaxerror(filename)
         else:
             self.InteractiveTB()
             if self.InteractiveTB.call_pdb and self.has_readline:
                 # pdb mucks up readline, fix it back
                 self.readline.set_completer(self.Completer.complete)
 
     def mainloop(self,banner=None):
         """Creates the local namespace and starts the mainloop.
 
         If an optional banner argument is given, it will override the
         internally created default banner."""
         
         if self.rc.c:  # Emulate Python's -c option
             self.exec_init_cmd()
         if banner is None:
             if self.rc.banner:
                 banner = self.BANNER+self.banner2
             else:
                 banner = ''
         self.interact(banner)
 
     def exec_init_cmd(self):
         """Execute a command given at the command line.
 
         This emulates Python's -c option."""
 
         sys.argv = ['-c']
         self.push(self.rc.c)
 
     def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
         """Embeds IPython into a running python program.
 
         Input:
 
           - header: An optional header message can be specified.
 
           - local_ns, global_ns: working namespaces. If given as None, the
           IPython-initialized one is updated with __main__.__dict__, so that
           program variables become visible but user-specific configuration
           remains possible.
 
           - stack_depth: specifies how many levels in the stack to go to
           looking for namespaces (when local_ns and global_ns are None).  This
           allows an intermediate caller to make sure that this function gets
           the namespace from the intended level in the stack.  By default (0)
           it will get its locals and globals from the immediate caller.
 
         Warning: it's possible to use this in a program which is being run by
         IPython itself (via %run), but some funny things will happen (a few
         globals get overwritten). In the future this will be cleaned up, as
         there is no fundamental reason why it can't work perfectly."""
 
         # Get locals and globals from caller
         if local_ns is None or global_ns is None:
             call_frame = sys._getframe(stack_depth).f_back
 
             if local_ns is None:
                 local_ns = call_frame.f_locals
             if global_ns is None:
                 global_ns = call_frame.f_globals
 
         # Update namespaces and fire up interpreter
 
         # The global one is easy, we can just throw it in
         self.user_global_ns = global_ns
 
         # but the user/local one is tricky: ipython needs it to store internal
         # data, but we also need the locals.  We'll copy locals in the user
         # one, but will track what got copied so we can delete them at exit.
         # This is so that a later embedded call doesn't see locals from a
         # previous call (which most likely existed in a separate scope).
         local_varnames = local_ns.keys()
         self.user_ns.update(local_ns)
 
         # Patch for global embedding to make sure that things don't overwrite
         # user globals accidentally. Thanks to Richard <[e-mail]>
         # FIXME. Test this a bit more carefully (the if.. is new)
         if local_ns is None and global_ns is None:
             self.user_global_ns.update(__main__.__dict__)
 
         # make sure the tab-completer has the correct frame information, so it
         # actually completes using the frame's locals/globals
         self.set_completer_frame(call_frame)
 
         # before activating the interactive mode, we need to make sure that
         # all names in the builtin namespace needed by ipython point to
         # ourselves, and not to other instances.
         self.add_builtins()
         
         self.interact(header)
         
         # now, purge out the user namespace from anything we might have added
         # from the caller's local namespace
         delvar = self.user_ns.pop
         for var in local_varnames:
             delvar(var,None)
         # and clean builtins we may have overridden
         self.clean_builtins()
 
     def interact(self, banner=None):
         """Closely emulate the interactive Python console.
 
         The optional banner argument specify the banner to print
         before the first interaction; by default it prints a banner
         similar to the one printed by the real Python interpreter,
         followed by the current class name in parentheses (so as not
         to confuse this with the real interpreter -- since it's so
         close!).
 
         """
         cprt = 'Type "copyright", "credits" or "license" for more information.'
         if banner is None:
             self.write("Python %s on %s\n%s\n(%s)\n" %
                        (sys.version, sys.platform, cprt,
                         self.__class__.__name__))
         else:
             self.write(banner)
 
         more = 0
         
         # Mark activity in the builtins
         __builtin__.__dict__['__IPYTHON__active'] += 1
 
         # exit_now is set by a call to %Exit or %Quit
         self.exit_now = False
         while not self.exit_now:
 
             try:
                 if more:
                     prompt = self.outputcache.prompt2
                     if self.autoindent:
                         self.readline_startup_hook(self.pre_readline)
                 else:
                     prompt = self.outputcache.prompt1
                 try:
                     line = self.raw_input(prompt,more)
                     if self.autoindent:
                         self.readline_startup_hook(None)
                 except EOFError:
                     if self.autoindent:
                         self.readline_startup_hook(None)
                     self.write("\n")
                     self.exit()
                 else:
                     more = self.push(line)
 
                     if (self.SyntaxTB.last_syntax_error and
                         self.rc.autoedit_syntax):
                         self.edit_syntax_error()
 
             except KeyboardInterrupt:
                 self.write("\nKeyboardInterrupt\n")
                 self.resetbuffer()
                 more = 0
                 # keep cache in sync with the prompt counter:
                 self.outputcache.prompt_count -= 1
 
                 if self.autoindent:
                     self.indent_current_nsp = 0
                     self.indent_current = ' '* self.indent_current_nsp
 
             except bdb.BdbQuit:
                 warn("The Python debugger has exited with a BdbQuit exception.\n"
                      "Because of how pdb handles the stack, it is impossible\n"
                      "for IPython to properly format this particular exception.\n"
                      "IPython will resume normal operation.")
             
         # We are off again...
         __builtin__.__dict__['__IPYTHON__active'] -= 1
 
     def excepthook(self, type, value, tb):
       """One more defense for GUI apps that call sys.excepthook.
 
       GUI frameworks like wxPython trap exceptions and call
       sys.excepthook themselves.  I guess this is a feature that
       enables them to keep running after exceptions that would
       otherwise kill their mainloop. This is a bother for IPython
       which excepts to catch all of the program exceptions with a try:
       except: statement.
 
       Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
       any app directly invokes sys.excepthook, it will look to the user like
       IPython crashed.  In order to work around this, we can disable the
       CrashHandler and replace it with this excepthook instead, which prints a
       regular traceback using our InteractiveTB.  In this fashion, apps which
       call sys.excepthook will generate a regular-looking exception from
       IPython, and the CrashHandler will only be triggered by real IPython
       crashes.
 
       This hook should be used sparingly, only in places which are not likely
       to be true IPython errors.
       """
       
       self.InteractiveTB(type, value, tb, tb_offset=0)
       if self.InteractiveTB.call_pdb and self.has_readline:
           self.readline.set_completer(self.Completer.complete)
 
     def call_alias(self,alias,rest=''):
         """Call an alias given its name and the rest of the line.
 
         This function MUST be given a proper alias, because it doesn't make
         any checks when looking up into the alias table.  The caller is
         responsible for invoking it only with a valid alias."""
 
         #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
         nargs,cmd = self.alias_table[alias]
         # Expand the %l special to be the user's input line
         if cmd.find('%l') >= 0:
             cmd = cmd.replace('%l',rest)
             rest = ''
         if nargs==0:
             # Simple, argument-less aliases
             cmd = '%s %s' % (cmd,rest)
         else:
             # Handle aliases with positional arguments
             args = rest.split(None,nargs)
             if len(args)< nargs:
                 error('Alias <%s> requires %s arguments, %s given.' %
                       (alias,nargs,len(args)))
                 return
             cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
         # Now call the macro, evaluating in the user's namespace
         try:
             self.system(cmd)
         except:
             self.showtraceback()
 
     def autoindent_update(self,line):
         """Keep track of the indent level."""
         if self.autoindent:
             if line:
                 ini_spaces = ini_spaces_re.match(line)
                 if ini_spaces:
                     nspaces = ini_spaces.end()
                 else:
                     nspaces = 0
                 self.indent_current_nsp = nspaces
 
                 if line[-1] == ':':
                     self.indent_current_nsp += 4
                 elif dedent_re.match(line):
                     self.indent_current_nsp -= 4
             else:
                 self.indent_current_nsp = 0
 
             # indent_current is the actual string to be inserted
             # by the readline hooks for indentation
             self.indent_current = ' '* self.indent_current_nsp
 
     def runlines(self,lines):
         """Run a string of one or more lines of source.
 
         This method is capable of running a string containing multiple source
         lines, as if they had been entered at the IPython prompt.  Since it
         exposes IPython's processing machinery, the given strings can contain
         magic calls (%magic), special shell access (!cmd), etc."""
 
         # We must start with a clean buffer, in case this is run from an
         # interactive IPython session (via a magic, for example).
         self.resetbuffer()
         lines = lines.split('\n')
         more = 0
         for line in lines:
             # skip blank lines so we don't mess up the prompt counter, but do
             # NOT skip even a blank line if we are in a code block (more is
             # true)
             if line or more:
                 more = self.push(self.prefilter(line,more))
                 # IPython's runsource returns None if there was an error
                 # compiling the code.  This allows us to stop processing right
                 # away, so the user gets the error message at the right place.
                 if more is None:
                     break
         # final newline in case the input didn't have it, so that the code
         # actually does get executed
         if more:
             self.push('\n')
 
     def runsource(self, source, filename='<input>', symbol='single'):
         """Compile and run some source in the interpreter.
 
         Arguments are as for compile_command().
 
         One several things can happen:
 
         1) The input is incorrect; compile_command() raised an
         exception (SyntaxError or OverflowError).  A syntax traceback
         will be printed by calling the showsyntaxerror() method.
 
         2) The input is incomplete, and more input is required;
         compile_command() returned None.  Nothing happens.
 
         3) The input is complete; compile_command() returned a code
         object.  The code is executed by calling self.runcode() (which
         also handles run-time exceptions, except for SystemExit).
 
         The return value is:
 
           - True in case 2
 
           - False in the other cases, unless an exception is raised, where
           None is returned instead.  This can be used by external callers to
           know whether to continue feeding input or not.
 
         The return value can be used to decide whether to use sys.ps1 or
         sys.ps2 to prompt the next line."""
 
         try:
             code = self.compile(source,filename,symbol)
         except (OverflowError, SyntaxError, ValueError):
             # Case 1
             self.showsyntaxerror(filename)
             return None
 
         if code is None:
             # Case 2
             return True
 
         # Case 3
         # We store the code object so that threaded shells and
         # custom exception handlers can access all this info if needed.
         # The source corresponding to this can be obtained from the
         # buffer attribute as '\n'.join(self.buffer).
         self.code_to_run = code
         # now actually execute the code object
         if self.runcode(code) == 0:
             return False
         else:
             return None
 
     def runcode(self,code_obj):
         """Execute a code object.
 
         When an exception occurs, self.showtraceback() is called to display a
         traceback.
 
         Return value: a flag indicating whether the code to be run completed
         successfully:
 
           - 0: successful execution.
           - 1: an error occurred.
         """
 
         # Set our own excepthook in case the user code tries to call it
         # directly, so that the IPython crash handler doesn't get triggered
         old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
 
         # we save the original sys.excepthook in the instance, in case config
         # code (such as magics) needs access to it.
         self.sys_excepthook = old_excepthook
         outflag = 1  # happens in more places, so it's easier as default
         try:
             try:
                 # Embedded instances require separate global/local namespaces
                 # so they can see both the surrounding (local) namespace and
                 # the module-level globals when called inside another function.
                 if self.embedded:
                     exec code_obj in self.user_global_ns, self.user_ns
                 # Normal (non-embedded) instances should only have a single
                 # namespace for user code execution, otherwise functions won't
                 # see interactive top-level globals.
                 else:
                     exec code_obj in self.user_ns
             finally:
                 # Reset our crash handler in place
                 sys.excepthook = old_excepthook
         except SystemExit:
             self.resetbuffer()
             self.showtraceback()
             warn("Type exit or quit to exit IPython "
                  "(%Exit or %Quit do so unconditionally).",level=1)
         except self.custom_exceptions:
             etype,value,tb = sys.exc_info()
             self.CustomTB(etype,value,tb)
         except:
             self.showtraceback()
         else:
             outflag = 0
             if softspace(sys.stdout, 0):
                 print
         # Flush out code object which has been run (and source)
         self.code_to_run = None
         return outflag
         
     def push(self, line):
         """Push a line to the interpreter.
 
         The line should not have a trailing newline; it may have
         internal newlines.  The line is appended to a buffer and the
         interpreter's runsource() method is called with the
         concatenated contents of the buffer as source.  If this
         indicates that the command was executed or invalid, the buffer
         is reset; otherwise, the command is incomplete, and the buffer
         is left as it was after the line was appended.  The return
         value is 1 if more input is required, 0 if the line was dealt
         with in some way (this is the same as runsource()).
         """
 
         # autoindent management should be done here, and not in the
         # interactive loop, since that one is only seen by keyboard input.  We
         # need this done correctly even for code run via runlines (which uses
         # push).
 
         #print 'push line: <%s>' % line  # dbg
         self.autoindent_update(line)
 
         self.buffer.append(line)
         more = self.runsource('\n'.join(self.buffer), self.filename)
         if not more:
             self.resetbuffer()
         return more
 
     def resetbuffer(self):
         """Reset the input buffer."""
         self.buffer[:] = []
 
     def raw_input(self,prompt='',continue_prompt=False):
         """Write a prompt and read a line.
 
         The returned line does not include the trailing newline.
         When the user enters the EOF key sequence, EOFError is raised.
 
         Optional inputs:
 
           - prompt(''): a string to be printed to prompt the user.
 
           - continue_prompt(False): whether this line is the first one or a
           continuation in a sequence of inputs.
         """
 
         line = raw_input_original(prompt)
         # Try to be reasonably smart about not re-indenting pasted input more
         # than necessary.  We do this by trimming out the auto-indent initial
         # spaces, if the user's actual input started itself with whitespace.
         if self.autoindent:
             line2 = line[self.indent_current_nsp:]
             if line2[0:1] in (' ','\t'):
                 line = line2
         return self.prefilter(line,continue_prompt)
         
     def split_user_input(self,line):
         """Split user input into pre-char, function part and rest."""
 
         lsplit = self.line_split.match(line)
         if lsplit is None:  # no regexp match returns None
             try:
                 iFun,theRest = line.split(None,1)
             except ValueError:
                 iFun,theRest = line,''
             pre = re.match('^(\s*)(.*)',line).groups()[0]
         else:
             pre,iFun,theRest = lsplit.groups()
 
         #print 'line:<%s>' % line # dbg
         #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
         return pre,iFun.strip(),theRest
 
     def _prefilter(self, line, continue_prompt):
         """Calls different preprocessors, depending on the form of line."""
 
         # All handlers *must* return a value, even if it's blank ('').
 
         # Lines are NOT logged here. Handlers should process the line as
         # needed, update the cache AND log it (so that the input cache array
         # stays synced).
 
         # This function is _very_ delicate, and since it's also the one which
         # determines IPython's response to user input, it must be as efficient
         # as possible.  For this reason it has _many_ returns in it, trying
         # always to exit as quickly as it can figure out what it needs to do.
 
         # This function is the main responsible for maintaining IPython's
         # behavior respectful of Python's semantics.  So be _very_ careful if
         # making changes to anything here.
 
         #.....................................................................
         # Code begins
 
         #if line.startswith('%crash'): raise RuntimeError,'Crash now!'  # dbg
 
         # save the line away in case we crash, so the post-mortem handler can
         # record it
         self._last_input_line = line
 
         #print '***line: <%s>' % line # dbg
         
         # the input history needs to track even empty lines
         if not line.strip():
             if not continue_prompt:
                 self.outputcache.prompt_count -= 1
             return self.handle_normal(line,continue_prompt)
             #return self.handle_normal('',continue_prompt)
 
         # print '***cont',continue_prompt  # dbg
         # special handlers are only allowed for single line statements
         if continue_prompt and not self.rc.multi_line_specials:
             return self.handle_normal(line,continue_prompt)
 
         # For the rest, we need the structure of the input
         pre,iFun,theRest = self.split_user_input(line)
         #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest)  # dbg
 
         # First check for explicit escapes in the last/first character
         handler = None
         if line[-1] == self.ESC_HELP:
             handler = self.esc_handlers.get(line[-1])  # the ? can be at the end
         if handler is None:
             # look at the first character of iFun, NOT of line, so we skip
             # leading whitespace in multiline input
             handler = self.esc_handlers.get(iFun[0:1])
         if handler is not None:
             return handler(line,continue_prompt,pre,iFun,theRest)
         # Emacs ipython-mode tags certain input lines
         if line.endswith('# PYTHON-MODE'):
             return self.handle_emacs(line,continue_prompt)
 
         # Next, check if we can automatically execute this thing
 
         # Allow ! in multi-line statements if multi_line_specials is on:
         if continue_prompt and self.rc.multi_line_specials and \
                iFun.startswith(self.ESC_SHELL):
             return self.handle_shell_escape(line,continue_prompt,
                                             pre=pre,iFun=iFun,
                                             theRest=theRest)
 
         # Let's try to find if the input line is a magic fn
         oinfo = None
         if hasattr(self,'magic_'+iFun):
             # WARNING: _ofind uses getattr(), so it can consume generators and
             # cause other side effects.
             oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
             if oinfo['ismagic']:
                 # Be careful not to call magics when a variable assignment is
                 # being made (ls='hi', for example)
                 if self.rc.automagic and \
                        (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
                        (self.rc.multi_line_specials or not continue_prompt):
                     return self.handle_magic(line,continue_prompt,
                                              pre,iFun,theRest)
                 else:
                     return self.handle_normal(line,continue_prompt)
 
         # If the rest of the line begins with an (in)equality, assginment or
         # function call, we should not call _ofind but simply execute it.
         # This avoids spurious geattr() accesses on objects upon assignment.
         #
         # It also allows users to assign to either alias or magic names true
         # python variables (the magic/alias systems always take second seat to
         # true python code).
         if theRest and theRest[0] in '!=()':
             return self.handle_normal(line,continue_prompt)
 
         if oinfo is None:
             # let's try to ensure that _oinfo is ONLY called when autocall is
             # on.  Since it has inevitable potential side effects, at least
             # having autocall off should be a guarantee to the user that no
             # weird things will happen.
 
             if self.rc.autocall:
                 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
             else:
                 # in this case, all that's left is either an alias or
                 # processing the line normally.
                 if iFun in self.alias_table:
                     return self.handle_alias(line,continue_prompt,
                                              pre,iFun,theRest)
                 else:
                     return self.handle_normal(line,continue_prompt)
         
         if not oinfo['found']:
             return self.handle_normal(line,continue_prompt)
         else:
             #print 'iFun <%s> rest <%s>' % (iFun,theRest) # dbg
             if oinfo['isalias']:
                 return self.handle_alias(line,continue_prompt,
                                              pre,iFun,theRest)
 
             if self.rc.autocall and \
                    not self.re_exclude_auto.match(theRest) and \
                    self.re_fun_name.match(iFun) and \
                    callable(oinfo['obj']) :
                 #print 'going auto'  # dbg
                 return self.handle_auto(line,continue_prompt,
                                         pre,iFun,theRest,oinfo['obj'])
             else:
                 #print 'was callable?', callable(oinfo['obj'])  # dbg
                 return self.handle_normal(line,continue_prompt)
 
         # If we get here, we have a normal Python line. Log and return.
         return self.handle_normal(line,continue_prompt)
 
     def _prefilter_dumb(self, line, continue_prompt):
         """simple prefilter function, for debugging"""
         return self.handle_normal(line,continue_prompt)
 
     # Set the default prefilter() function (this can be user-overridden)
     prefilter = _prefilter
 
     def handle_normal(self,line,continue_prompt=None,
                       pre=None,iFun=None,theRest=None):
         """Handle normal input lines. Use as a template for handlers."""
 
         # With autoindent on, we need some way to exit the input loop, and I
         # don't want to force the user to have to backspace all the way to
         # clear the line.  The rule will be in this case, that either two
         # lines of pure whitespace in a row, or a line of pure whitespace but
         # of a size different to the indent level, will exit the input loop.
         
         if (continue_prompt and self.autoindent and isspace(line) and
             (line != self.indent_current or isspace(self.buffer[-1]))):
             line = ''
 
         self.log(line,continue_prompt)
         return line
 
     def handle_alias(self,line,continue_prompt=None,
                      pre=None,iFun=None,theRest=None):
         """Handle alias input lines. """
 
         # pre is needed, because it carries the leading whitespace.  Otherwise
         # aliases won't work in indented sections.
         line_out = '%sipalias("%s %s")' % (pre,iFun,esc_quotes(theRest))
         self.log(line_out,continue_prompt)
         return line_out
 
     def handle_shell_escape(self, line, continue_prompt=None,
                             pre=None,iFun=None,theRest=None):
         """Execute the line in a shell, empty return value"""
 
         #print 'line in :', `line` # dbg
         # Example of a special handler. Others follow a similar pattern.
         if continue_prompt:  # multi-line statements
             if iFun.startswith('!!'):
                 print 'SyntaxError: !! is not allowed in multiline statements'
                 return pre
             else:
                 cmd = ("%s %s" % (iFun[1:],theRest))
                 line_out = '%sipsystem(r"""%s"""[:-1])' % (pre,cmd + "_")
         else: # single-line input
             if line.startswith('!!'):
                 # rewrite iFun/theRest to properly hold the call to %sx and
                 # the actual command to be executed, so handle_magic can work
                 # correctly
                 theRest = '%s %s' % (iFun[2:],theRest)
                 iFun = 'sx'
                 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,line[2:]),
                                          continue_prompt,pre,iFun,theRest)
             else:
                 cmd=line[1:]
                 line_out = '%sipsystem(r"""%s"""[:-1])' % (pre,cmd +"_")
         # update cache/log and return
         self.log(line_out,continue_prompt)
         return line_out
 
     def handle_magic(self, line, continue_prompt=None,
                      pre=None,iFun=None,theRest=None):
         """Execute magic functions.
 
         Also log them with a prepended # so the log is clean Python."""
 
         cmd = '%sipmagic("%s")' % (pre,esc_quotes('%s %s' % (iFun,theRest)))
         self.log(cmd,continue_prompt)
         #print 'in handle_magic, cmd=<%s>' % cmd  # dbg
         return cmd
 
     def handle_auto(self, line, continue_prompt=None,
                     pre=None,iFun=None,theRest=None,obj=None):
         """Hande lines which can be auto-executed, quoting if requested."""
 
         #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest)  # dbg
         
         # This should only be active for single-line input!
         if continue_prompt:
             self.log(line,continue_prompt)
             return line
 
         auto_rewrite = True
         if pre == self.ESC_QUOTE:
             # Auto-quote splitting on whitespace
             newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
         elif pre == self.ESC_QUOTE2:
             # Auto-quote whole string
             newcmd = '%s("%s")' % (iFun,theRest)
         else:
             # Auto-paren.
             # We only apply it to argument-less calls if the autocall
             # parameter is set to 2.  We only need to check that autocall is <
             # 2, since this function isn't called unless it's at least 1.
             if not theRest and (self.rc.autocall < 2):
                 newcmd = '%s %s' % (iFun,theRest)
                 auto_rewrite = False
             else:
                 if theRest.startswith('['):
                     if hasattr(obj,'__getitem__'):
                         # Don't autocall in this case: item access for an object
                         # which is BOTH callable and implements __getitem__.
                         newcmd = '%s %s' % (iFun,theRest)
                         auto_rewrite = False
                     else:
                         # if the object doesn't support [] access, go ahead and
                         # autocall
                         newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
                 elif theRest.endswith(';'):
                     newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
                 else:
                     newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
 
         if auto_rewrite:
             print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
         # log what is now valid Python, not the actual user input (without the
         # final newline)
         self.log(newcmd,continue_prompt)
         return newcmd
 
     def handle_help(self, line, continue_prompt=None,
                     pre=None,iFun=None,theRest=None):
         """Try to get some help for the object.
 
         obj? or ?obj   -> basic information.
         obj?? or ??obj -> more details.
         """
 
         # We need to make sure that we don't process lines which would be
         # otherwise valid python, such as "x=1 # what?"
         try:
             codeop.compile_command(line)
         except SyntaxError:
             # We should only handle as help stuff which is NOT valid syntax
             if line[0]==self.ESC_HELP:
                 line = line[1:]
             elif line[-1]==self.ESC_HELP:
                 line = line[:-1]
             self.log('#?'+line)
             if line:
                 self.magic_pinfo(line)
             else:
                 page(self.usage,screen_lines=self.rc.screen_length)
             return '' # Empty string is needed here!
         except:
             # Pass any other exceptions through to the normal handler
             return self.handle_normal(line,continue_prompt)
         else:
             # If the code compiles ok, we should handle it normally
             return self.handle_normal(line,continue_prompt)
 
     def handle_emacs(self,line,continue_prompt=None,
                     pre=None,iFun=None,theRest=None):
         """Handle input lines marked by python-mode."""
 
         # Currently, nothing is done.  Later more functionality can be added
         # here if needed.
 
         # The input cache shouldn't be updated
 
         return line
 
     def mktempfile(self,data=None):
         """Make a new tempfile and return its filename.
 
         This makes a call to tempfile.mktemp, but it registers the created
         filename internally so ipython cleans it up at exit time.
 
         Optional inputs:
 
           - data(None): if data is given, it gets written out to the temp file
           immediately, and the file is closed again."""
 
         filename = tempfile.mktemp('.py')
         self.tempfiles.append(filename)
         
         if data:
             tmp_file = open(filename,'w')
             tmp_file.write(data)
             tmp_file.close()
         return filename
 
     def write(self,data):
         """Write a string to the default output"""
         Term.cout.write(data)
 
     def write_err(self,data):
         """Write a string to the default error output"""
         Term.cerr.write(data)
 
     def exit(self):
         """Handle interactive exit.
 
         This method sets the exit_now attribute."""
 
         if self.rc.confirm_exit:
             if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
                 self.exit_now = True
         else:
             self.exit_now = True
         return self.exit_now
 
     def safe_execfile(self,fname,*where,**kw):
         fname = os.path.expanduser(fname)
 
         # find things also in current directory
         dname = os.path.dirname(fname)
         if not sys.path.count(dname):
             sys.path.append(dname)
 
         try:
             xfile = open(fname)
         except:
             print >> Term.cerr, \
                   'Could not open file <%s> for safe execution.' % fname
             return None
 
         kw.setdefault('islog',0)
         kw.setdefault('quiet',1)
         kw.setdefault('exit_ignore',0)
         first = xfile.readline()
         loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
         xfile.close()
         # line by line execution
         if first.startswith(loghead) or kw['islog']:
             print 'Loading log file <%s> one line at a time...' % fname
             if kw['quiet']:
                 stdout_save = sys.stdout
                 sys.stdout = StringIO.StringIO()
             try:
                 globs,locs = where[0:2]
             except:
                 try:
                     globs = locs = where[0]
                 except:
                     globs = locs = globals()
             badblocks = []
 
             # we also need to identify indented blocks of code when replaying
             # logs and put them together before passing them to an exec
             # statement. This takes a bit of regexp and look-ahead work in the
             # file. It's easiest if we swallow the whole thing in memory
             # first, and manually walk through the lines list moving the
             # counter ourselves.
             indent_re = re.compile('\s+\S')
             xfile = open(fname)
             filelines = xfile.readlines()
             xfile.close()
             nlines = len(filelines)
             lnum = 0
             while lnum < nlines:
                 line = filelines[lnum]
                 lnum += 1
                 # don't re-insert logger status info into cache
                 if line.startswith('#log#'):
                     continue
                 else:
                     # build a block of code (maybe a single line) for execution
                     block = line
                     try:
                         next = filelines[lnum] # lnum has already incremented
                     except:
                         next = None
                     while next and indent_re.match(next):
                         block += next
                         lnum += 1
                         try:
                             next = filelines[lnum]
                         except:
                             next = None
                     # now execute the block of one or more lines
                     try:
                         exec block in globs,locs
                     except SystemExit:
                         pass
                     except:
                         badblocks.append(block.rstrip())
             if kw['quiet']:  # restore stdout
                 sys.stdout.close()
                 sys.stdout = stdout_save
             print 'Finished replaying log file <%s>' % fname
             if badblocks:
                 print >> sys.stderr, ('\nThe following lines/blocks in file '
                                       '<%s> reported errors:' % fname)
                     
                 for badline in badblocks:
                     print >> sys.stderr, badline
         else:  # regular file execution
             try:
                 execfile(fname,*where)
             except SyntaxError:
                 etype,evalue = sys.exc_info()[:2]
                 self.SyntaxTB(etype,evalue,[])
                 warn('Failure executing file: <%s>' % fname)
             except SystemExit,status:
                 if not kw['exit_ignore']:
                     self.InteractiveTB()
                     warn('Failure executing file: <%s>' % fname)
             except:
                 self.InteractiveTB()
                 warn('Failure executing file: <%s>' % fname)
 
 #************************* end of file <iplib.py> *****************************

IPython/ipmaker.py

@@ -1,701 +1,701 b''
 # -*- coding: utf-8 -*-
 """
 IPython -- An enhanced Interactive Python
 
 Requires Python 2.1 or better.
 
 This file contains the main make_IPython() starter function.
 
-$Id: ipmaker.py 990 2006-01-04 06:59:02Z fperez $"""
+$Id: ipmaker.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+#       Copyright (C) 2001-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 __version__ = Release.version
 
 credits._Printer__data = """
 Python: %s
 
 IPython: Fernando Perez, Janko Hauser, Nathan Gray, and many users.
 See http://ipython.scipy.org for more information.""" \
 % credits._Printer__data
 
 copyright._Printer__data += """
 
 Copyright (c) 2001-2004 Fernando Perez, Janko Hauser, Nathan Gray.
 All Rights Reserved."""
 
 #****************************************************************************
 # Required modules
 
 # From the standard library
 import __main__
 import __builtin__
 import os
 import re
 import sys
 import types
 from pprint import pprint,pformat
 
 # Our own
 from IPython import DPyGetOpt
 from IPython.Struct import Struct
 from IPython.OutputTrap import OutputTrap
 from IPython.ConfigLoader import ConfigLoader
 from IPython.iplib import InteractiveShell
 from IPython.usage import cmd_line_usage,interactive_usage
 from IPython.genutils import *
 
 #-----------------------------------------------------------------------------
 def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,
                  rc_override=None,shell_class=InteractiveShell,
                  embedded=False,**kw):
     """This is a dump of IPython into a single function.
 
     Later it will have to be broken up in a sensible manner.
 
     Arguments:
 
     - argv: a list similar to sys.argv[1:].  It should NOT contain the desired
     script name, b/c DPyGetOpt strips the first argument only for the real
     sys.argv.
 
     - user_ns: a dict to be used as the user's namespace."""
 
     #----------------------------------------------------------------------
     # Defaults and initialization
     
     # For developer debugging, deactivates crash handler and uses pdb.
     DEVDEBUG = False
 
     if argv is None:
         argv = sys.argv
 
     # __IP is the main global that lives throughout and represents the whole
     # application. If the user redefines it, all bets are off as to what
     # happens.
 
     # __IP is the name of he global which the caller will have accessible as
     # __IP.name. We set its name via the first parameter passed to
     # InteractiveShell:
 
     IP = shell_class('__IP',user_ns=user_ns,user_global_ns=user_global_ns,
                      embedded=embedded,**kw)
 
     # Put 'help' in the user namespace
     from site import _Helper
     IP.user_ns['help'] = _Helper()
 
 
     if DEVDEBUG:
         # For developer debugging only (global flag)
         from IPython import ultraTB
         sys.excepthook = ultraTB.VerboseTB(call_pdb=1)
 
     IP.BANNER_PARTS = ['Python %s\n'
                          'Type "copyright", "credits" or "license" '
                          'for more information.\n'
                          % (sys.version.split('\n')[0],),
                          "IPython %s -- An enhanced Interactive Python."
                          % (__version__,),
 """?       -> Introduction to IPython's features.
 %magic  -> Information about IPython's 'magic' % functions.
 help    -> Python's own help system.
 object? -> Details about 'object'. ?object also works, ?? prints more.
 """ ]
 
     IP.usage = interactive_usage
 
     # Platform-dependent suffix and directory names.  We use _ipython instead
     # of .ipython under win32 b/c there's software that breaks with .named
     # directories on that platform.
     if os.name == 'posix':
         rc_suffix = ''
         ipdir_def = '.ipython'
     else:
         rc_suffix = '.ini'
         ipdir_def = '_ipython'
 
     # default directory for configuration
     ipythondir = os.path.abspath(os.environ.get('IPYTHONDIR',
                                  os.path.join(IP.home_dir,ipdir_def)))
 
     # we need the directory where IPython itself is installed
     import IPython
     IPython_dir = os.path.dirname(IPython.__file__)
     del IPython
     
     #-------------------------------------------------------------------------
     # Command line handling
 
     # Valid command line options (uses DPyGetOpt syntax, like Perl's
     # GetOpt::Long)
 
     # Any key not listed here gets deleted even if in the file (like session
     # or profile). That's deliberate, to maintain the rc namespace clean.
 
     # Each set of options appears twice: under _conv only the names are
     # listed, indicating which type they must be converted to when reading the
     # ipythonrc file. And under DPyGetOpt they are listed with the regular
     # DPyGetOpt syntax (=s,=i,:f,etc).
 
     # Make sure there's a space before each end of line (they get auto-joined!)
     cmdline_opts = ('autocall=i autoindent! automagic! banner! cache_size|cs=i '
                     'c=s classic|cl color_info! colors=s confirm_exit! '
                     'debug! deep_reload! editor=s log|l messages! nosep pdb! '
                     'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
                     'quick screen_length|sl=i prompts_pad_left=i '
                     'logfile|lf=s logplay|lp=s profile|p=s '
                     'readline! readline_merge_completions! '
                     'readline_omit__names! '
                     'rcfile=s separate_in|si=s separate_out|so=s '
                     'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
                     'magic_docstrings system_verbose! '
                     'multi_line_specials! '
                     'autoedit_syntax!')
 
     # Options that can *only* appear at the cmd line (not in rcfiles).
     
     # The "ignore" option is a kludge so that Emacs buffers don't crash, since
     # the 'C-c !' command in emacs automatically appends a -i option at the end.
     cmdline_only = ('help ignore|i ipythondir=s Version upgrade '
                     'gthread! qthread! wthread! pylab! tk!')
 
     # Build the actual name list to be used by DPyGetOpt
     opts_names = qw(cmdline_opts) + qw(cmdline_only)
 
     # Set sensible command line defaults.
     # This should have everything from  cmdline_opts and cmdline_only
     opts_def = Struct(autocall = 1,
                       autoedit_syntax = 1,
                       autoindent=0,
                       automagic = 1,
                       banner = 1,
                       cache_size = 1000,
                       c = '',
                       classic = 0,
                       colors = 'NoColor',
                       color_info = 0,
                       confirm_exit = 1,
                       debug = 0,
                       deep_reload = 0,
                       editor = '0',
                       help = 0,
                       ignore = 0,
                       ipythondir = ipythondir,
                       log = 0,
                       logfile = '',
                       logplay = '',
                       multi_line_specials = 1,
                       messages = 1,
                       nosep = 0,
                       pdb = 0,
                       pprint = 0,
                       profile = '',
                       prompt_in1 = 'In [\\#]: ',
                       prompt_in2 = '   .\\D.: ',
                       prompt_out = 'Out[\\#]: ',
                       prompts_pad_left = 1,
                       quick = 0,
                       readline = 1,
                       readline_merge_completions = 1,
                       readline_omit__names = 0,
                       rcfile = 'ipythonrc' + rc_suffix,
                       screen_length = 0,
                       separate_in = '\n',
                       separate_out = '\n',
                       separate_out2 = '',
                       system_verbose = 0,
                       gthread = 0,
                       qthread = 0,
                       wthread = 0,
                       pylab = 0,
                       tk = 0,
                       upgrade = 0,
                       Version = 0,
                       xmode = 'Verbose',
                       wildcards_case_sensitive = 1,
                       magic_docstrings = 0,  # undocumented, for doc generation
                       )
     
     # Things that will *only* appear in rcfiles (not at the command line).
     # Make sure there's a space before each end of line (they get auto-joined!)
     rcfile_opts = { qwflat: 'include import_mod import_all execfile ',
                     qw_lol: 'import_some ',
                     # for things with embedded whitespace:
                     list_strings:'execute alias readline_parse_and_bind ',
                     # Regular strings need no conversion:
                     None:'readline_remove_delims ',
                     }
     # Default values for these
     rc_def = Struct(include = [],
                     import_mod = [], 
                     import_all = [],
                     import_some = [[]],
                     execute = [],
                     execfile = [],
                     alias = [],
                     readline_parse_and_bind = [],
                     readline_remove_delims = '',
                     )
 
     # Build the type conversion dictionary from the above tables:
     typeconv = rcfile_opts.copy()
     typeconv.update(optstr2types(cmdline_opts))
 
     # FIXME: the None key appears in both, put that back together by hand. Ugly!
     typeconv[None] += ' ' + rcfile_opts[None]
 
     # Remove quotes at ends of all strings (used to protect spaces)
     typeconv[unquote_ends] = typeconv[None]
     del typeconv[None]
 
     # Build the list we'll use to make all config decisions with defaults:
     opts_all = opts_def.copy()
     opts_all.update(rc_def)
 
     # Build conflict resolver for recursive loading of config files:
     # - preserve means the outermost file maintains the value, it is not
     # overwritten if an included file has the same key.
     # - add_flip applies + to the two values, so it better make sense to add
     # those types of keys. But it flips them first so that things loaded
     # deeper in the inclusion chain have lower precedence.
     conflict = {'preserve': ' '.join([ typeconv[int],
                                        typeconv[unquote_ends] ]),
                 'add_flip': ' '.join([ typeconv[qwflat],
                                        typeconv[qw_lol],
                                        typeconv[list_strings] ])
                 }
 
     # Now actually process the command line
     getopt = DPyGetOpt.DPyGetOpt()
     getopt.setIgnoreCase(0)
 
     getopt.parseConfiguration(opts_names)
 
     try:
         getopt.processArguments(argv)
     except:
         print cmd_line_usage
         warn('\nError in Arguments: ' + `sys.exc_value`)
         sys.exit(1)
 
     # convert the options dict to a struct for much lighter syntax later
     opts = Struct(getopt.optionValues)
     args = getopt.freeValues
 
     # this is the struct (which has default values at this point) with which
     # we make all decisions:
     opts_all.update(opts)
 
     # Options that force an immediate exit
     if opts_all.help:
         page(cmd_line_usage)
         sys.exit()
 
     if opts_all.Version:
         print __version__
         sys.exit()
 
     if opts_all.magic_docstrings:
         IP.magic_magic('-latex')
         sys.exit()
 
     # Create user config directory if it doesn't exist. This must be done
     # *after* getting the cmd line options.
     if not os.path.isdir(opts_all.ipythondir):
         IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
 
     # upgrade user config files while preserving a copy of the originals
     if opts_all.upgrade:
         IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
 
     # check mutually exclusive options in the *original* command line
     mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
                      qw('classic profile'),qw('classic rcfile')])
 
     #---------------------------------------------------------------------------
     # Log replay
     
     # if -logplay, we need to 'become' the other session. That basically means
     # replacing the current command line environment with that of the old
     # session and moving on.
 
     # this is needed so that later we know we're in session reload mode, as
     # opts_all will get overwritten:
     load_logplay = 0
 
     if opts_all.logplay:
         load_logplay = opts_all.logplay 
         opts_debug_save = opts_all.debug
         try:
             logplay = open(opts_all.logplay)
         except IOError:
             if opts_all.debug: IP.InteractiveTB()
             warn('Could not open logplay file '+`opts_all.logplay`)
             # restore state as if nothing had happened and move on, but make
             # sure that later we don't try to actually load the session file
             logplay = None
             load_logplay = 0
             del opts_all.logplay
         else:
             try: 
                 logplay.readline()
                 logplay.readline();
                 # this reloads that session's command line
                 cmd = logplay.readline()[6:] 
                 exec cmd
                 # restore the true debug flag given so that the process of
                 # session loading itself can be monitored.
                 opts.debug = opts_debug_save
                 # save the logplay flag so later we don't overwrite the log
                 opts.logplay = load_logplay
                 # now we must update our own structure with defaults
                 opts_all.update(opts)
                 # now load args
                 cmd = logplay.readline()[6:] 
                 exec cmd
                 logplay.close()
             except:
                 logplay.close()
                 if opts_all.debug: IP.InteractiveTB()
                 warn("Logplay file lacking full configuration information.\n"
                      "I'll try to read it, but some things may not work.")
 
     #-------------------------------------------------------------------------
     # set up output traps: catch all output from files, being run, modules
     # loaded, etc. Then give it to the user in a clean form at the end.
     
     msg_out = 'Output messages. '
     msg_err = 'Error messages. '
     msg_sep = '\n'
     msg = Struct(config    = OutputTrap('Configuration Loader',msg_out,
                                         msg_err,msg_sep,debug,
                                         quiet_out=1),
                  user_exec = OutputTrap('User File Execution',msg_out,
                                         msg_err,msg_sep,debug),
                  logplay   = OutputTrap('Log Loader',msg_out,
                                         msg_err,msg_sep,debug),
                  summary = ''
                  )
 
     #-------------------------------------------------------------------------
     # Process user ipythonrc-type configuration files
 
     # turn on output trapping and log to msg.config
     # remember that with debug on, trapping is actually disabled
     msg.config.trap_all()
 
     # look for rcfile in current or default directory
     try:
         opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
     except IOError:
         if opts_all.debug:  IP.InteractiveTB()
         warn('Configuration file %s not found. Ignoring request.'
              % (opts_all.rcfile) )
 
     # 'profiles' are a shorthand notation for config filenames
     if opts_all.profile:
         try:
             opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
                                        + rc_suffix,
                                        opts_all.ipythondir)
         except IOError:
            if opts_all.debug:  IP.InteractiveTB()
            opts.profile = ''  # remove profile from options if invalid
            warn('Profile configuration file %s not found. Ignoring request.'
                 % (opts_all.profile) )
 
     # load the config file
     rcfiledata = None
     if opts_all.quick:
         print 'Launching IPython in quick mode. No config file read.'
     elif opts_all.classic:
         print 'Launching IPython in classic mode. No config file read.'
     elif opts_all.rcfile:
         try:
             cfg_loader = ConfigLoader(conflict)
             rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
                                          'include',opts_all.ipythondir,
                                          purge = 1,
                                          unique = conflict['preserve'])
         except:
             IP.InteractiveTB()
             warn('Problems loading configuration file '+
                  `opts_all.rcfile`+
                  '\nStarting with default -bare bones- configuration.')
     else:
         warn('No valid configuration file found in either currrent directory\n'+
              'or in the IPython config. directory: '+`opts_all.ipythondir`+
              '\nProceeding with internal defaults.')
 
     #------------------------------------------------------------------------
     # Set exception handlers in mode requested by user.
     otrap = OutputTrap(trap_out=1)  # trap messages from magic_xmode
     IP.magic_xmode(opts_all.xmode)
     otrap.release_out()
 
     #------------------------------------------------------------------------
     # Execute user config
 
     # Create a valid config structure with the right precedence order:
     # defaults < rcfile < command line.  This needs to be in the instance, so
     # that method calls below that rely on it find it.
     IP.rc = rc_def.copy()
 
     # Work with a local alias inside this routine to avoid unnecessary
     # attribute lookups.
     IP_rc = IP.rc
     
     IP_rc.update(opts_def)
     if rcfiledata:
         # now we can update 
         IP_rc.update(rcfiledata)
     IP_rc.update(opts)
     IP_rc.update(rc_override)
 
     # Store the original cmd line for reference:
     IP_rc.opts = opts
     IP_rc.args = args
 
     # create a *runtime* Struct like rc for holding parameters which may be
     # created and/or modified by runtime user extensions.
     IP.runtime_rc = Struct()
 
     # from this point on, all config should be handled through IP_rc,
     # opts* shouldn't be used anymore.
 
     # add personal .ipython dir to sys.path so that users can put things in
     # there for customization
     sys.path.append(IP_rc.ipythondir)
     sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
     
     # update IP_rc with some special things that need manual
     # tweaks. Basically options which affect other options. I guess this
     # should just be written so that options are fully orthogonal and we
     # wouldn't worry about this stuff!
 
     if IP_rc.classic:
         IP_rc.quick = 1
         IP_rc.cache_size = 0
         IP_rc.pprint = 0
         IP_rc.prompt_in1 = '>>> '
         IP_rc.prompt_in2 = '... '
         IP_rc.prompt_out = ''
         IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
         IP_rc.colors = 'NoColor'
         IP_rc.xmode = 'Plain'
 
     # configure readline
     # Define the history file for saving commands in between sessions
     if IP_rc.profile:
         histfname = 'history-%s' % IP_rc.profile
     else:
         histfname = 'history'
     IP.histfile = os.path.join(opts_all.ipythondir,histfname)
 
     # update exception handlers with rc file status
     otrap.trap_out()  # I don't want these messages ever.
     IP.magic_xmode(IP_rc.xmode)
     otrap.release_out()
 
     # activate logging if requested and not reloading a log
     if IP_rc.logplay:
         IP.magic_logstart(IP_rc.logplay + ' append')
     elif  IP_rc.logfile:
         IP.magic_logstart(IP_rc.logfile)
     elif IP_rc.log:
         IP.magic_logstart()
 
     # find user editor so that it we don't have to look it up constantly
     if IP_rc.editor.strip()=='0':
         try:
             ed = os.environ['EDITOR']
         except KeyError:
             if os.name == 'posix':
                 ed = 'vi'  # the only one guaranteed to be there!
             else:
                 ed = 'notepad' # same in Windows!
         IP_rc.editor = ed
 
     # Keep track of whether this is an embedded instance or not (useful for
     # post-mortems).
     IP_rc.embedded = IP.embedded
 
     # Recursive reload
     try:
         from IPython import deep_reload
         if IP_rc.deep_reload:
             __builtin__.reload = deep_reload.reload
         else:
             __builtin__.dreload = deep_reload.reload
         del deep_reload
     except ImportError:
         pass
 
     # Save the current state of our namespace so that the interactive shell
     # can later know which variables have been created by us from config files
     # and loading. This way, loading a file (in any way) is treated just like
     # defining things on the command line, and %who works as expected.
 
     # DON'T do anything that affects the namespace beyond this point!
     IP.internal_ns.update(__main__.__dict__)
 
     #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
 
     # Now run through the different sections of the users's config
     if IP_rc.debug:
         print 'Trying to execute the following configuration structure:'
         print '(Things listed first are deeper in the inclusion tree and get'
         print 'loaded first).\n'
         pprint(IP_rc.__dict__)
         
     for mod in IP_rc.import_mod:
         try:
             exec 'import '+mod in IP.user_ns
         except :
             IP.InteractiveTB()
             import_fail_info(mod)
 
     for mod_fn in IP_rc.import_some:
         if mod_fn == []: break
         mod,fn = mod_fn[0],','.join(mod_fn[1:])
         try:
             exec 'from '+mod+' import '+fn in IP.user_ns
         except :
             IP.InteractiveTB()
             import_fail_info(mod,fn)
 
     for mod in IP_rc.import_all:
         try:
             exec 'from '+mod+' import *' in IP.user_ns
         except :
             IP.InteractiveTB()
             import_fail_info(mod)
 
     for code in IP_rc.execute:
         try:
             exec code in IP.user_ns
         except:
             IP.InteractiveTB()
             warn('Failure executing code: ' + `code`)
 
     # Execute the files the user wants in ipythonrc
     for file in IP_rc.execfile:
         try:
             file = filefind(file,sys.path+[IPython_dir])
         except IOError:
             warn(itpl('File $file not found. Skipping it.'))
         else:
             IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
 
     # release stdout and stderr and save config log into a global summary
     msg.config.release_all()
     if IP_rc.messages:
         msg.summary += msg.config.summary_all()
 
     #------------------------------------------------------------------------
     # Setup interactive session
 
     # Now we should be fully configured. We can then execute files or load
     # things only needed for interactive use. Then we'll open the shell.
 
     # Take a snapshot of the user namespace before opening the shell. That way
     # we'll be able to identify which things were interactively defined and
     # which were defined through config files.
     IP.user_config_ns = IP.user_ns.copy()
 
     # Force reading a file as if it were a session log. Slower but safer.
     if load_logplay:
         print 'Replaying log...'
         try:
             if IP_rc.debug:
                 logplay_quiet = 0
             else:
                  logplay_quiet = 1
 
             msg.logplay.trap_all()
             IP.safe_execfile(load_logplay,IP.user_ns,
                              islog = 1, quiet = logplay_quiet)
             msg.logplay.release_all()
             if IP_rc.messages:
                 msg.summary += msg.logplay.summary_all()
         except:
             warn('Problems replaying logfile %s.' % load_logplay)
             IP.InteractiveTB()
 
     # Load remaining files in command line
     msg.user_exec.trap_all()
 
     # Do NOT execute files named in the command line as scripts to be loaded
     # by embedded instances.  Doing so has the potential for an infinite
     # recursion if there are exceptions thrown in the process.
 
     # XXX FIXME: the execution of user files should be moved out to after
     # ipython is fully initialized, just as if they were run via %run at the
     # ipython prompt.  This would also give them the benefit of ipython's
     # nice tracebacks.
     
     if not embedded and IP_rc.args:
         name_save = IP.user_ns['__name__']
         IP.user_ns['__name__'] = '__main__'
         try:
             # Set our own excepthook in case the user code tries to call it
             # directly. This prevents triggering the IPython crash handler.
             old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
             for run in args:
                 IP.safe_execfile(run,IP.user_ns)
         finally:
             # Reset our crash handler in place
             sys.excepthook = old_excepthook
             
         IP.user_ns['__name__'] = name_save
         
     msg.user_exec.release_all()
     if IP_rc.messages:
         msg.summary += msg.user_exec.summary_all()
 
     # since we can't specify a null string on the cmd line, 0 is the equivalent:
     if IP_rc.nosep:
         IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
     if IP_rc.separate_in == '0': IP_rc.separate_in = ''
     if IP_rc.separate_out == '0': IP_rc.separate_out = ''
     if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
     IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
     IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
     IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
 
     # Determine how many lines at the bottom of the screen are needed for
     # showing prompts, so we can know wheter long strings are to be printed or
     # paged:
     num_lines_bot = IP_rc.separate_in.count('\n')+1
     IP_rc.screen_length = IP_rc.screen_length - num_lines_bot
 
     # configure startup banner
     if IP_rc.c:  # regular python doesn't print the banner with -c
         IP_rc.banner = 0
     if IP_rc.banner:
         BANN_P = IP.BANNER_PARTS
     else:
         BANN_P = []
 
     if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
 
     # add message log (possibly empty)
     if msg.summary: BANN_P.append(msg.summary)
     # Final banner is a string
     IP.BANNER = '\n'.join(BANN_P)
 
     # Finalize the IPython instance.  This assumes the rc structure is fully
     # in place.
     IP.post_config_initialization()
 
     return IP
 #************************ end of file <ipmaker.py> **************************

IPython/ultraTB.py

@@ -1,858 +1,857 b''
 # -*- coding: utf-8 -*-
 """
 ultraTB.py -- Spice up your tracebacks!
 
 * ColorTB
 I've always found it a bit hard to visually parse tracebacks in Python.  The
 ColorTB class is a solution to that problem.  It colors the different parts of a
 traceback in a manner similar to what you would expect from a syntax-highlighting
 text editor.
 
 Installation instructions for ColorTB:
     import sys,ultraTB
     sys.excepthook = ultraTB.ColorTB()
 
 * VerboseTB  
 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
 of useful info when a traceback occurs.  Ping originally had it spit out HTML
 and intended it for CGI programmers, but why should they have all the fun?  I
 altered it to spit out colored text to the terminal.  It's a bit overwhelming,
 but kind of neat, and maybe useful for long-running programs that you believe
 are bug-free.  If a crash *does* occur in that type of program you want details.
 Give it a shot--you'll love it or you'll hate it.
 
 Note:
 
   The Verbose mode prints the variables currently visible where the exception
   happened (shortening their strings if too long). This can potentially be
   very slow, if you happen to have a huge data structure whose string
   representation is complex to compute. Your computer may appear to freeze for
   a while with cpu usage at 100%. If this occurs, you can cancel the traceback
   with Ctrl-C (maybe hitting it more than once).
 
   If you encounter this kind of situation often, you may want to use the
   Verbose_novars mode instead of the regular Verbose, which avoids formatting
   variables (but otherwise includes the information and context given by
   Verbose).
   
 
 Installation instructions for ColorTB:
     import sys,ultraTB
     sys.excepthook = ultraTB.VerboseTB()
 
 Note:  Much of the code in this module was lifted verbatim from the standard
 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
 
 * Color schemes
 The colors are defined in the class TBTools through the use of the
 ColorSchemeTable class. Currently the following exist:
 
   - NoColor: allows all of this module to be used in any terminal (the color
   escapes are just dummy blank strings).
 
   - Linux: is meant to look good in a terminal like the Linux console (black
   or very dark background).
 
   - LightBG: similar to Linux but swaps dark/light colors to be more readable
   in light background terminals.
 
 You can implement other color schemes easily, the syntax is fairly
 self-explanatory. Please send back new schemes you develop to the author for
 possible inclusion in future releases.
 
-$Id: ultraTB.py 992 2006-01-04 18:35:40Z fperez $"""
+$Id: ultraTB.py 994 2006-01-08 08:29:44Z fperez $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001 Nathaniel Gray <[e-mail]>
 #       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>\n%s <%s>' % (Release.authors['Nathan']+
                                     Release.authors['Fernando'])
 __license__ = Release.license
 
 # Required modules
 import inspect
 import keyword
 import linecache
 import os
 import pydoc
 import string
 import sys
 import time
 import tokenize
 import traceback
 import types
 
 # IPython's own modules
 # Modified pdb which doesn't damage IPython's readline handling
 from IPython import Debugger
 from IPython.Struct import Struct
 from IPython.excolors import ExceptionColors
 from IPython.genutils import Term,uniq_stable,error,info
 
 # Globals
 # amount of space to put line numbers before verbose tracebacks
 INDENT_SIZE = 8
 
 #---------------------------------------------------------------------------
 # Code begins
 
 # Utility functions
 def inspect_error():
     """Print a message about internal inspect errors.
 
     These are unfortunately quite common."""
     
     error('Internal Python error in the inspect module.\n'
           'Below is the traceback from this internal error.\n')
 
 def _fixed_getinnerframes(etb, context=1,tb_offset=0):
     import linecache
     LNUM_POS, LINES_POS, INDEX_POS =  2, 4, 5
 
     records  = inspect.getinnerframes(etb, context)
 
     # If the error is at the console, don't build any context, since it would
     # otherwise produce 5 blank lines printed out (there is no file at the
     # console)
     rec_check = records[tb_offset:]
     try:
         rname = rec_check[0][1]
         if rname == '<ipython console>' or rname.endswith('<string>'):
             return rec_check
     except IndexError:
         pass
 
     aux = traceback.extract_tb(etb)
     assert len(records) == len(aux)
     for i, (file, lnum, _, _) in zip(range(len(records)), aux):
         maybeStart = lnum-1 - context//2
         start =  max(maybeStart, 0)
         end   = start + context
         lines = linecache.getlines(file)[start:end]
         # pad with empty lines if necessary
         if maybeStart < 0:
             lines = (['\n'] * -maybeStart) + lines
         if len(lines) < context:
             lines += ['\n'] * (context - len(lines))
-        assert len(lines) == context
         buf = list(records[i])
         buf[LNUM_POS] = lnum
         buf[INDEX_POS] = lnum - 1 - start
         buf[LINES_POS] = lines
         records[i] = tuple(buf)
     return records[tb_offset:]
 
 # Helper function -- largely belongs to VerboseTB, but we need the same
 # functionality to produce a pseudo verbose TB for SyntaxErrors, so that they
 # can be recognized properly by ipython.el's py-traceback-line-re
 # (SyntaxErrors have to be treated specially because they have no traceback)
 def _formatTracebackLines(lnum, index, lines, Colors, lvals=None):
     numbers_width = INDENT_SIZE - 1
     res = []
     i = lnum - index
     for line in lines:
         if i == lnum:
             # This is the line with the error
             pad = numbers_width - len(str(i))
             if pad >= 3:
                 marker = '-'*(pad-3) + '-> '
             elif pad == 2:
                 marker = '> '
             elif pad == 1:
                 marker = '>'
             else:
                 marker = ''
             num = marker + str(i)
             line = '%s%s%s %s%s' %(Colors.linenoEm, num, 
                                    Colors.line, line, Colors.Normal)
         else:
             num = '%*s' % (numbers_width,i)
             line = '%s%s%s %s' %(Colors.lineno, num, 
                                  Colors.Normal, line)
 
         res.append(line)
         if lvals and i == lnum:
             res.append(lvals + '\n')
         i = i + 1
     return res
 
 #---------------------------------------------------------------------------
 # Module classes
 class TBTools:
     """Basic tools used by all traceback printer classes."""
 
     def __init__(self,color_scheme = 'NoColor',call_pdb=False):
         # Whether to call the interactive pdb debugger after printing
         # tracebacks or not
         self.call_pdb = call_pdb
 
         # Create color table
         self.color_scheme_table = ExceptionColors 
 
         self.set_colors(color_scheme)
         self.old_scheme = color_scheme  # save initial value for toggles
 
         if call_pdb:
             self.pdb = Debugger.Pdb(self.color_scheme_table.active_scheme_name)
         else:
             self.pdb = None
 
     def set_colors(self,*args,**kw):
         """Shorthand access to the color table scheme selector method."""
         
         self.color_scheme_table.set_active_scheme(*args,**kw)
         # for convenience, set Colors to the active scheme
         self.Colors = self.color_scheme_table.active_colors
 
     def color_toggle(self):
         """Toggle between the currently active color scheme and NoColor."""
         
         if self.color_scheme_table.active_scheme_name == 'NoColor':
             self.color_scheme_table.set_active_scheme(self.old_scheme)
             self.Colors = self.color_scheme_table.active_colors
         else:
             self.old_scheme = self.color_scheme_table.active_scheme_name
             self.color_scheme_table.set_active_scheme('NoColor')
             self.Colors = self.color_scheme_table.active_colors
 
 #---------------------------------------------------------------------------
 class ListTB(TBTools):
     """Print traceback information from a traceback list, with optional color.
         
     Calling: requires 3 arguments:
       (etype, evalue, elist)
     as would be obtained by:
       etype, evalue, tb = sys.exc_info()
       if tb:
         elist = traceback.extract_tb(tb)
       else:
         elist = None
 
     It can thus be used by programs which need to process the traceback before
     printing (such as console replacements based on the code module from the
     standard library).
 
     Because they are meant to be called without a full traceback (only a
     list), instances of this class can't call the interactive pdb debugger."""
 
     def __init__(self,color_scheme = 'NoColor'):
         TBTools.__init__(self,color_scheme = color_scheme,call_pdb=0)
         
     def __call__(self, etype, value, elist):
         print >> Term.cerr, self.text(etype,value,elist)
 
     def text(self,etype, value, elist,context=5):
         """Return a color formatted string with the traceback info."""
 
         Colors = self.Colors
         out_string = ['%s%s%s\n' % (Colors.topline,'-'*60,Colors.Normal)]
         if elist:
             out_string.append('Traceback %s(most recent call last)%s:' % \
                                 (Colors.normalEm, Colors.Normal) + '\n')
             out_string.extend(self._format_list(elist))
         lines = self._format_exception_only(etype, value)
         for line in lines[:-1]:
             out_string.append(" "+line)
         out_string.append(lines[-1])
         return ''.join(out_string)
 
     def _format_list(self, extracted_list):
         """Format a list of traceback entry tuples for printing.
 
         Given a list of tuples as returned by extract_tb() or
         extract_stack(), return a list of strings ready for printing.
         Each string in the resulting list corresponds to the item with the
         same index in the argument list.  Each string ends in a newline;
         the strings may contain internal newlines as well, for those items
         whose source text line is not None.
         
         Lifted almost verbatim from traceback.py
         """
 
         Colors = self.Colors
         list = []
         for filename, lineno, name, line in extracted_list[:-1]:
             item = '  File %s"%s"%s, line %s%d%s, in %s%s%s\n' % \
                     (Colors.filename, filename, Colors.Normal, 
                      Colors.lineno, lineno, Colors.Normal,
                      Colors.name, name, Colors.Normal)
             if line:
                 item = item + '    %s\n' % line.strip()
             list.append(item)
         # Emphasize the last entry
         filename, lineno, name, line = extracted_list[-1]
         item = '%s  File %s"%s"%s, line %s%d%s, in %s%s%s%s\n' % \
                 (Colors.normalEm,
                  Colors.filenameEm, filename, Colors.normalEm,
                  Colors.linenoEm, lineno, Colors.normalEm,
                  Colors.nameEm, name, Colors.normalEm,
                  Colors.Normal)
         if line:
             item = item + '%s    %s%s\n' % (Colors.line, line.strip(),
                                             Colors.Normal)
         list.append(item)
         return list
         
     def _format_exception_only(self, etype, value):
         """Format the exception part of a traceback.
 
         The arguments are the exception type and value such as given by
         sys.exc_info()[:2]. The return value is a list of strings, each ending
         in a newline.  Normally, the list contains a single string; however,
         for SyntaxError exceptions, it contains several lines that (when
         printed) display detailed information about where the syntax error
         occurred.  The message indicating which exception occurred is the
         always last string in the list.
         
         Also lifted nearly verbatim from traceback.py
         """
         
         Colors = self.Colors
         list = []
         if type(etype) == types.ClassType:
             stype = Colors.excName + etype.__name__ + Colors.Normal
         else:
             stype = etype  # String exceptions don't get special coloring
         if value is None:
             list.append( str(stype) + '\n')
         else:
             if etype is SyntaxError:
                 try:
                     msg, (filename, lineno, offset, line) = value
                 except:
                     pass
                 else:
                     #print 'filename is',filename  # dbg
                     if not filename: filename = "<string>"
                     list.append('%s  File %s"%s"%s, line %s%d%s\n' % \
                             (Colors.normalEm,
                              Colors.filenameEm, filename, Colors.normalEm,
                              Colors.linenoEm, lineno, Colors.Normal  ))
                     if line is not None:
                         i = 0
                         while i < len(line) and line[i].isspace():
                             i = i+1
                         list.append('%s    %s%s\n' % (Colors.line,
                                                       line.strip(), 
                                                       Colors.Normal))
                         if offset is not None:
                             s = '    '
                             for c in line[i:offset-1]:
                                 if c.isspace():
                                     s = s + c
                                 else:
                                     s = s + ' '
                             list.append('%s%s^%s\n' % (Colors.caret, s,
                                                        Colors.Normal) )
                         value = msg
             s = self._some_str(value)
             if s:
                 list.append('%s%s:%s %s\n' % (str(stype), Colors.excName,
                                               Colors.Normal, s))
             else:
                 list.append('%s\n' % str(stype))
         return list
 
     def _some_str(self, value):
         # Lifted from traceback.py
         try:
             return str(value)
         except:
             return '<unprintable %s object>' % type(value).__name__
 
 #----------------------------------------------------------------------------
 class VerboseTB(TBTools):
     """A port of Ka-Ping Yee's cgitb.py module that outputs color text instead
     of HTML.  Requires inspect and pydoc.  Crazy, man.
 
     Modified version which optionally strips the topmost entries from the
     traceback, to be used with alternate interpreters (because their own code
     would appear in the traceback)."""
 
     def __init__(self,color_scheme = 'Linux',tb_offset=0,long_header=0,
                  call_pdb = 0, include_vars=1):
         """Specify traceback offset, headers and color scheme.
 
         Define how many frames to drop from the tracebacks. Calling it with
         tb_offset=1 allows use of this handler in interpreters which will have
         their own code at the top of the traceback (VerboseTB will first
         remove that frame before printing the traceback info)."""
         TBTools.__init__(self,color_scheme=color_scheme,call_pdb=call_pdb)
         self.tb_offset = tb_offset
         self.long_header = long_header
         self.include_vars = include_vars
 
     def text(self, etype, evalue, etb, context=5):
         """Return a nice text document describing the traceback."""
 
         # some locals
         Colors        = self.Colors   # just a shorthand + quicker name lookup
         ColorsNormal  = Colors.Normal  # used a lot
         indent        = ' '*INDENT_SIZE
         text_repr     = pydoc.text.repr
         exc           = '%s%s%s' % (Colors.excName, str(etype), ColorsNormal)
         em_normal     = '%s\n%s%s' % (Colors.valEm, indent,ColorsNormal)
         undefined     = '%sundefined%s' % (Colors.em, ColorsNormal)
 
         # some internal-use functions
         def eqrepr(value, repr=text_repr): return '=%s' % repr(value)
         def nullrepr(value, repr=text_repr): return ''
 
         # meat of the code begins
         if type(etype) is types.ClassType:
             etype = etype.__name__
 
         if self.long_header:
             # Header with the exception type, python version, and date
             pyver = 'Python ' + string.split(sys.version)[0] + ': ' + sys.executable
             date = time.ctime(time.time())
             
             head = '%s%s%s\n%s%s%s\n%s' % (Colors.topline, '-'*75, ColorsNormal,
                                            exc, ' '*(75-len(str(etype))-len(pyver)),
                                            pyver, string.rjust(date, 75) )
             head += "\nA problem occured executing Python code.  Here is the sequence of function"\
                     "\ncalls leading up to the error, with the most recent (innermost) call last."
         else:
             # Simplified header
             head = '%s%s%s\n%s%s' % (Colors.topline, '-'*75, ColorsNormal,exc,
                                      string.rjust('Traceback (most recent call last)',
                                                   75 - len(str(etype)) ) )
         frames = []
         # Flush cache before calling inspect.  This helps alleviate some of the
         # problems with python 2.3's inspect.py.
         linecache.checkcache()
         # Drop topmost frames if requested
         try:
             # Try the default getinnerframes and Alex's: Alex's fixes some
             # problems, but it generates empty tracebacks for console errors
             # (5 blanks lines) where none should be returned.
             #records = inspect.getinnerframes(etb, context)[self.tb_offset:]
             #print 'python records:', records # dbg
             records = _fixed_getinnerframes(etb, context,self.tb_offset)
             #print 'alex   records:', records # dbg
         except:
 
             # FIXME: I've been getting many crash reports from python 2.3
             # users, traceable to inspect.py.  If I can find a small test-case
             # to reproduce this, I should either write a better workaround or
             # file a bug report against inspect (if that's the real problem).
             # So far, I haven't been able to find an isolated example to
             # reproduce the problem.
             inspect_error()
             traceback.print_exc(file=Term.cerr)
             info('\nUnfortunately, your original traceback can not be constructed.\n')
             return ''
 
         # build some color string templates outside these nested loops
         tpl_link       = '%s%%s%s' % (Colors.filenameEm,ColorsNormal)
         tpl_call       = 'in %s%%s%s%%s%s' % (Colors.vName, Colors.valEm,
                                               ColorsNormal)
         tpl_call_fail  = 'in %s%%s%s(***failed resolving arguments***)%s' % \
                          (Colors.vName, Colors.valEm, ColorsNormal)
         tpl_local_var  = '%s%%s%s' % (Colors.vName, ColorsNormal)
         tpl_global_var = '%sglobal%s %s%%s%s' % (Colors.em, ColorsNormal,
                                                  Colors.vName, ColorsNormal)
         tpl_name_val   = '%%s %s= %%s%s' % (Colors.valEm, ColorsNormal)
         tpl_line       = '%s%%s%s %%s' % (Colors.lineno, ColorsNormal)
         tpl_line_em    = '%s%%s%s %%s%s' % (Colors.linenoEm,Colors.line,
                                             ColorsNormal)
 
         # now, loop over all records printing context and info
         abspath = os.path.abspath
         for frame, file, lnum, func, lines, index in records:
             #print '*** record:',file,lnum,func,lines,index  # dbg
             try:
                 file = file and abspath(file) or '?'
             except OSError:
                 # if file is '<console>' or something not in the filesystem,
                 # the abspath call will throw an OSError.  Just ignore it and
                 # keep the original file string.
                 pass
             link = tpl_link % file
             try:
                 args, varargs, varkw, locals = inspect.getargvalues(frame)
             except:
                 # This can happen due to a bug in python2.3.  We should be
                 # able to remove this try/except when 2.4 becomes a
                 # requirement.  Bug details at http://python.org/sf/1005466
                 inspect_error()
                 traceback.print_exc(file=Term.cerr)
                 info("\nIPython's exception reporting continues...\n")
                 
             if func == '?':
                 call = ''
             else:
                 # Decide whether to include variable details or not
                 var_repr = self.include_vars and eqrepr or nullrepr
                 try:
                     call = tpl_call % (func,inspect.formatargvalues(args,
                                                 varargs, varkw,
                                                 locals,formatvalue=var_repr))
                 except KeyError:
                     # Very odd crash from inspect.formatargvalues().  The
                     # scenario under which it appeared was a call to
                     # view(array,scale) in NumTut.view.view(), where scale had
                     # been defined as a scalar (it should be a tuple). Somehow
                     # inspect messes up resolving the argument list of view()
                     # and barfs out. At some point I should dig into this one
                     # and file a bug report about it.
                     inspect_error()
                     traceback.print_exc(file=Term.cerr)
                     info("\nIPython's exception reporting continues...\n")
                     call = tpl_call_fail % func
 
             # Initialize a list of names on the current line, which the
             # tokenizer below will populate.
             names = []
 
             def tokeneater(token_type, token, start, end, line):
                 """Stateful tokeneater which builds dotted names.
 
                 The list of names it appends to (from the enclosing scope) can
                 contain repeated composite names.  This is unavoidable, since
                 there is no way to disambguate partial dotted structures until
                 the full list is known.  The caller is responsible for pruning
                 the final list of duplicates before using it."""
                 
                 # build composite names
                 if token == '.':
                     try:
                         names[-1] += '.'
                         # store state so the next token is added for x.y.z names
                         tokeneater.name_cont = True
                         return
                     except IndexError:
                         pass
                 if token_type == tokenize.NAME and token not in keyword.kwlist:
                     if tokeneater.name_cont:
                         # Dotted names
                         names[-1] += token
                         tokeneater.name_cont = False
                     else:
                         # Regular new names.  We append everything, the caller
                         # will be responsible for pruning the list later.  It's
                         # very tricky to try to prune as we go, b/c composite
                         # names can fool us.  The pruning at the end is easy
                         # to do (or the caller can print a list with repeated
                         # names if so desired.
                         names.append(token)
                 elif token_type == tokenize.NEWLINE:
                     raise IndexError
             # we need to store a bit of state in the tokenizer to build
             # dotted names
             tokeneater.name_cont = False
 
             def linereader(file=file, lnum=[lnum], getline=linecache.getline):
                 line = getline(file, lnum[0])
                 lnum[0] += 1
                 return line
 
             # Build the list of names on this line of code where the exception
             # occurred.
             try:
                 # This builds the names list in-place by capturing it from the
                 # enclosing scope.
                 tokenize.tokenize(linereader, tokeneater)
             except IndexError:
                 # signals exit of tokenizer
                 pass
             except tokenize.TokenError,msg:
                 _m = ("An unexpected error occurred while tokenizing input\n"
                       "The following traceback may be corrupted or invalid\n"
                       "The error message is: %s\n" % msg)
                 error(_m)
             
             # prune names list of duplicates, but keep the right order
             unique_names = uniq_stable(names)
 
             # Start loop over vars
             lvals = []
             if self.include_vars:
                 for name_full in unique_names:
                     name_base = name_full.split('.',1)[0]
                     if name_base in frame.f_code.co_varnames:
                         if locals.has_key(name_base):
                             try:
                                 value = repr(eval(name_full,locals))
                             except:
                                 value = undefined
                         else:
                             value = undefined
                         name = tpl_local_var % name_full
                     else:
                         if frame.f_globals.has_key(name_base):
                             try:
                                 value = repr(eval(name_full,frame.f_globals))
                             except:
                                 value = undefined
                         else:
                             value = undefined
                         name = tpl_global_var % name_full
                     lvals.append(tpl_name_val % (name,value))
             if lvals:
                 lvals = '%s%s' % (indent,em_normal.join(lvals))
             else:
                 lvals = ''
 
             level = '%s %s\n' % (link,call)
 
             if index is None:
                 frames.append(level)
             else:
                 frames.append('%s%s' % (level,''.join(
                     _formatTracebackLines(lnum,index,lines,self.Colors,lvals))))
 
         # Get (safely) a string form of the exception info
         try:
             etype_str,evalue_str = map(str,(etype,evalue))
         except:
             # User exception is improperly defined.
             etype,evalue = str,sys.exc_info()[:2]
             etype_str,evalue_str = map(str,(etype,evalue))
         # ... and format it
         exception = ['%s%s%s: %s' % (Colors.excName, etype_str,
                                      ColorsNormal, evalue_str)]
         if type(evalue) is types.InstanceType:
             try:
                 names = [w for w in dir(evalue) if isinstance(w, basestring)]
             except:
                 # Every now and then, an object with funny inernals blows up
                 # when dir() is called on it.  We do the best we can to report
                 # the problem and continue
                 _m = '%sException reporting error (object with broken dir())%s:'
                 exception.append(_m % (Colors.excName,ColorsNormal))
                 etype_str,evalue_str = map(str,sys.exc_info()[:2])
                 exception.append('%s%s%s: %s' % (Colors.excName,etype_str,
                                      ColorsNormal, evalue_str))
                 names = []
             for name in names:
                 value = text_repr(getattr(evalue, name))
                 exception.append('\n%s%s = %s' % (indent, name, value))
         # return all our info assembled as a single string
         return '%s\n\n%s\n%s' % (head,'\n'.join(frames),''.join(exception[0]) )
 
     def debugger(self):
         """Call up the pdb debugger if desired, always clean up the tb reference.
 
         If the call_pdb flag is set, the pdb interactive debugger is
         invoked. In all cases, the self.tb reference to the current traceback
         is deleted to prevent lingering references which hamper memory
         management.
 
         Note that each call to pdb() does an 'import readline', so if your app
         requires a special setup for the readline completers, you'll have to
         fix that by hand after invoking the exception handler."""
 
         if self.call_pdb:
             if self.pdb is None:
                 self.pdb = Debugger.Pdb(
                     self.color_scheme_table.active_scheme_name)
             # the system displayhook may have changed, restore the original
             # for pdb
             dhook = sys.displayhook
             sys.displayhook = sys.__displayhook__
             self.pdb.reset()
             # Find the right frame so we don't pop up inside ipython itself
             etb = self.tb
             while self.tb.tb_next is not None:
                 self.tb = self.tb.tb_next
             try:
                 if etb and etb.tb_next:
                     etb = etb.tb_next
                 self.pdb.botframe = etb.tb_frame
                 self.pdb.interaction(self.tb.tb_frame, self.tb)
             except:
                 print '*** ERROR ***'
                 print 'This version of pdb has a bug and crashed.'
                 print 'Returning to IPython...'
             sys.displayhook = dhook
         del self.tb
 
     def handler(self, info=None):
         (etype, evalue, etb) = info or sys.exc_info()
         self.tb = etb
         print >> Term.cerr, self.text(etype, evalue, etb)
 
     # Changed so an instance can just be called as VerboseTB_inst() and print
     # out the right info on its own.
     def __call__(self, etype=None, evalue=None, etb=None):
         """This hook can replace sys.excepthook (for Python 2.1 or higher)."""
         if etb is None:
             self.handler()
         else:
             self.handler((etype, evalue, etb))
         self.debugger()
 
 #----------------------------------------------------------------------------
 class FormattedTB(VerboseTB,ListTB):
     """Subclass ListTB but allow calling with a traceback.
 
     It can thus be used as a sys.excepthook for Python > 2.1.
 
     Also adds 'Context' and 'Verbose' modes, not available in ListTB.
 
     Allows a tb_offset to be specified. This is useful for situations where
     one needs to remove a number of topmost frames from the traceback (such as
     occurs with python programs that themselves execute other python code,
     like Python shells).  """
     
     def __init__(self, mode = 'Plain', color_scheme='Linux',
                  tb_offset = 0,long_header=0,call_pdb=0,include_vars=0):
 
         # NEVER change the order of this list. Put new modes at the end:
         self.valid_modes = ['Plain','Context','Verbose']
         self.verbose_modes = self.valid_modes[1:3]
 
         VerboseTB.__init__(self,color_scheme,tb_offset,long_header,
                            call_pdb=call_pdb,include_vars=include_vars)
         self.set_mode(mode)
         
     def _extract_tb(self,tb):
         if tb:
             return traceback.extract_tb(tb)
         else:
             return None
 
     def text(self, etype, value, tb,context=5,mode=None):
         """Return formatted traceback.
 
         If the optional mode parameter is given, it overrides the current
         mode."""
 
         if mode is None:
             mode = self.mode
         if mode in self.verbose_modes:
             # verbose modes need a full traceback
             return VerboseTB.text(self,etype, value, tb,context=5)
         else:
             # We must check the source cache because otherwise we can print
             # out-of-date source code.
             linecache.checkcache()
             # Now we can extract and format the exception
             elist = self._extract_tb(tb)
             if len(elist) > self.tb_offset:
                 del elist[:self.tb_offset]
             return ListTB.text(self,etype,value,elist)
 
     def set_mode(self,mode=None):
         """Switch to the desired mode.
 
         If mode is not specified, cycles through the available modes."""
 
         if not mode:
             new_idx = ( self.valid_modes.index(self.mode) + 1 ) % \
                       len(self.valid_modes)
             self.mode = self.valid_modes[new_idx]
         elif mode not in self.valid_modes:
             raise ValueError, 'Unrecognized mode in FormattedTB: <'+mode+'>\n'\
                   'Valid modes: '+str(self.valid_modes)
         else:
             self.mode = mode
         # include variable details only in 'Verbose' mode
         self.include_vars = (self.mode == self.valid_modes[2])
 
     # some convenient shorcuts
     def plain(self):
         self.set_mode(self.valid_modes[0])
 
     def context(self):
         self.set_mode(self.valid_modes[1])
 
     def verbose(self):
         self.set_mode(self.valid_modes[2])
 
 #----------------------------------------------------------------------------
 class AutoFormattedTB(FormattedTB):
     """A traceback printer which can be called on the fly.
 
     It will find out about exceptions by itself.
 
     A brief example:
     
     AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
     try:
       ...
     except:
       AutoTB()  # or AutoTB(out=logfile) where logfile is an open file object
     """
     def __call__(self,etype=None,evalue=None,etb=None,
                  out=None,tb_offset=None):
         """Print out a formatted exception traceback.
 
         Optional arguments:
           - out: an open file-like object to direct output to.
 
           - tb_offset: the number of frames to skip over in the stack, on a
           per-call basis (this overrides temporarily the instance's tb_offset
           given at initialization time.  """
         
         if out is None:
             out = Term.cerr
         if tb_offset is not None:
             tb_offset, self.tb_offset = self.tb_offset, tb_offset
             print >> out, self.text(etype, evalue, etb)
             self.tb_offset = tb_offset
         else:
             print >> out, self.text(etype, evalue, etb)
         self.debugger()
 
     def text(self,etype=None,value=None,tb=None,context=5,mode=None):
         if etype is None:
             etype,value,tb = sys.exc_info()
         self.tb = tb
         return FormattedTB.text(self,etype,value,tb,context=5,mode=mode)
 
 #---------------------------------------------------------------------------
 # A simple class to preserve Nathan's original functionality.
 class ColorTB(FormattedTB):
     """Shorthand to initialize a FormattedTB in Linux colors mode."""
     def __init__(self,color_scheme='Linux',call_pdb=0):
         FormattedTB.__init__(self,color_scheme=color_scheme,
                              call_pdb=call_pdb)
 
 #----------------------------------------------------------------------------
 # module testing (minimal)
 if __name__ == "__main__":
     def spam(c, (d, e)):
         x = c + d
         y = c * d
         foo(x, y)
 
     def foo(a, b, bar=1):
         eggs(a, b + bar)
 
     def eggs(f, g, z=globals()):
         h = f + g
         i = f - g
         return h / i
 
     print ''
     print '*** Before ***'
     try:
         print spam(1, (2, 3))
     except:
         traceback.print_exc()
     print ''
     
     handler = ColorTB()
     print '*** ColorTB ***'
     try:
         print spam(1, (2, 3))
     except:
         apply(handler, sys.exc_info() )
     print ''
     
     handler = VerboseTB()
     print '*** VerboseTB ***'
     try:
         print spam(1, (2, 3))
     except:
         apply(handler, sys.exc_info() )
     print ''
     

IPython/winconsole.py

@@ -1,43 +1,46 b''
+"""Set of functions to work with console on Windows.
 """
-Set of functions to work with console on Windows.
 
-Author: Alexander Belchenko (e-mail: bialix AT ukr.net)
-License: Public domain
-"""
+#*****************************************************************************
+#       Copyright (C) 2005 Alexander Belchenko <[e-mail]>
+#
+#                This file is placed in the public domain.
+#
+#*****************************************************************************
 
 __author__  = 'Alexander Belchenko (e-mail: bialix AT ukr.net)'
 __license__ = 'Public domain'
 
 import struct
 
 try:
     import ctypes
 except ImportError:
     ctypes = None
 
 def get_console_size(defaultx=80, defaulty=25):
     """ Return size of current console.
 
     This function try to determine actual size of current working
     console window and return tuple (sizex, sizey) if success,
     or default size (defaultx, defaulty) otherwise.
 
     Dependencies: ctypes should be installed.
     """
     if ctypes is None:
         # no ctypes is found
         return (defaultx, defaulty)
 
     h = ctypes.windll.kernel32.GetStdHandle(-11)
     csbi = ctypes.create_string_buffer(22)
     res = ctypes.windll.kernel32.GetConsoleScreenBufferInfo(h, csbi)
     
     if res:
         (bufx, bufy, curx, cury, wattr,
          left, top, right, bottom, maxx, maxy) = struct.unpack("hhhhHhhhhhh",
                                                                csbi.raw)
         sizex = right - left + 1
         sizey = bottom - top + 1
         return (sizex, sizey)
     else:
         return (defaultx, defaulty)