Remove svn-style $Id marks from docstrings and Release imports.

The Id marks show up as junk in the API docs (and they were outdated anyway,
since we now use bzr).  

The Release imports were in there for pulling author/license information for
epydoc, but now with sphinx they aren't necessary, and they just are extra
startup work.

IPython/ColorANSI.py

@@ -1,182 +1,177 b''
 # -*- coding: utf-8 -*-
 """Tools for coloring text in ANSI terminals.
-
-$Id: ColorANSI.py 2167 2007-03-21 06:57:50Z fperez $"""
+"""
 
 #*****************************************************************************
 #       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.ipstruct 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 = (
         # Dark colors
         ("Black"       , "0;30"),
         ("Red"         , "0;31"),
         ("Green"       , "0;32"),
         ("Brown"       , "0;33"),
         ("Blue"        , "0;34"),
         ("Purple"      , "0;35"),
         ("Cyan"        , "0;36"),
         ("LightGray"   , "0;37"),
         # Light colors
         ("DarkGray"    , "1;30"),
         ("LightRed"    , "1;31"),
         ("LightGreen"  , "1;32"),
         ("Yellow"      , "1;33"),
         ("LightBlue"   , "1;34"),
         ("LightPurple" , "1;35"),
         ("LightCyan"   , "1;36"),
         ("White"       , "1;37"),  
         # Blinking colors.  Probably should not be used in anything serious.
         ("BlinkBlack"  , "5;30"),
         ("BlinkRed"    , "5;31"),
         ("BlinkGreen"  , "5;32"),
         ("BlinkYellow" , "5;33"),
         ("BlinkBlue"   , "5;34"),
         ("BlinkPurple" , "5;35"),
         ("BlinkCyan"   , "5;36"),
         ("BlinkLightGray", "5;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.
 
     if os.name == 'nt' and os.environ.get('TERM','dumb') == 'emacs':
         # (X)emacs on W32 gets confused with \001 and \002 so we remove them
         Normal = '\033[0m'   # Reset normal coloring
         _base  = '\033[%sm'  # Template for all other colors
     else:
         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,111 b''
 # -*- coding: utf-8 -*-
 """Configuration loader
-
-$Id: ConfigLoader.py 1005 2006-01-12 08:39:26Z fperez $"""
+"""
 
 #*****************************************************************************
 #       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.ipstruct 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(color_scheme='NoColor')
         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:
             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,228 +1,227 b''
 # -*- coding: utf-8 -*-
 """sys.excepthook for IPython itself, leaves a detailed report on disk.
-
-$Id: CrashHandler.py 2908 2007-12-30 21:07:46Z vivainio $"""
+"""
 
 #*****************************************************************************
 #       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:
     """Customizable crash handlers for IPython-based systems.
 
     Instances of this class provide a __call__ method which can be used as a
     sys.excepthook, i.e., the __call__ signature is:
 
         def __call__(self,etype, evalue, etb)
 
     """
 
     def __init__(self,IP,app_name,contact_name,contact_email,
                  bug_tracker,crash_report_fname,
                  show_crash_traceback=True):
         """New crash handler.
 
         Inputs:
 
         - IP: a running IPython instance, which will be queried at crash time
         for internal information.
 
         - app_name: a string containing the name of your application.
 
         - contact_name: a string with the name of the person to contact.
 
         - contact_email: a string with the email address of the contact.
 
         - bug_tracker: a string with the URL for your project's bug tracker.
 
         - crash_report_fname: a string with the filename for the crash report
         to be saved in.  These reports are left in the ipython user directory
         as determined by the running IPython instance.
 
         Optional inputs:
         
         - show_crash_traceback(True): if false, don't print the crash
         traceback on stderr, only generate the on-disk report
 
 
         Non-argument instance attributes:
 
         These instances contain some non-argument attributes which allow for 
         further customization of the crash handler's behavior.  Please see the
         source for further details.
         """
 
         # apply args into instance
         self.IP = IP  # IPython instance
         self.app_name = app_name
         self.contact_name = contact_name
         self.contact_email = contact_email
         self.bug_tracker = bug_tracker
         self.crash_report_fname = crash_report_fname
         self.show_crash_traceback = show_crash_traceback
         
         # Hardcoded defaults, which can be overridden either by subclasses or
         # at runtime for the instance.
 
         # Template for the user message.  Subclasses which completely override
         # this, or user apps, can modify it to suit their tastes.  It gets
         # expanded using itpl, so calls of the kind $self.foo are valid.
         self.user_message_template = """
 Oops, $self.app_name 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 crash traceback.
   - A copy of your input history during this session.
   - Data on your current $self.app_name configuration.
 
 It was left in the file named:
 \t'$self.crash_report_fname'
 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.contact_name at $self.contact_email
 with the subject '$self.app_name Crash Report'.
 
 If you want to do it now, the following command will work (under Unix):
 mail -s '$self.app_name Crash Report' $self.contact_email < $self.crash_report_fname
 
 To ensure accurate tracking of this issue, please file a report about it at:
 $self.bug_tracker
 """
 
     def __call__(self,etype, evalue, etb):
         """Handle an exception, call for compatible with sys.excepthook"""
 
         # 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()
         report_name = os.path.join(rptdir,self.crash_report_fname)
         # write the report filename into the instance dict so it can get
         # properly expanded out in the user message template
         self.crash_report_fname = report_name
         TBhandler = ultraTB.VerboseTB(color_scheme=color_scheme,
                                            long_header=1)
         traceback = TBhandler.text(etype,evalue,etb,context=31)
 
         # print traceback to screen
         if self.show_crash_traceback:
             print >> sys.stderr, traceback
 
         # and generate a complete report on disk
         try:
             report = open(report_name,'w')
         except:
             print >> sys.stderr, 'Could not create crash report on disk.'
             return
 
         # Inform user on stderr of what happened
         msg = itpl('\n'+'*'*70+'\n'+self.user_message_template)
         print >> sys.stderr, msg
 
         # Construct report on disk
         report.write(self.make_report(traceback))
         report.close()
         raw_input("Press enter to exit:")
 
     def make_report(self,traceback):
         """Return a string containing a crash report."""
 
         sec_sep = '\n\n'+'*'*75+'\n\n'
 
         report = []
         rpt_add = report.append
         
         rpt_add('*'*75+'\n\n'+'IPython post-mortem report\n\n')
         rpt_add('IPython version: %s \n\n' % Release.version)
         rpt_add('SVN revision   : %s \n\n' % Release.revision)
         rpt_add('Platform info  : os.name -> %s, sys.platform -> %s' %
                      (os.name,sys.platform) )
         rpt_add(sec_sep+'Current user configuration structure:\n\n')
         rpt_add(pformat(self.IP.rc.dict()))
         rpt_add(sec_sep+'Crash traceback:\n\n' + traceback)
         try:
             rpt_add(sec_sep+"History of session input:")
             for line in self.IP.user_ns['_ih']:
                 rpt_add(line)
             rpt_add('\n*** Last line of input (may not be in above history):\n')
             rpt_add(self.IP._last_input_line+'\n')
         except:
             pass
 
         return ''.join(report)
 
 class IPythonCrashHandler(CrashHandler):
     """sys.excepthook for IPython itself, leaves a detailed report on disk."""
     
     def __init__(self,IP):
 
         # Set here which of the IPython authors should be listed as contact
         AUTHOR_CONTACT = 'Ville'
         
         # Set argument defaults
         app_name = 'IPython'
         bug_tracker = 'http://projects.scipy.org/ipython/ipython/report'
         contact_name,contact_email = Release.authors[AUTHOR_CONTACT][:2]
         crash_report_fname = 'IPython_crash_report.txt'
         # Call parent constructor
         CrashHandler.__init__(self,IP,app_name,contact_name,contact_email,
                               bug_tracker,crash_report_fname)
 
     def make_report(self,traceback):
         """Return a string containing a crash report."""
 
         sec_sep = '\n\n'+'*'*75+'\n\n'
 
         report = []
         rpt_add = report.append
         
         rpt_add('*'*75+'\n\n'+'IPython post-mortem report\n\n')
         rpt_add('IPython version: %s \n\n' % Release.version)
         rpt_add('SVN revision   : %s \n\n' % Release.revision)
         rpt_add('Platform info  : os.name -> %s, sys.platform -> %s' %
                      (os.name,sys.platform) )
         rpt_add(sec_sep+'Current user configuration structure:\n\n')
         rpt_add(pformat(self.IP.rc.dict()))
         rpt_add(sec_sep+'Crash traceback:\n\n' + traceback)
         try:
             rpt_add(sec_sep+"History of session input:")
             for line in self.IP.user_ns['_ih']:
                 rpt_add(line)
             rpt_add('\n*** Last line of input (may not be in above history):\n')
             rpt_add(self.IP._last_input_line+'\n')
         except:
             pass
 
         return ''.join(report)

IPython/DPyGetOpt.py

@@ -1,693 +1,690 b''
 # -*- coding: utf-8 -*-
 """DPyGetOpt -- Demiurge Python GetOptions Module
 
- $Id: DPyGetOpt.py 2872 2007-11-25 17:58:05Z fperez $
-
 This module is modeled after perl's Getopt::Long module-- which
 is, in turn, modeled after GNU's extended getopt() function.
 
 Upon instantiation, the option specification should be a sequence
 (list) of option definitions.
 
 Options that take no arguments should simply contain the name of
 the option.  If a ! is post-pended, the option can be negated by
 prepending 'no';  ie 'debug!' specifies that -debug and -nodebug
 should be accepted.
 
 Mandatory arguments to options are specified using a postpended
 '=' + a type specifier.  '=s' specifies a mandatory string
 argument, '=i' specifies a mandatory integer argument, and '=f'
 specifies a mandatory real number.  In all cases, the '=' can be
 substituted with ':' to specify that the argument is optional.
 
 Dashes '-' in option names are allowed.
 
 If an option has the character '@' postpended (after the
 argumentation specification), it can appear multiple times within
 each argument list that is processed. The results will be stored
 in a list.
 
 The option name can actually be a list of names separated by '|'
 characters;  ie-- 'foo|bar|baz=f@' specifies that all -foo, -bar,
 and -baz options that appear on within the parsed argument list
 must have a real number argument and that the accumulated list
 of values will be available under the name 'foo'
-
-$Id: DPyGetOpt.py 2872 2007-11-25 17:58:05Z fperez $"""
+"""
 
 #*****************************************************************************
 #
 # Copyright (c) 2001 Bill Bumgarner <[e-mail]>
 #
 #
 # Published under the terms of the MIT license, hereby reproduced:
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
 # deal in the Software without restriction, including without limitation the
 # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 # sell copies of the Software, and to permit persons to whom the Software is
 # furnished to do so, subject to the following conditions:
 #
 # The above copyright notice and this permission notice shall be included in
 # all copies or substantial portions of the Software.
 #
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 #
 #*****************************************************************************
 
 __author__  = 'Bill Bumgarner <[e-mail]>'
 __license__ = 'MIT'
 __version__ = '1.2'
 
 # Modified to use re instead of regex and regsub modules.
 # 2001/5/7, Jonathan Hogg <[e-mail]>
 
 import re
 import string
 import sys
 import types
 
 class Error(Exception):
     """Base class for exceptions in the DPyGetOpt module."""
 
 class ArgumentError(Error):
     """Exception indicating an error in the arguments passed to
     DPyGetOpt.processArguments."""
 
 class SpecificationError(Error):
     """Exception indicating an error with an option specification."""
 
 class TerminationError(Error):
     """Exception indicating an error with an option processing terminator."""
 
 specificationExpr = re.compile('(?P<required>.)(?P<type>.)(?P<multi>@?)')
 
 ArgRequired     = 'Requires an Argument'
 ArgOptional     = 'Argument Optional'
 
 # The types modules is not used for these identifiers because there
 # is no identifier for 'boolean' or 'generic'
 StringArgType   = 'String Argument Type'
 IntegerArgType  = 'Integer Argument Type'
 RealArgType             = 'Real Argument Type'
 BooleanArgType  = 'Boolean Argument Type'
 GenericArgType  = 'Generic Argument Type'
 
 # dictionary of conversion functions-- boolean and generic options
 # do not accept arguments and do not need conversion functions;
 # the identity function is used purely for convenience.
 ConversionFunctions = {
         StringArgType : lambda x: x,
         IntegerArgType : string.atoi,
         RealArgType : string.atof,
         BooleanArgType : lambda x: x,
         GenericArgType : lambda x: x,
         }
 
 class DPyGetOpt:
 
     def __init__(self, spec = None, terminators = ['--']):
         """
         Declare and intialize instance variables
 
         Yes, declaration is not necessary... but one of the things
         I sorely miss from C/Obj-C is the concept of having an
         interface definition that clearly declares all instance
         variables and methods without providing any implementation
          details.   it is a useful reference!
 
         all instance variables are initialized to 0/Null/None of
         the appropriate type-- not even the default value...
         """
 
 #               sys.stderr.write(string.join(spec) + "\n")
 
         self.allowAbbreviations = 1  # boolean, 1 if abbreviations will
                                                                                   # be expanded
         self.freeValues         = [] # list, contains free values
         self.ignoreCase         = 0  # boolean, YES if ignoring case
         self.needsParse         = 0  # boolean, YES if need to reparse parameter spec
         self.optionNames        = {} # dict, all option names-- value is index of tuple
         self.optionStartExpr    = None # regexp defining the start of an option (ie; '-', '--')
         self.optionTuples       = [] # list o' tuples containing defn of options AND aliases
         self.optionValues       = {} # dict, option names (after alias expansion) -> option value(s)
         self.orderMixed         = 0  # boolean, YES if options can be mixed with args
         self.posixCompliance    = 0  # boolean, YES indicates posix like behaviour
         self.spec               = [] # list, raw specs (in case it must be reparsed)
         self.terminators        = terminators # list, strings that terminate argument processing
         self.termValues         = [] # list, values after terminator
         self.terminator         = None # full name of terminator that ended
                                                # option processing
 
         # set up defaults
         self.setPosixCompliance()
         self.setIgnoreCase()
         self.setAllowAbbreviations()
 
         # parse spec-- if present
         if spec:
             self.parseConfiguration(spec)
 
     def setPosixCompliance(self, aFlag = 0):
         """
         Enables and disables posix compliance.
 
         When enabled, '+' can be used as an option prefix and free
         values can be mixed with options.
         """
         self.posixCompliance = aFlag
         self.needsParse = 1
 
         if self.posixCompliance:
             self.optionStartExpr = re.compile('(--|-)(?P<option>[A-Za-z0-9_-]+)(?P<arg>=.*)?')
             self.orderMixed = 0
         else:
             self.optionStartExpr = re.compile('(--|-|\+)(?P<option>[A-Za-z0-9_-]+)(?P<arg>=.*)?')
             self.orderMixed = 1
 
     def isPosixCompliant(self):
         """
         Returns the value of the posix compliance flag.
         """
         return self.posixCompliance
 
     def setIgnoreCase(self, aFlag = 1):
         """
         Enables and disables ignoring case during option processing.
         """
         self.needsParse = 1
         self.ignoreCase = aFlag
 
     def ignoreCase(self):
         """
         Returns 1 if the option processor will ignore case when
         processing options.
         """
         return self.ignoreCase
 
     def setAllowAbbreviations(self, aFlag = 1):
         """
         Enables and disables the expansion of abbreviations during
         option processing.
         """
         self.allowAbbreviations = aFlag
 
     def willAllowAbbreviations(self):
         """
         Returns 1 if abbreviated options will be automatically
         expanded to the non-abbreviated form (instead of causing an
         unrecognized option error).
         """
         return self.allowAbbreviations
 
     def addTerminator(self, newTerm):
         """
         Adds newTerm as terminator of option processing.
 
         Whenever the option processor encounters one of the terminators
         during option processing, the processing of options terminates
         immediately, all remaining options are stored in the termValues
         instance variable and the full name of the terminator is stored
         in the terminator instance variable.
         """
         self.terminators = self.terminators + [newTerm]
 
     def _addOption(self, oTuple):
         """
         Adds the option described by oTuple (name, (type, mode,
         default), alias) to optionTuples.  Adds index keyed under name
         to optionNames.  Raises SpecificationError if name already in
         optionNames
         """
         (name, (type, mode, default, multi), realName) = oTuple
 
         # verify name and add to option names dictionary
         if self.optionNames.has_key(name):
             if realName:
                 raise SpecificationError('Alias \'' + name + '\' for \'' +
                                          realName +
                                          '\' already used for another option or alias.')
             else:
                 raise SpecificationError('Option named \'' + name +
                                          '\' specified more than once. Specification: '
                                          + option)
 
         # validated. add to optionNames
         self.optionNames[name] = self.tupleIndex
         self.tupleIndex = self.tupleIndex + 1
 
         # add to optionTuples
         self.optionTuples = self.optionTuples + [oTuple]
 
         # if type is boolean, add negation
         if type == BooleanArgType:
             alias            = 'no' + name
             specTuple = (type, mode, 0, multi)
             oTuple = (alias, specTuple, name)
 
             # verify name and add to option names dictionary
             if self.optionNames.has_key(alias):
                 if realName:
                     raise SpecificationError('Negated alias \'' + name +
                                              '\' for \'' + realName +
                                              '\' already used for another option or alias.')
                 else:
                     raise SpecificationError('Negated option named \'' + name +
                                              '\' specified more than once. Specification: '
                                              + option)
 
             # validated. add to optionNames
             self.optionNames[alias] = self.tupleIndex
             self.tupleIndex = self.tupleIndex + 1
 
             # add to optionTuples
             self.optionTuples = self.optionTuples + [oTuple]
 
     def addOptionConfigurationTuple(self, oTuple):
         (name, argSpec, realName) = oTuple
         if self.ignoreCase:
             name = string.lower(name)
             if realName:
                 realName = string.lower(realName)
             else:
                 realName = name
 
             oTuple = (name, argSpec, realName)
 
         # add option
         self._addOption(oTuple)
 
     def addOptionConfigurationTuples(self, oTuple):
         if type(oTuple) is ListType:
             for t in oTuple:
                 self.addOptionConfigurationTuple(t)
         else:
             self.addOptionConfigurationTuple(oTuple)
 
     def parseConfiguration(self, spec):
         # destroy previous stored information + store raw spec
         self.spec                       = spec
         self.optionTuples       = []
         self.optionNames  = {}
         self.tupleIndex   = 0
 
         tupleIndex = 0
 
         # create some regex's for parsing each spec
         splitExpr = \
                                  re.compile('(?P<names>\w+[-A-Za-z0-9|]*)?(?P<spec>!|[=:][infs]@?)?')
         for option in spec:
  # push to lower case (does not negatively affect
  # specification)
             if self.ignoreCase:
                 option = string.lower(option)
 
             # break into names, specification
             match = splitExpr.match(option)
             if match is None:
                 raise SpecificationError('Invalid specification {' + option +
                                          '}')
 
             names                     = match.group('names')
             specification = match.group('spec')
 
             # break name into name, aliases
             nlist = string.split(names, '|')
 
             # get name
             name      = nlist[0]
             aliases = nlist[1:]
 
             # specificationExpr = regex.symcomp('\(<required>.\)\(<type>.\)\(<multi>@?\)')
             if not specification:
                 #spec tuple is ('type', 'arg mode', 'default value', 'multiple')
                 argType         = GenericArgType
                 argMode         = None
                 argDefault      = 1
                 argMultiple     = 0
             elif specification == '!':
                 argType         = BooleanArgType
                 argMode         = None
                 argDefault      = 1
                 argMultiple     = 0
             else:
                 # parse
                 match = specificationExpr.match(specification)
                 if match is None:
                     # failed to parse, die
                     raise SpecificationError('Invalid configuration for option \''
                                              + option + '\'')
 
                 # determine mode
                 required = match.group('required')
                 if required == '=':
                     argMode = ArgRequired
                 elif required == ':':
                     argMode = ArgOptional
                 else:
                     raise SpecificationError('Unknown requirement configuration \''
                                              + required + '\'')
 
                 # determine type
                 type = match.group('type')
                 if type == 's':
                     argType   = StringArgType
                     argDefault = ''
                 elif type == 'i':
                     argType   = IntegerArgType
                     argDefault = 1
                 elif type == 'f' or type == 'n':
                     argType   = RealArgType
                     argDefault = 1
                 else:
                     raise SpecificationError('Unknown type specifier \'' +
                                              type + '\'')
 
                 # determine quantity
                 if match.group('multi') == '@':
                     argMultiple = 1
                 else:
                     argMultiple = 0
             ## end else (of not specification)
 
             # construct specification tuple
             specTuple = (argType, argMode, argDefault, argMultiple)
 
             # add the option-- option tuple is (name, specTuple, real name)
             oTuple = (name, specTuple, name)
             self._addOption(oTuple)
 
             for alias in aliases:
                 # drop to all lower (if configured to do so)
                 if self.ignoreCase:
                     alias = string.lower(alias)
                 # create configuration tuple
                 oTuple = (alias, specTuple, name)
                 # add
                 self._addOption(oTuple)
 
         # successfully parsed....
         self.needsParse = 0
 
     def _getArgTuple(self, argName):
         """
         Returns a list containing all the specification tuples that
         match argName.  If none match, None is returned.  If one
         matches, a list with one tuple is returned.  If more than one
         match, a list containing all the tuples that matched is
         returned.
 
         In other words, this function does not pass judgement upon the
         validity of multiple matches.
         """
         # is it in the optionNames dict?
 
         try:
 #                       sys.stderr.write(argName + string.join(self.optionNames.keys()) + "\n")
 
             # yes, get index
             tupleIndex = self.optionNames[argName]
             # and return tuple as element of list
             return [self.optionTuples[tupleIndex]]
         except KeyError:
             # are abbreviations allowed?
             if not self.allowAbbreviations:
                 # No! terefore, this cannot be valid argument-- nothing found
                 return None
 
         # argName might be an abbreviation (and, abbreviations must
         # be allowed... or this would not have been reached!)
 
         # create regex for argName
         argExpr = re.compile('^' + argName)
 
         tuples = filter(lambda x, argExpr=argExpr: argExpr.search(x[0]) is not None,
                                                   self.optionTuples)
 
         if not len(tuples):
             return None
         else:
             return tuples
 
     def _isTerminator(self, optionName):
         """
         Returns the full name of the terminator if optionName is a valid
         terminator.  If it is, sets self.terminator to the full name of
         the terminator.
 
         If more than one terminator matched, raises a TerminationError with a
         string describing the ambiguity.
         """
 
 #               sys.stderr.write(optionName + "\n")
 #               sys.stderr.write(repr(self.terminators))
 
         if optionName in self.terminators:
             self.terminator = optionName
         elif not self.allowAbbreviations:
             return None
 
 # regex thing in bogus
 #               termExpr = regex.compile('^' + optionName)
 
         terms = filter(lambda x, on=optionName: string.find(x,on) == 0, self.terminators)
 
         if not len(terms):
             return None
         elif len(terms) > 1:
             raise TerminationError('Ambiguous terminator \'' + optionName +
                                    '\' matches ' + repr(terms))
 
         self.terminator = terms[0]
         return self.terminator
 
     def processArguments(self, args = None):
         """
         Processes args, a list of arguments (including options).
 
         If args is the same as sys.argv, automatically trims the first
         argument (the executable name/path).
 
         If an exception is not raised, the argument list was parsed
         correctly.
 
         Upon successful completion, the freeValues instance variable
         will contain all the arguments that were not associated with an
         option in the order they were encountered.  optionValues is a
         dictionary containing the value of each option-- the method
         valueForOption() can be used to query this dictionary.
         terminator will contain the argument encountered that terminated
         option processing (or None, if a terminator was never
         encountered) and termValues will contain all of the options that
         appeared after the Terminator (or an empty list).
         """
 
         if hasattr(sys, "argv") and args == sys.argv:
             args = sys.argv[1:]
 
         max             = len(args) # maximum index + 1
         self.freeValues = []        # array to hold return values
         self.optionValues= {}
         index           = 0         # initial index
         self.terminator = None
         self.termValues  = []
 
         while index < max:
             # obtain argument
             arg = args[index]
             # increment index -- REMEMBER; it is NOW incremented
             index = index + 1
 
             # terminate immediately if option terminator encountered
             if self._isTerminator(arg):
                 self.freeValues = self.freeValues + args[index:]
                 self.termValues = args[index:]
                 return
 
             # is this possibly an option?
             match = self.optionStartExpr.match(arg)
             if match is None:
                 # not an option-- add to freeValues
                 self.freeValues = self.freeValues + [arg]
                 if not self.orderMixed:
                     # mixing not allowed;  add rest of args as freeValues
                     self.freeValues = self.freeValues + args[index:]
                     # return to caller
                     return
                 else:
                     continue
 
             # grab name
             optName = match.group('option')
 
             # obtain next argument-- index has already been incremented
             nextArg = match.group('arg')
             if nextArg:
                 nextArg = nextArg[1:]
                 index = index - 1 # put it back
             else:
                 try:
                     nextArg = args[index]
                 except:
                     nextArg = None
 
             # transpose to lower case, if necessary
             if self.ignoreCase:
                 optName = string.lower(optName)
 
             # obtain defining tuple
             tuples = self._getArgTuple(optName)
 
             if tuples == None:
                 raise ArgumentError('Illegal option \'' + arg + '\'')
             elif len(tuples) > 1:
                 raise ArgumentError('Ambiguous option \'' + arg +
                                     '\';  matches ' +
                                     repr(map(lambda x: x[0], tuples)))
             else:
                 config = tuples[0]
 
             # config is now set to the configuration tuple for the
             # argument
             (fullName, spec, realName) = config
             (optType, optMode, optDefault, optMultiple) = spec
 
             # if opt mode required, but nextArg is none, raise an error
             if (optMode == ArgRequired):
                 if (not nextArg) or self._isTerminator(nextArg):
 #                                       print nextArg
                     raise ArgumentError('Option \'' + arg +
                                         '\' requires an argument of type ' +
                                         optType)
 
             if (not optMode == None) and nextArg and (not self._isTerminator(nextArg)):
                 # nextArg defined, option configured to possibly consume arg
                 try:
                     # grab conversion function-- the try is more for internal diagnostics
                     func = ConversionFunctions[optType]
                     try:
                         optionValue = func(nextArg)
                         index = index + 1
                     except:
                         # only raise conversion error if REQUIRED to consume argument
                         if optMode == ArgRequired:
                             raise ArgumentError('Invalid argument to option \''
                                                 + arg + '\';  should be \'' +
                                                 optType + '\'')
                         else:
                             optionValue = optDefault
                 except ArgumentError:
                     raise
                 except:
                     raise ArgumentError('(' + arg +
                                         ') Conversion function for \'' +
                                         optType + '\' not found.')
             else:
                 optionValue = optDefault
 
             # add value to options dictionary
             if optMultiple:
                 # can be multiple values
                 try:
                     # try to append element
                     self.optionValues[realName] = self.optionValues[realName] + [optionValue]
                 except:
                     # failed-- must not exist;  add it
                     self.optionValues[realName] = [optionValue]
             else:
                 # only one value per
                 if self.isPosixCompliant and self.optionValues.has_key(realName):
                     raise ArgumentError('Argument \'' + arg +
                                         '\' occurs multiple times.')
 
                 self.optionValues[realName] = optionValue
 
     def valueForOption(self, optionName, defaultValue = None):
         """
         Return the value associated with optionName.  If optionName was
         not encountered during parsing of the arguments, returns the
         defaultValue (which defaults to None).
         """
         try:
             optionValue = self.optionValues[optionName]
         except:
             optionValue = defaultValue
 
         return optionValue
 
 ##
 ## test/example section
 ##
 test_error = 'Test Run Amok!'
 def _test():
     """
     A relatively complete test suite.
     """
     try:
         DPyGetOpt(['foo', 'bar=s', 'foo'])
     except Error, exc:
         print 'EXCEPTION (should be \'foo\' already used..): %s' % exc
 
     try:
         DPyGetOpt(['foo|bar|apple=s@', 'baz|apple!'])
     except Error, exc:
         print 'EXCEPTION (should be duplicate alias/name error): %s' % exc
 
     x = DPyGetOpt(['apple|atlas=i@', 'application|executable=f@'])
     try:
         x.processArguments(['-app', '29.3'])
     except Error, exc:
         print 'EXCEPTION (should be ambiguous argument): %s' % exc
 
     x = DPyGetOpt(['foo'], ['antigravity', 'antithesis'])
     try:
         x.processArguments(['-foo', 'anti'])
     except Error, exc:
         print 'EXCEPTION (should be ambiguous terminator): %s' % exc
 
     profile = ['plain-option',
                               'boolean-option!',
                               'list-of-integers=i@',
                               'list-real-option|list-real-alias|list-real-pseudonym=f@',
                               'optional-string-option:s',
                               'abbreviated-string-list=s@']
 
     terminators = ['terminator']
 
     args = ['-plain-option',
                       '+noboolean-option',
                       '--list-of-integers', '1',
                       '+list-of-integers', '2',
                       '-list-of-integers', '3',
                       'freeargone',
                       '-list-real-option', '1.1',
                       '+list-real-alias', '1.2',
                       '--list-real-pseudonym', '1.3',
                       'freeargtwo',
                       '-abbreviated-string-list', 'String1',
                       '--abbreviated-s', 'String2',
                       '-abbrev', 'String3',
                       '-a', 'String4',
                       '-optional-string-option',
                       'term',
                       'next option should look like an invalid arg',
                       '-a']
 
 
     print 'Using profile: ' + repr(profile)
     print 'With terminator: ' + repr(terminators)
     print 'Processing arguments: ' + repr(args)
 
     go = DPyGetOpt(profile, terminators)
     go.processArguments(args)
 
     print 'Options (and values): ' + repr(go.optionValues)
     print 'free args: ' + repr(go.freeValues)
     print 'term args: ' + repr(go.termValues)

IPython/Debugger.py

@@ -1,528 +1,522 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 2913 2007-12-31 12:42:14Z vivainio $"""
+http://www.python.org/2.2.3/license.html"""
 
 #*****************************************************************************
 #
 #       This file is licensed under the PSF license.
 #
 #       Copyright (C) 2001 Python Software Foundation, www.python.org
 #       Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
 #
 #
 #*****************************************************************************
 
-from IPython import Release
-__author__  = '%s <%s>' % Release.authors['Fernando']
-__license__ = 'Python'
-
 import bdb
 import cmd
 import linecache
 import os
 import sys
 
 from IPython import PyColorize, ColorANSI, ipapi
 from IPython.genutils import Term
 from IPython.excolors import exception_colors
 
 # See if we can use pydb.
 has_pydb = False
 prompt = 'ipdb> '
 #We have to check this directly from sys.argv, config struct not yet available
 if '-pydb' in sys.argv:
     try:        
         import pydb
         if hasattr(pydb.pydb, "runl") and pydb.version>'1.17':
             # Version 1.17 is broken, and that's what ships with Ubuntu Edgy, so we
             # better protect against it.
             has_pydb = True
     except ImportError:
         print "Pydb (http://bashdb.sourceforge.net/pydb/) does not seem to be available"
 
 if has_pydb:
     from pydb import Pdb as OldPdb
     #print "Using pydb for %run -d and post-mortem" #dbg
     prompt = 'ipydb> '
 else:
     from pdb import Pdb as OldPdb
 
 # Allow the set_trace code to operate outside of an ipython instance, even if
 # it does so with some limitations.  The rest of this support is implemented in
 # the Tracer constructor.
 def BdbQuit_excepthook(et,ev,tb):
     if et==bdb.BdbQuit:
         print 'Exiting Debugger.'
     else:
         BdbQuit_excepthook.excepthook_ori(et,ev,tb)
 
 def BdbQuit_IPython_excepthook(self,et,ev,tb):
     print 'Exiting Debugger.'
 
 class Tracer(object):
     """Class for local debugging, similar to pdb.set_trace.
 
     Instances of this class, when called, behave like pdb.set_trace, but
     providing IPython's enhanced capabilities.
 
     This is implemented as a class which must be initialized in your own code
     and not as a standalone function because we need to detect at runtime
     whether IPython is already active or not.  That detection is done in the
     constructor, ensuring that this code plays nicely with a running IPython,
     while functioning acceptably (though with limitations) if outside of it.
     """
 
     def __init__(self,colors=None):
         """Create a local debugger instance.
 
         :Parameters:
 
           - `colors` (None): a string containing the name of the color scheme to
         use, it must be one of IPython's valid color schemes.  If not given, the
         function will default to the current IPython scheme when running inside
         IPython, and to 'NoColor' otherwise.
 
         Usage example:
 
         from IPython.Debugger import Tracer; debug_here = Tracer()
 
         ... later in your code
         debug_here()  # -> will open up the debugger at that point.
 
         Once the debugger activates, you can use all of its regular commands to
         step through code, set breakpoints, etc.  See the pdb documentation
         from the Python standard library for usage details.
         """
 
         global __IPYTHON__
         try:
             __IPYTHON__
         except NameError:
             # Outside of ipython, we set our own exception hook manually
             __IPYTHON__ = ipapi.get(True,False)
             BdbQuit_excepthook.excepthook_ori = sys.excepthook
             sys.excepthook = BdbQuit_excepthook
             def_colors = 'NoColor'
             try:
                 # Limited tab completion support
                 import rlcompleter,readline
                 readline.parse_and_bind('tab: complete')
             except ImportError:
                 pass
         else:
             # In ipython, we use its custom exception handler mechanism
             ip = ipapi.get()
             def_colors = ip.options.colors
             ip.set_custom_exc((bdb.BdbQuit,),BdbQuit_IPython_excepthook)
 
         if colors is None:
             colors = def_colors
         self.debugger = Pdb(colors)
 
     def __call__(self):
         """Starts an interactive debugger at the point where called.
 
         This is similar to the pdb.set_trace() function from the std lib, but
         using IPython's enhanced debugger."""
         
         self.debugger.set_trace(sys._getframe().f_back)
 
 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
     """Make new_fn have old_fn's doc string. This is particularly useful
     for the do_... commands that hook into the help system.
     Adapted from from a comp.lang.python posting
     by Duncan Booth."""
     def wrapper(*args, **kw):
         return new_fn(*args, **kw)
     if old_fn.__doc__:
         wrapper.__doc__ = old_fn.__doc__ + additional_text
     return wrapper
 
 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(OldPdb):
     """Modified Pdb class, does not load readline."""
 
     if sys.version[:3] >= '2.5' or has_pydb:
         def __init__(self,color_scheme='NoColor',completekey=None,
                      stdin=None, stdout=None):
 
             # Parent constructor:
             if has_pydb and completekey is None:
                 OldPdb.__init__(self,stdin=stdin,stdout=Term.cout)
             else:
                 OldPdb.__init__(self,completekey,stdin,stdout)
                 
             self.prompt = prompt # The default prompt is '(Pdb)'
             
             # IPython changes...
             self.is_pydb = has_pydb
 
             if self.is_pydb:
 
                 # iplib.py's ipalias seems to want pdb's checkline
                 # which located in pydb.fn
                 import pydb.fns
                 self.checkline = lambda filename, lineno: \
                                  pydb.fns.checkline(self, filename, lineno)
 
                 self.curframe = None
                 self.do_restart = self.new_do_restart
 
                 self.old_all_completions = __IPYTHON__.Completer.all_completions
                 __IPYTHON__.Completer.all_completions=self.all_completions
 
                 self.do_list = decorate_fn_with_doc(self.list_command_pydb,
                                                     OldPdb.do_list)
                 self.do_l     = self.do_list
                 self.do_frame = decorate_fn_with_doc(self.new_do_frame,
                                                      OldPdb.do_frame)
 
             self.aliases = {}
 
             # Create color table: we copy the default one from the traceback
             # module and add a few attributes needed for debugging
             self.color_scheme_table = exception_colors()
 
             # 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)
 
             # Add a python parser so we can syntax highlight source while
             # debugging.
             self.parser = PyColorize.Parser()
 
 
     else:
         # Ugly hack: for Python 2.3-2.4, we can't call the parent constructor,
         # because it binds readline and breaks tab-completion.  This means we
         # have to COPY the constructor here.
         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 = {}
 
             # These two lines are part of the py2.4 constructor, let's put them
             # unconditionally here as they won't cause any problems in 2.3.
             self.mainpyfile = ''
             self._wait_for_mainpyfile = 0
 
             # 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 = exception_colors()
 
             # 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)
 
             # Add a python parser so we can syntax highlight source while
             # debugging.
             self.parser = PyColorize.Parser()
         
     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)
         OldPdb.interaction(self, frame, traceback)
 
     def new_do_up(self, arg):
         OldPdb.do_up(self, arg)
         __IPYTHON__.set_completer_frame(self.curframe)
     do_u = do_up = decorate_fn_with_doc(new_do_up, OldPdb.do_up)
 
     def new_do_down(self, arg):
         OldPdb.do_down(self, arg)
         __IPYTHON__.set_completer_frame(self.curframe)
 
     do_d = do_down = decorate_fn_with_doc(new_do_down, OldPdb.do_down)
 
     def new_do_frame(self, arg):
         OldPdb.do_frame(self, arg)
         __IPYTHON__.set_completer_frame(self.curframe)
 
     def new_do_quit(self, arg):
         
         if hasattr(self, 'old_all_completions'):
             __IPYTHON__.Completer.all_completions=self.old_all_completions
         
         
         return OldPdb.do_quit(self, arg)
 
     do_q = do_quit = decorate_fn_with_doc(new_do_quit, OldPdb.do_quit)
 
     def new_do_restart(self, arg):
         """Restart command. In the context of ipython this is exactly the same
         thing as 'quit'."""
         self.msg("Restart doesn't make sense here. Using 'quit' instead.")
         return self.do_quit(arg)
 
     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)
 
         # vds: >>
         frame, lineno = frame_lineno
         filename = frame.f_code.co_filename
         __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
         # vds: <<
 
     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 = '%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.append(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)
 
         # The level info should be generated in the same format pdb uses, to
         # avoid breaking the pdbtrack functionality of python-mode in *emacs.
         if frame is self.curframe:
             ret.append('> ')
         else:
             ret.append('  ')
         ret.append('%s(%s)%s\n' % (link,lineno,call))
             
         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,line in enumerate(lines):
             show_arrow = (start + 1 + i == lineno)
             linetpl = (frame is self.curframe or show_arrow) \
                       and tpl_line_em \
                       or tpl_line
             ret.append(self.__format_line(linetpl, filename,
                                           start + 1 + i, line,
                                           arrow = show_arrow) )
 
         return ''.join(ret)
 
     def __format_line(self, tpl_line, filename, lineno, line, arrow = False):
         bp_mark = ""
         bp_mark_color = ""
 
         scheme = self.color_scheme_table.active_scheme_name
         new_line, err = self.parser.format2(line, 'str', scheme)
         if not err: line = new_line
 
         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 list_command_pydb(self, arg):
         """List command to use if we have a newer pydb installed"""
         filename, first, last = OldPdb.parse_list_cmd(self, arg)
         if filename is not None:
             self.print_list_lines(filename, first, last)
         
     def print_list_lines(self, filename, first, last):
         """The printing (as opposed to the parsing part of a 'list'
         command."""
         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
 
     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
         self.print_list_lines(self.curframe.f_code.co_filename, first, last)
 
         # vds: >>
         lineno = first
         filename = self.curframe.f_code.co_filename
         __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
         # vds: <<
 
     do_l = do_list
 
     def do_pdef(self, arg):
         """The debugger interface to magic_pdef"""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         __IPYTHON__.magic_pdef(arg, namespaces=namespaces)
 
     def do_pdoc(self, arg):
         """The debugger interface to magic_pdoc"""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         __IPYTHON__.magic_pdoc(arg, namespaces=namespaces)
 
     def do_pinfo(self, arg):
         """The debugger equivalant of ?obj"""
         namespaces = [('Locals', self.curframe.f_locals),
                       ('Globals', self.curframe.f_globals)]
         __IPYTHON__.magic_pinfo("pinfo %s" % arg, namespaces=namespaces)

IPython/Extensions/InterpreterExec.py

@@ -1,259 +1,253 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 2724 2007-09-07 08:05:38Z fperez $"""
+"""
 
 #*****************************************************************************
 #       Copyright (C) 2004 W.J. van der Laan <[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
-
 # TODO: deprecated
 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.
 
 
 #  Set the 'cd' command to quiet mode, a more shell-like behavior
 __IPYTHON__.default_option('cd','-q')
 
 # This is redundant, ipy_user_conf.py will determine this
 # Load all of $PATH as aliases
 __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/ext_rescapture.py

@@ -1,66 +1,63 b''
 # -*- coding: utf-8 -*-
 """ IPython extension: new prefilters for output grabbing 
 
 Provides 
 
 var = %magic blah blah
 
 var = !ls
-
-$Id: genutils.py 1077 2006-01-24 18:15:27Z vivainio $
-
 """
 
 import IPython.ipapi
 from IPython.genutils import *
 
 ip = IPython.ipapi.get()
 
 import re
 
 def hnd_magic(line,mo):
     """ Handle a = %mymagic blah blah """
     #cmd = genutils.make_quoted_expr(mo.group('syscmd'))
     #mag = 'ipmagic
     #return "%s = %s"
     var = mo.group('varname')
     cmd = mo.group('cmd')
     expr = make_quoted_expr(cmd)
     return itpl('$var = _ip.magic($expr)')
 
 def hnd_syscmd(line,mo):
     """ Handle a = !ls """
     #cmd = genutils.make_quoted_expr(mo.group('syscmd'))
     #mag = 'ipmagic
     #return "%s = %s"
     var = mo.group('varname')
     cmd = mo.group('cmd')
     expr = make_quoted_expr(itpl("sc -l =$cmd"))
     return itpl('$var = _ip.magic($expr)')
 
 def install_re_handler(pat, hnd):
     ip.meta.re_prefilters.append((re.compile(pat), hnd))
 
 def init_handlers():
 
     ip.meta.re_prefilters = []
 
     install_re_handler('(?P<varname>[\w\.]+)\s*=\s*%(?P<cmd>.*)',
                        hnd_magic
                        )
     
     install_re_handler('(?P<varname>[\w\.]+)\s*=\s*!(?P<cmd>.*)',
                        hnd_syscmd
                        )
 
 init_handlers()
 
 def regex_prefilter_f(self,line):    
     for pat, handler in ip.meta.re_prefilters:
         mo = pat.match(line)
         if mo:
             return handler(line,mo)
     
     raise IPython.ipapi.TryNext
 
 ip.set_hook('input_prefilter', regex_prefilter_f)     

IPython/Extensions/pspersistence.py

@@ -1,184 +1,182 b''
 # -*- coding: utf-8 -*-
 """
 %store magic for lightweight persistence.
 
 Stores variables, aliases etc. in PickleShare database.
-
-$Id: iplib.py 1107 2006-01-30 19:02:20Z vivainio $
 """
 
 import IPython.ipapi
 from IPython.ipapi import UsageError
 ip = IPython.ipapi.get()
 
 import pickleshare
 
 import inspect,pickle,os,sys,textwrap
 from IPython.FakeModule import FakeModule
 
 def restore_aliases(self):
     ip = self.getapi()
     staliases = ip.db.get('stored_aliases', {})
     for k,v in staliases.items():
         #print "restore alias",k,v # dbg
         #self.alias_table[k] = v
         ip.defalias(k,v)
 
 
 def refresh_variables(ip):
     db = ip.db
     for key in db.keys('autorestore/*'):
         # strip autorestore
         justkey = os.path.basename(key)
         try:
             obj = db[key]
         except KeyError:
             print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey
             print "The error was:",sys.exc_info()[0]
         else:
             #print "restored",justkey,"=",obj #dbg
             ip.user_ns[justkey] = obj
     
 
 def restore_dhist(ip):
     db = ip.db
     ip.user_ns['_dh'] = db.get('dhist',[])
     
 def restore_data(self):
     ip = self.getapi()
     refresh_variables(ip)
     restore_aliases(self)
     restore_dhist(self)
     raise IPython.ipapi.TryNext
     
 ip.set_hook('late_startup_hook', restore_data)
 
 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 -z       - Remove all variables from storage\\
     %store -r       - Refresh all variables from store (delete current vals)\\
     %store foo >a.txt  - Store value of foo to new file a.txt\\
     %store foo >>a.txt - Append value of foo to file a.txt\\   
     
     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.
     
     Also aliases can be %store'd across sessions.
     """
     
     opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
     args = argsl.split(None,1)
     ip = self.getapi()
     db = ip.db
     # delete
     if opts.has_key('d'):
         try:
             todel = args[0]
         except IndexError:
             raise UsageError('You must provide the variable to forget')
         else:
             try:
                 del db['autorestore/' + todel]
             except:
                 raise UsageError("Can't delete variable '%s'" % todel)
     # reset
     elif opts.has_key('z'):
         for k in db.keys('autorestore/*'):
             del db[k]
 
     elif opts.has_key('r'):
         refresh_variables(ip)
 
     
     # run without arguments -> list variables & values
     elif not args:
         vars = self.db.keys('autorestore/*')
         vars.sort()            
         if vars:
             size = max(map(len,vars))
         else:
             size = 0
             
         print 'Stored variables and their in-db values:'
         fmt = '%-'+str(size)+'s -> %s'
         get = db.get
         for var in vars:
             justkey = os.path.basename(var)
             # print 30 first characters from every var
             print fmt % (justkey,repr(get(var,'<unavailable>'))[:50])
     
     # default action - store the variable
     else:
         # %store foo >file.txt or >>file.txt
         if len(args) > 1 and args[1].startswith('>'):
             fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
             if args[1].startswith('>>'):
                 fil = open(fnam,'a')
             else:
                 fil = open(fnam,'w')
             obj = ip.ev(args[0])
             print "Writing '%s' (%s) to file '%s'." % (args[0],
               obj.__class__.__name__, fnam)
 
             
             if not isinstance (obj,basestring):
                 from pprint import pprint
                 pprint(obj,fil)
             else:
                 fil.write(obj)
                 if not obj.endswith('\n'):
                     fil.write('\n')
             
             fil.close()
             return
         
         # %store foo
         try:
             obj = ip.user_ns[args[0]]
         except KeyError:
             # it might be an alias
             if args[0] in self.alias_table:
                 staliases = db.get('stored_aliases',{})
                 staliases[ args[0] ] = self.alias_table[ args[0] ]
                 db['stored_aliases'] = staliases                
                 print "Alias stored:", args[0], self.alias_table[ args[0] ]
                 return
             else:
                 raise UsageError("Unknown variable '%s'" % args[0])
             
         else:
             if isinstance(inspect.getmodule(obj), FakeModule):
                 print textwrap.dedent("""\
                 Warning:%s is %s 
                 Proper storage of interactively declared classes (or instances
                 of those classes) is not possible! Only instances
                 of classes in real modules on file system can be %%store'd.
                 """ % (args[0], obj) ) 
                 return
             #pickled = pickle.dumps(obj)
             self.db[ 'autorestore/' + args[0] ] = obj
             print "Stored '%s' (%s)" % (args[0], obj.__class__.__name__)
 
 ip.expose_magic('store',magic_store)

IPython/FakeModule.py

@@ -1,43 +1,42 b''
 # -*- coding: utf-8 -*-
 """
 Class which mimics a module.
 
 Needed to allow pickle to correctly resolve namespaces during IPython
 sessions.
-
-$Id: FakeModule.py 2754 2007-09-09 10:16:59Z fperez $"""
+"""
 
 #*****************************************************************************
 #       Copyright (C) 2002-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.
 #*****************************************************************************
 
 import types
 
 class FakeModule(types.ModuleType):
     """Simple class with attribute access to fake a module.
 
     This is not meant to replace a module, but to allow inserting a fake
     module in sys.modules so that systems which rely on run-time module
     importing (like shelve and pickle) work correctly in interactive IPython
     sessions.
 
     Do NOT use this code for anything other than this IPython private hack."""
 
     def __init__(self,adict=None):
         
         # tmp to force __dict__ instance creation, else self.__dict__ fails
         self.__iptmp = None
         
         # It seems pydoc (and perhaps others) needs any module instance to
         # implement a __nonzero__ method, so we add it if missing:
         self.__dict__.setdefault('__nonzero__',lambda : True)
         self.__dict__.setdefault('__file__',__file__)
 
         # cleanup our temp trick
         del self.__iptmp
 
         if adict is not None:
             self.__dict__.update(adict)

IPython/Gnuplot2.py

@@ -1,666 +1,665 b''
 # -*- coding: utf-8 -*-
 """Improved replacement for the Gnuplot.Gnuplot class.
 
 This module imports Gnuplot and replaces some of its functionality with
 improved versions. They add better handling of arrays for plotting and more
 convenient PostScript generation, plus some fixes for hardcopy().
 
 It also adds a convenient plot2 method for plotting dictionaries and
 lists/tuples of arrays.
 
 This module is meant to be used as a drop-in replacement to the original
 Gnuplot, so it should be safe to do:
 
 import IPython.Gnuplot2 as Gnuplot
-
-$Id: Gnuplot2.py 1210 2006-03-13 01:19:31Z fperez $"""
+"""
 
 import cStringIO
 import os
 import string
 import sys
 import tempfile
 import time
 import types
 
 import Gnuplot as Gnuplot_ori
 import Numeric
 
 from IPython.genutils import popkey,xsys
 
 # needed by hardcopy():
 gp = Gnuplot_ori.gp
 
 # Patch for Gnuplot.py 1.6 compatibility.
 # Thanks to Hayden Callow <[e-mail]>
 try:
     OptionException = Gnuplot_ori.PlotItems.OptionException
 except AttributeError:
     OptionException = Gnuplot_ori.Errors.OptionError
 
 # exhibit a similar interface to Gnuplot so it can be somewhat drop-in
 Data      = Gnuplot_ori.Data
 Func      = Gnuplot_ori.Func
 GridData  = Gnuplot_ori.GridData
 PlotItem  = Gnuplot_ori.PlotItem
 PlotItems = Gnuplot_ori.PlotItems
 
 # Modify some of Gnuplot's functions with improved versions (or bugfixed, in
 # hardcopy's case). In order to preserve the docstrings at runtime, I've
 # copied them from the original code.
 
 # After some significant changes in v 1.7 of Gnuplot.py, we need to do a bit
 # of version checking.
 
 if Gnuplot_ori.__version__ <= '1.6':
     _BaseFileItem = PlotItems.File
     _BaseTempFileItem = PlotItems.TempFile
 
     # Fix the File class to add the 'index' option for Gnuplot versions < 1.7
     class File(_BaseFileItem):
 
         _option_list = _BaseFileItem._option_list.copy()
         _option_list.update({
             'index' : lambda self, index: self.set_option_index(index),
             })
 
         # A new initializer is needed b/c we want to add a modified
         # _option_sequence list which includes 'index' in the right place.
         def __init__(self,*args,**kw):
             self._option_sequence = ['binary', 'index', 'using', 'smooth', 'axes',
                          'title', 'with']
 
             _BaseFileItem.__init__(self,*args,**kw)
 
         # Let's fix the constructor docstring
         __newdoc = \
             """Additional Keyword arguments added by IPython:
 
              'index=<int>' -- similar to the `index` keyword in Gnuplot.
                  This allows only some of the datasets in a file to be
                  plotted. Datasets within a file are assumed to be separated
                  by _pairs_ of blank lines, and the first one is numbered as
                  0 (similar to C/Python usage)."""
         __init__.__doc__ = PlotItems.File.__init__.__doc__ + __newdoc
 
         def set_option_index(self, index):
             if index is None:
                 self.clear_option('index')
             elif type(index) in [type(''), type(1)]:
                 self._options['index'] = (index, 'index %s' % index)
             elif type(index) is type(()):
                 self._options['index'] = (index,'index %s' %
                                           string.join(map(repr, index), ':'))
             else:
                 raise OptionException('index=%s' % (index,))
 
     # We need a FileClass with a different name from 'File', which is a
     # factory function in 1.7, so that our String class can subclass FileClass
     # in any version.
     _FileClass = File
 
 elif Gnuplot_ori.__version__ =='1.7':
     _FileClass = _BaseFileItem = PlotItems._FileItem
     _BaseTempFileItem = PlotItems._TempFileItem
     File = PlotItems.File
 
 else:  # changes in the newer version (svn as of March'06)
      _FileClass = _BaseFileItem = PlotItems._FileItem
      _BaseTempFileItem = PlotItems._NewFileItem
      File = PlotItems.File
 
 
 # Now, we can add our generic code which is version independent
 
 # First some useful utilities
 def eps_fix_bbox(fname):
     """Fix the bounding box of an eps file by running ps2eps on it.
 
     If its name ends in .eps, the original file is removed.
 
     This is particularly useful for plots made by Gnuplot with square aspect
     ratio: there is a bug in Gnuplot which makes it generate a bounding box
     which is far wider than the actual plot.
 
     This function assumes that ps2eps is installed in your system."""
 
     # note: ps2ps and eps2eps do NOT work, ONLY ps2eps works correctly. The
     # others make output with bitmapped fonts, which looks horrible.
     print 'Fixing eps file: <%s>' % fname
     xsys('ps2eps -f -q -l %s' % fname)
     if fname.endswith('.eps'):
         os.rename(fname+'.eps',fname)
 
 def is_list1d(x,containers = [types.ListType,types.TupleType]):
     """Returns true if x appears to be a 1d list/tuple/array.
 
     The heuristics are: identify Numeric arrays, or lists/tuples whose first
     element is not itself a list/tuple. This way zipped lists should work like
     the original Gnuplot. There's no inexpensive way to know if a list doesn't
     have a composite object after its first element, so that kind of input
     will produce an error. But it should work well in most cases.
     """
     x_type = type(x)
 
     return x_type == Numeric.ArrayType and len(x.shape)==1 or \
            (x_type in containers and
             type(x[0]) not in containers + [Numeric.ArrayType])
 
 def zip_items(items,titles=None):
     """zip together neighboring 1-d arrays, and zip standalone ones
     with their index. Leave other plot items alone."""
 
     class StandaloneItem(Exception): pass
     
     def get_titles(titles):
         """Return the next title and the input titles array.
 
         The input array may be changed to None when no titles are left to
         prevent extra unnecessary calls to this function."""
         
         try:
             title = titles[tit_ct[0]]  # tit_ct[0] is in zip_items'scope
         except IndexError:
             titles = None # so we don't enter again
             title = None
         else:
             tit_ct[0] += 1
         return title,titles
 
     new_items = []
 
     if titles:
         # Initialize counter. It was put in a list as a hack to allow the
         # nested get_titles to modify it without raising a NameError.
         tit_ct = [0]
 
     n = 0  # this loop needs to be done by hand
     while n < len(items):
         item = items[n]
         try:
             if is_list1d(item):
                 if n==len(items)-1: # last in list
                     raise StandaloneItem
                 else: # check the next item and zip together if needed
                     next_item = items[n+1]
                     if next_item is None:
                         n += 1
                         raise StandaloneItem
                     elif is_list1d(next_item):
                         # this would be best done with an iterator
                         if titles:
                             title,titles = get_titles(titles)
                         else:
                             title = None
                         new_items.append(Data(zip(item,next_item),
                                               title=title))
                         n += 1  # avoid double-inclusion of next item
                     else: # can't zip with next, zip with own index list
                         raise StandaloneItem
             else:  # not 1-d array
                 new_items.append(item)
         except StandaloneItem:
             if titles:
                 title,titles = get_titles(titles)
             else:
                 title = None
             new_items.append(Data(zip(range(len(item)),item),title=title))
         except AttributeError:
             new_items.append(item)
         n+=1
 
     return new_items
 
 # And some classes with enhanced functionality.
 class String(_FileClass):
     """Make a PlotItem from data in a string with the same format as a File.
 
     This allows writing data directly inside python scripts using the exact
     same format and manipulation options which would be used for external
     files."""
 
     def __init__(self, data_str, **keyw):
         """Construct a String object.
 
         <data_str> is a string formatted exactly like a valid Gnuplot data
         file would be. All options from the File constructor are valid here.
 
         Warning: when used for interactive plotting in scripts which exit
         immediately, you may get an error because the temporary file used to
         hold the string data was deleted before Gnuplot had a chance to see
         it. You can work around this problem by putting a raw_input() call at
         the end of the script.
 
         This problem does not appear when generating PostScript output, only
         with Gnuplot windows."""
 
         self.tmpfile = _BaseTempFileItem()
         tmpfile = file(self.tmpfile.filename,'w')
         tmpfile.write(data_str)
         _BaseFileItem.__init__(self,self.tmpfile,**keyw)
 
 
 class Gnuplot(Gnuplot_ori.Gnuplot):
     """Improved Gnuplot class.
 
     Enhancements: better plot,replot and hardcopy methods. New methods for
     quick range setting.
     """
 
     def xrange(self,min='*',max='*'):
         """Set xrange. If min/max is omitted, it is set to '*' (auto).
 
         Note that this is different from the regular Gnuplot behavior, where
         an unspecified limit means no change. Here any unspecified limit is
         set to autoscaling, allowing these functions to be used for full
         autoscaling when called with no arguments.
 
         To preserve one limit's current value while changing the other, an
         explicit '' argument must be given as the limit to be kept.
 
         Similar functions exist for [y{2}z{2}rtuv]range."""
         
         self('set xrange [%s:%s]' % (min,max))
              
     def yrange(self,min='*',max='*'):
         self('set yrange [%s:%s]' % (min,max))
              
     def zrange(self,min='*',max='*'):
         self('set zrange [%s:%s]' % (min,max))
              
     def x2range(self,min='*',max='*'):
         self('set xrange [%s:%s]' % (min,max))
              
     def y2range(self,min='*',max='*'):
         self('set yrange [%s:%s]' % (min,max))
              
     def z2range(self,min='*',max='*'):
         self('set zrange [%s:%s]' % (min,max))
              
     def rrange(self,min='*',max='*'):
         self('set rrange [%s:%s]' % (min,max))
              
     def trange(self,min='*',max='*'):
         self('set trange [%s:%s]' % (min,max))
              
     def urange(self,min='*',max='*'):
         self('set urange [%s:%s]' % (min,max))
              
     def vrange(self,min='*',max='*'):
         self('set vrange [%s:%s]' % (min,max))
 
     def set_ps(self,option):
         """Set an option for the PostScript terminal and reset default term."""
 
         self('set terminal postscript %s ' % option)
         self('set terminal %s' % gp.GnuplotOpts.default_term)
 
     def __plot_ps(self, plot_method,*items, **keyw):
         """Wrapper for plot/splot/replot, with processing of hardcopy options.
 
         For internal use only."""
 
         # Filter out PostScript options which will crash the normal plot/replot
         psargs = {'filename':None,
                   'mode':None,
                   'eps':None,
                   'enhanced':None,
                   'color':None,
                   'solid':None,
                   'duplexing':None,
                   'fontname':None,
                   'fontsize':None,
                   'debug':0 }
 
         for k in psargs.keys():
             if keyw.has_key(k):
                 psargs[k] = keyw[k]
                 del keyw[k]
 
         # Filter out other options the original plot doesn't know
         hardcopy = popkey(keyw,'hardcopy',psargs['filename'] is not None)
         titles = popkey(keyw,'titles',0)
         
         # the filename keyword should control hardcopy generation, this is an
         # override switch only which needs to be explicitly set to zero
         if hardcopy:
             if psargs['filename'] is None:
                 raise ValueError, \
                       'If you request hardcopy, you must give a filename.'
 
             # set null output so nothing goes to screen. hardcopy() restores output
             self('set term dumb')
             # I don't know how to prevent screen output in Windows
             if os.name == 'posix':
                 self('set output "/dev/null"')
 
         new_items = zip_items(items,titles)
         # plot_method is either plot or replot from the original Gnuplot class:
         plot_method(self,*new_items,**keyw)
 
         # Do hardcopy if requested
         if hardcopy:
             if psargs['filename'].endswith('.eps'):
                 psargs['eps'] = 1
             self.hardcopy(**psargs)
 
     def plot(self, *items, **keyw):
         """Draw a new plot.
 
         Clear the current plot and create a new 2-d plot containing
         the specified items.  Each arguments should be of the
         following types:
 
         'PlotItem' (e.g., 'Data', 'File', 'Func') -- This is the most
             flexible way to call plot because the PlotItems can
             contain suboptions.  Moreover, PlotItems can be saved to
             variables so that their lifetime is longer than one plot
             command; thus they can be replotted with minimal overhead.
 
         'string' (e.g., 'sin(x)') -- The string is interpreted as
             'Func(string)' (a function that is computed by gnuplot).
 
         Anything else -- The object, which should be convertible to an
             array, is passed to the 'Data' constructor, and thus
             plotted as data.  If the conversion fails, an exception is
             raised.
 
 
         This is a modified version of plot(). Compared to the original in
         Gnuplot.py, this version has several enhancements, listed below.
 
 
         Modifications to the input arguments
         ------------------------------------
 
         (1-d array means Numeric array, list or tuple):
 
         (i) Any 1-d array which is NOT followed by another 1-d array, is
         automatically zipped with range(len(array_1d)). Typing g.plot(y) will
         plot y against its indices.
 
         (ii) If two 1-d arrays are contiguous in the argument list, they are
         automatically zipped together. So g.plot(x,y) plots y vs. x, and
         g.plot(x1,y1,x2,y2) plots y1 vs. x1 and y2 vs. x2.
 
         (iii) Any 1-d array which is followed by None is automatically zipped
         with range(len(array_1d)). In this form, typing g.plot(y1,None,y2)
         will plot both y1 and y2 against their respective indices (and NOT
         versus one another). The None prevents zipping y1 and y2 together, and
         since y2 is unpaired it is automatically zipped to its indices by (i)
 
         (iv) Any other arguments which don't match these cases are left alone and
         passed to the code below.
 
         For lists or tuples, the heuristics used to determine whether they are
         in fact 1-d is fairly simplistic: their first element is checked, and
         if it is not a list or tuple itself, it is assumed that the whole
         object is one-dimensional.
 
         An additional optional keyword 'titles' has been added: it must be a
         list of strings to be used as labels for the individual plots which
         are NOT PlotItem objects (since those objects carry their own labels
         within).
 
 
         PostScript generation
         ---------------------
 
         This version of plot() also handles automatically the production of
         PostScript output. The main options are (given as keyword arguments):
 
         - filename: a string, typically ending in .eps. If given, the plot is
         sent to this file in PostScript format.
         
         - hardcopy: this can be set to 0 to override 'filename'. It does not
         need to be given to produce PostScript, its purpose is to allow
         switching PostScript output off globally in scripts without having to
         manually change 'filename' values in multiple calls.
 
         All other keywords accepted by Gnuplot.hardcopy() are transparently
         passed, and safely ignored if output is sent to the screen instead of
         PostScript.
 
         For example:
         
         In [1]: x=frange(0,2*pi,npts=100)
 
         Generate a plot in file 'sin.eps':
 
         In [2]: plot(x,sin(x),filename = 'sin.eps')
 
         Plot to screen instead, without having to change the filename:
 
         In [3]: plot(x,sin(x),filename = 'sin.eps',hardcopy=0)
 
         Pass the 'color=0' option to hardcopy for monochrome output:
 
         In [4]: plot(x,sin(x),filename = 'sin.eps',color=0)
 
         PostScript generation through plot() is useful mainly for scripting
         uses where you are not interested in interactive plotting. For
         interactive use, the hardcopy() function is typically more convenient:
         
         In [5]: plot(x,sin(x))
 
         In [6]: hardcopy('sin.eps')  """
         
         self.__plot_ps(Gnuplot_ori.Gnuplot.plot,*items,**keyw)
         
     def plot2(self,arg,**kw):
         """Plot the entries of a dictionary or a list/tuple of arrays.        
         
         This simple utility calls plot() with a list of Gnuplot.Data objects
         constructed either from the values of the input dictionary, or the entries
         in it if it is a tuple or list.  Each item gets labeled with the key/index
         in the Gnuplot legend.
 
         Each item is plotted by zipping it with a list of its indices.
 
         Any keywords are passed directly to plot()."""
 
         if hasattr(arg,'keys'):
             keys = arg.keys()
             keys.sort()
         else:
             keys = range(len(arg))
 
         pitems = [Data(zip(range(len(arg[k])),arg[k]),title=`k`) for k in keys]
         self.plot(*pitems,**kw)
 
     def splot(self, *items, **keyw):
         """Draw a new three-dimensional plot.
 
         Clear the current plot and create a new 3-d plot containing
         the specified items.  Arguments can be of the following types:
 
         'PlotItem' (e.g., 'Data', 'File', 'Func', 'GridData' ) -- This
             is the most flexible way to call plot because the
             PlotItems can contain suboptions.  Moreover, PlotItems can
             be saved to variables so that their lifetime is longer
             than one plot command--thus they can be replotted with
             minimal overhead.
 
         'string' (e.g., 'sin(x*y)') -- The string is interpreted as a
             'Func()' (a function that is computed by gnuplot).
 
         Anything else -- The object is converted to a Data() item, and
             thus plotted as data.  Note that each data point should
             normally have at least three values associated with it
             (i.e., x, y, and z).  If the conversion fails, an
             exception is raised.
 
         This is a modified version of splot(). Compared to the original in
         Gnuplot.py, this version has several enhancements, listed in the
         plot() documentation.
         """
         
         self.__plot_ps(Gnuplot_ori.Gnuplot.splot,*items,**keyw)
 
     def replot(self, *items, **keyw):
         """Replot the data, possibly adding new 'PlotItem's.
 
         Replot the existing graph, using the items in the current
         itemlist.  If arguments are specified, they are interpreted as
         additional items to be plotted alongside the existing items on
         the same graph.  See 'plot' for details.
 
         If you want to replot to a postscript file, you MUST give the
         'filename' keyword argument in each call to replot. The Gnuplot python
         interface has no way of knowing that your previous call to
         Gnuplot.plot() was meant for PostScript output."""
         
         self.__plot_ps(Gnuplot_ori.Gnuplot.replot,*items,**keyw)
 
     # The original hardcopy has a bug. See fix at the end. The rest of the code
     # was lifted verbatim from the original, so that people using IPython get the
     # benefits without having to manually patch Gnuplot.py
     def hardcopy(self, filename=None,
                  mode=None,
                  eps=None,
                  enhanced=None,
                  color=None,
                  solid=None,
                  duplexing=None,
                  fontname=None,
                  fontsize=None,
                  debug = 0,
                  ):
         """Create a hardcopy of the current plot.
 
         Create a postscript hardcopy of the current plot to the
         default printer (if configured) or to the specified filename.
 
         Note that gnuplot remembers the postscript suboptions across
         terminal changes.  Therefore if you set, for example, color=1
         for one hardcopy then the next hardcopy will also be color
         unless you explicitly choose color=0.  Alternately you can
         force all of the options to their defaults by setting
         mode='default'.  I consider this to be a bug in gnuplot.
 
         Keyword arguments:
 
           'filename=<string>' -- if a filename is specified, save the
               output in that file; otherwise print it immediately
               using the 'default_lpr' configuration option.  If the
               filename ends in '.eps', EPS mode is automatically
               selected (like manually specifying eps=1 or mode='eps').
 
           'mode=<string>' -- set the postscript submode ('landscape',
               'portrait', 'eps', or 'default').  The default is
               to leave this option unspecified.
 
           'eps=<bool>' -- shorthand for 'mode="eps"'; asks gnuplot to
               generate encapsulated postscript.
 
           'enhanced=<bool>' -- if set (the default), then generate
               enhanced postscript, which allows extra features like
               font-switching, superscripts, and subscripts in axis
               labels.  (Some old gnuplot versions do not support
               enhanced postscript; if this is the case set
               gp.GnuplotOpts.prefer_enhanced_postscript=None.)
 
           'color=<bool>' -- if set, create a plot with color.  Default
               is to leave this option unchanged.
 
           'solid=<bool>' -- if set, force lines to be solid (i.e., not
               dashed).
 
           'duplexing=<string>' -- set duplexing option ('defaultplex',
               'simplex', or 'duplex').  Only request double-sided
               printing if your printer can handle it.  Actually this
               option is probably meaningless since hardcopy() can only
               print a single plot at a time.
 
           'fontname=<string>' -- set the default font to <string>,
               which must be a valid postscript font.  The default is
               to leave this option unspecified.
 
           'fontsize=<double>' -- set the default font size, in
               postscript points.
 
           'debug=<bool>' -- print extra debugging information (useful if
               your PostScript files are misteriously not being created).
         """
 
         if filename is None:
             assert gp.GnuplotOpts.default_lpr is not None, \
                    OptionException('default_lpr is not set, so you can only '
                                    'print to a file.')
             filename = gp.GnuplotOpts.default_lpr
             lpr_output = 1
         else:
             if filename.endswith('.eps'):
                 eps = 1
             lpr_output = 0
 
         # Be careful processing the options.  If the user didn't
         # request an option explicitly, do not specify it on the 'set
         # terminal' line (don't even specify the default value for the
         # option).  This is to avoid confusing older versions of
         # gnuplot that do not support all of these options.  The
         # exception is 'enhanced', which is just too useful to have to
         # specify each time!
 
         setterm = ['set', 'terminal', 'postscript']
         if eps:
             assert mode is None or mode=='eps', \
                    OptionException('eps option and mode are incompatible')
             setterm.append('eps')
         else:
             if mode is not None:
                 assert mode in ['landscape', 'portrait', 'eps', 'default'], \
                        OptionException('illegal mode "%s"' % mode)
                 setterm.append(mode)
         if enhanced is None:
             enhanced = gp.GnuplotOpts.prefer_enhanced_postscript
         if enhanced is not None:
             if enhanced: setterm.append('enhanced')
             else: setterm.append('noenhanced')
         if color is not None:
             if color: setterm.append('color')
             else: setterm.append('monochrome')
         if solid is not None:
             if solid: setterm.append('solid')
             else: setterm.append('dashed')
         if duplexing is not None:
             assert duplexing in ['defaultplex', 'simplex', 'duplex'], \
                    OptionException('illegal duplexing mode "%s"' % duplexing)
             setterm.append(duplexing)
         if fontname is not None:
             setterm.append('"%s"' % fontname)
         if fontsize is not None:
             setterm.append('%s' % fontsize)
 
         self(string.join(setterm))
         self.set_string('output', filename)
         # replot the current figure (to the printer):
         self.refresh()
 
         # fperez. Ugly kludge: often for some reason the file is NOT created
         # and we must reissue the creation commands. I have no idea why!
         if not lpr_output:
             #print 'Hardcopy <%s>' % filename  # dbg
             maxtries = 20
             delay = 0.1  # delay (in seconds) between print attempts
             for i in range(maxtries):
                 time.sleep(0.05)  # safety, very small delay
                 if os.path.isfile(filename):
                     if debug:
                         print 'Hardcopy to file <%s> success at attempt #%s.' \
                         % (filename,i+1)
                     break
                 time.sleep(delay)
                 # try again, issue all commands just in case
                 self(string.join(setterm))
                 self.set_string('output', filename)
                 self.refresh()
             if not os.path.isfile(filename):
                 print >> sys.stderr,'ERROR: Tried %s times and failed to '\
                 'create hardcopy file `%s`' % (maxtries,filename)
 
         # reset the terminal to its `default' setting:
         self('set terminal %s' % gp.GnuplotOpts.default_term)
         self.set_string('output')
 
 #********************** End of file <Gnuplot2.py> ************************

IPython/GnuplotInteractive.py

@@ -1,148 +1,147 b''
 # -*- coding: utf-8 -*-
 """Interactive functions and magic functions for Gnuplot usage.
 
 This requires the Gnuplot.py module for interfacing python with Gnuplot, which
 can be downloaded from:
 
 http://gnuplot-py.sourceforge.net/
 
 See gphelp() below for details on the services offered by this module.
 
 Inspired by a suggestion/request from Arnd Baecker.
-
-$Id: GnuplotInteractive.py 389 2004-10-09 07:59:30Z fperez $"""
+"""
 
 __all__ = ['Gnuplot','gp','gp_new','plot','plot2','splot','replot',
            'hardcopy','gpdata','gpfile','gpstring','gpfunc','gpgrid',
            'gphelp']
 
 import IPython.GnuplotRuntime as GRun
 from IPython.genutils import page,warn
 
 # Set global names for interactive use
 Gnuplot  = GRun.Gnuplot
 gp_new   = GRun.gp_new
 gp       = GRun.gp
 plot     = gp.plot
 plot2    = gp.plot2
 splot    = gp.splot
 replot   = gp.replot
 hardcopy = gp.hardcopy
 
 # Accessors for the main plot object constructors:
 gpdata   = Gnuplot.Data
 gpfile   = Gnuplot.File
 gpstring = Gnuplot.String
 gpfunc   = Gnuplot.Func
 gpgrid   = Gnuplot.GridData
 
 def gphelp():
     """Print information about the Gnuplot facilities in IPython."""
 
     page("""
 IPython provides an interface to access the Gnuplot scientific plotting
 system, in an environment similar to that of Mathematica or Matlab.
 
 New top-level global objects
 ----------------------------
 
 Please see their respective docstrings for further details.
 
 - gp: a running Gnuplot instance. You can access its methods as
 gp.<method>. gp(`a string`) will execute the given string as if it had been
 typed in an interactive gnuplot window.
 
 - plot, splot, replot and hardcopy: aliases to the methods of the same name in
 the global running Gnuplot instance gp. These allow you to simply type:
 
 In [1]: plot(x,sin(x),title='Sin(x)')  # assuming x is a Numeric array
 
 and obtain a plot of sin(x) vs x with the title 'Sin(x)'.
 
 - gp_new: a function which returns a new Gnuplot instance. This can be used to
 have multiple Gnuplot instances running in your session to compare different
 plots, each in a separate window.
 
 - Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
 the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
 functions with improved versions (Gnuplot2 comes with IPython).
 
 - gpdata, gpfile, gpstring, gpfunc, gpgrid: aliases to Gnuplot.Data,
 Gnuplot.File, Gnuplot.String, Gnuplot.Func and Gnuplot.GridData
 respectively. These functions create objects which can then be passed to the
 plotting commands. See the Gnuplot.py documentation for details.
 
 Keep in mind that all commands passed to a Gnuplot instance are executed in
 the Gnuplot namespace, where no Python variables exist. For example, for
 plotting sin(x) vs x as above, typing
 
 In [2]: gp('plot x,sin(x)')
 
 would not work. Instead, you would get the plot of BOTH the functions 'x' and
 'sin(x)', since Gnuplot doesn't know about the 'x' Python array. The plot()
 method lives in python and does know about these variables.
 
 
 New magic functions
 -------------------
 
 %gpc: pass one command to Gnuplot and execute it or open a Gnuplot shell where
 each line of input is executed.
 
 %gp_set_default: reset the value of IPython's global Gnuplot instance.""")
     
 # Code below is all for IPython use
 # Define the magic functions for communicating with the above gnuplot instance.
 def magic_gpc(self,parameter_s=''):
     """Execute a gnuplot command or open a gnuplot shell.
 
     Usage (omit the % if automagic is on). There are two ways to use it:
 
       1) %gpc 'command' -> passes 'command' directly to the gnuplot instance.
 
       2) %gpc -> will open up a prompt (gnuplot>>>) which takes input like the
       standard gnuplot interactive prompt. If you need to type a multi-line
       command, use \\ at the end of each intermediate line.
 
       Upon exiting of the gnuplot sub-shell, you return to your IPython
       session (the gnuplot sub-shell can be invoked as many times as needed).
       """
 
     if parameter_s.strip():
         self.shell.gnuplot(parameter_s)
     else:
         self.shell.gnuplot.interact()
 
 def magic_gp_set_default(self,parameter_s=''):
     """Set the default gnuplot instance accessed by the %gp magic function.
 
     %gp_set_default name
 
     Call with the name of the new instance at the command line. If you want to
     set this instance in your own code (using an embedded IPython, for
     example), simply set the variable __IPYTHON__.gnuplot to your own gnuplot
     instance object."""
 
     gname = parameter_s.strip()
     G = eval(gname,self.shell.user_ns)
     self.shell.gnuplot = G
     self.shell.user_ns.update({'plot':G.plot,'splot':G.splot,'plot2':G.plot2,
                                'replot':G.replot,'hardcopy':G.hardcopy})
 
 try:
     __IPYTHON__
 except NameError:
     pass
 else:
     # make the global Gnuplot instance known to IPython
     __IPYTHON__.gnuplot = GRun.gp
     __IPYTHON__.gnuplot.shell_first_time = 1
 
     print """*** Type `gphelp` for help on the Gnuplot integration features."""
 
     # Add the new magic functions to the class dict
     from IPython.iplib import InteractiveShell
     InteractiveShell.magic_gpc = magic_gpc
     InteractiveShell.magic_gp_set_default = magic_gp_set_default
 
 #********************** End of file <GnuplotInteractive.py> *******************

IPython/GnuplotRuntime.py

@@ -1,147 +1,146 b''
 # -*- coding: utf-8 -*-
 """Basic Gnuplot functionality for inclusion in other code.
 
 This module creates a running Gnuplot instance called 'gp' and builds other
 convenient globals for quick use in running scripts. It is intended to allow
 you to script plotting tasks in Python with a minimum of effort. A typical
 usage would be:
 
 import IPython.GnuplotRuntime as GP  # or some other short name
 GP.gp.plot(GP.File('your_data.dat'))
 
 
 This module exposes the following objects:
 
 - gp: a running Gnuplot instance. You can access its methods as
 gp.<method>. gp(`a string`) will execute the given string as if it had been
 typed in an interactive gnuplot window.
 
 - gp_new: a function which returns a new Gnuplot instance. This can be used to
 have multiple Gnuplot instances running in your session to compare different
 plots.
 
 - Gnuplot: alias to the Gnuplot2 module, an improved drop-in replacement for
 the original Gnuplot.py. Gnuplot2 needs Gnuplot but redefines several of its
 functions with improved versions (Gnuplot2 comes with IPython).
 
 - Data: alias to Gnuplot.Data, makes a PlotItem from array data.
 
 - File: alias to Gnuplot.File, makes a PlotItem from a file.
 
 - String: alias to Gnuplot.String, makes a PlotItem from a string formatted
 exactly like a file for Gnuplot.File would be.
 
 - Func: alias to Gnuplot.Func, makes a PlotItem from a function string.
 
 - GridData: alias to Gnuplot.GridData, makes a PlotItem from grid data.
 
 - pm3d_config: a string with Gnuplot commands to set up the pm3d mode for
 surface plotting. You can activate it simply by calling gp(pm3d_config).
 
 - eps_fix_bbox: A Unix-only function to fix eps files with bad bounding boxes
 (which Gnuplot generates when the plot size is set to square).
 
 This requires the Gnuplot.py module for interfacing Python with Gnuplot, which
 can be downloaded from:
 
 http://gnuplot-py.sourceforge.net/
 
 Inspired by a suggestion/request from Arnd Baecker.
-
-$Id: GnuplotRuntime.py 389 2004-10-09 07:59:30Z fperez $"""
+"""
 
 __all__ = ['Gnuplot','gp','gp_new','Data','File','Func','GridData',
            'pm3d_config','eps_fix_bbox']
 
 import os,tempfile,sys
 from IPython.genutils import getoutput
 
 #---------------------------------------------------------------------------
 # Notes on mouse support for Gnuplot.py
 
 # If you do not have a mouse-enabled gnuplot, set gnuplot_mouse to 0. If you
 # use gnuplot, you should really grab a recent, mouse enabled copy. It is an
 # extremely useful feature.  Mouse support is official as of gnuplot 4.0,
 # released in April 2004.
 
 # For the mouse features to work correctly, you MUST set your Gnuplot.py
 # module to use temporary files instead of 'inline data' for data
 # communication. Note that this is the default, so unless you've manually
 # fiddled with it you should be ok. If you need to make changes, in the
 # Gnuplot module directory, loook for the gp_unix.py file and make sure the
 # prefer_inline_data variable is set to 0. If you set it to 1 Gnuplot.py will
 # try to pass the data to gnuplot via standard input, which completely
 # confuses the mouse control system (even though it may be a bit faster than
 # using temp files).
 
 # As of Gnuplot.py v1.7, a new option was added to use FIFOs (pipes).  This
 # mechanism, while fast, also breaks the mouse system.  You must therefore set
 # the variable prefer_fifo_data to 0 in gp_unix.py.
 
 tmpname = tempfile.mktemp()
 open(tmpname,'w').write('set mouse')
 gnu_out = getoutput('gnuplot '+ tmpname)
 os.unlink(tmpname)
 if gnu_out:  # Gnuplot won't print anything if it has mouse support
     print "*** Your version of Gnuplot appears not to have mouse support."
     gnuplot_mouse = 0
 else:
     gnuplot_mouse = 1
 del tmpname,gnu_out
 
 # Default state for persistence of new gnuplot instances
 if os.name in ['nt','dos'] or sys.platform == 'cygwin':
     gnuplot_persist = 0
 else:
     gnuplot_persist = 1
 
 import IPython.Gnuplot2 as Gnuplot
 
 class NotGiven: pass
 
 def gp_new(mouse=NotGiven,persist=NotGiven):
     """Return a new Gnuplot instance.
 
     The instance returned uses the improved methods defined in Gnuplot2.
 
     Options (boolean):
 
     - mouse: if unspecified, the module global gnuplot_mouse is used.
 
     - persist: if unspecified, the module global gnuplot_persist is used."""
     
     if mouse is NotGiven:
         mouse = gnuplot_mouse
     if persist is NotGiven:
         persist = gnuplot_persist
     g = Gnuplot.Gnuplot(persist=persist)
     if mouse:
         g('set mouse')
     return g
 
 # Global-level names.
 
 # A global Gnuplot instance for interactive use:
 gp = gp_new()
 
 # Accessors for the main plot object constructors:
 Data = Gnuplot.Data
 File = Gnuplot.File
 Func = Gnuplot.Func
 String = Gnuplot.String
 GridData = Gnuplot.GridData
 
 # A Unix-only function to fix eps files with bad bounding boxes (which Gnuplot
 # generates when the plot size is set to square):
 eps_fix_bbox = Gnuplot.eps_fix_bbox
 
 # String for configuring pm3d. Simply call g(pm3d_config) to execute it.  pm3d
 # is a very nice mode for plotting colormaps on surfaces. Modify the defaults
 # below to suit your taste.
 pm3d_config = """
 set pm3d solid
 set hidden3d
 unset surface
 set isosamples 50
 """
 #******************** End of file <GnuplotRuntime.py> ******************

IPython/Itpl.py

@@ -1,292 +1,290 b''
 # -*- coding: utf-8 -*-
 """String interpolation for Python (by Ka-Ping Yee, 14 Feb 2000).
 
 This module lets you quickly and conveniently interpolate values into
 strings (in the flavour of Perl or Tcl, but with less extraneous
 punctuation).  You get a bit more power than in the other languages,
 because this module allows subscripting, slicing, function calls,
 attribute lookup, or arbitrary expressions.  Variables and expressions
 are evaluated in the namespace of the caller.
 
 The itpl() function returns the result of interpolating a string, and
 printpl() prints out an interpolated string.  Here are some examples:
 
     from Itpl import printpl
     printpl("Here is a $string.")
     printpl("Here is a $module.member.")
     printpl("Here is an $object.member.")
     printpl("Here is a $functioncall(with, arguments).")
     printpl("Here is an ${arbitrary + expression}.")
     printpl("Here is an $array[3] member.")
     printpl("Here is a $dictionary['member'].")
 
 The filter() function filters a file object so that output through it
 is interpolated.  This lets you produce the illusion that Python knows
 how to do interpolation:
 
     import Itpl
     sys.stdout = Itpl.filter()
     f = "fancy"
-    print "Isn't this $f?"
+    print "Is this not $f?"
     print "Standard output has been replaced with a $sys.stdout object."
     sys.stdout = Itpl.unfilter()
     print "Okay, back $to $normal."
 
 Under the hood, the Itpl class represents a string that knows how to
 interpolate values.  An instance of the class parses the string once
 upon initialization; the evaluation and substitution can then be done
 each time the instance is evaluated with str(instance).  For example:
 
     from Itpl import Itpl
     s = Itpl("Here is $foo.")
     foo = 5
     print str(s)
     foo = "bar"
     print str(s)
-
-$Id: Itpl.py 2918 2007-12-31 14:34:47Z vivainio $
-"""                   # ' -> close an open quote for stupid emacs
+"""
 
 #*****************************************************************************
 #
 # Copyright (c) 2001 Ka-Ping Yee <[e-mail]>
 #
 #
 # Published under the terms of the MIT license, hereby reproduced:
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
 # deal in the Software without restriction, including without limitation the
 # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 # sell copies of the Software, and to permit persons to whom the Software is
 # furnished to do so, subject to the following conditions:
 #
 # The above copyright notice and this permission notice shall be included in
 # all copies or substantial portions of the Software.
 #
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 #
 #*****************************************************************************
 
 __author__  = 'Ka-Ping Yee <[e-mail]>'
 __license__ = 'MIT'
 
 import string
 import sys
 from tokenize import tokenprog
 from types import StringType
 
 class ItplError(ValueError):
     def __init__(self, text, pos):
         self.text = text
         self.pos = pos
     def __str__(self):
         return "unfinished expression in %s at char %d" % (
             repr(self.text), self.pos)
 
 def matchorfail(text, pos):
     match = tokenprog.match(text, pos)
     if match is None:
         raise ItplError(text, pos)
 
     return match, match.end()
 
 try:
     itpl_encoding = sys.stdin.encoding or 'ascii'
 except AttributeError:
     itpl_encoding = 'ascii'
 
     
 
 class Itpl:
     """Class representing a string with interpolation abilities.
     
     Upon creation, an instance works out what parts of the format
     string are literal and what parts need to be evaluated.  The
     evaluation and substitution happens in the namespace of the
     caller when str(instance) is called."""
 
     def __init__(self, format,codec=itpl_encoding,encoding_errors='backslashreplace'):
         """The single mandatory argument to this constructor is a format
         string.
 
         The format string is parsed according to the following rules:
 
         1.  A dollar sign and a name, possibly followed by any of: 
               - an open-paren, and anything up to the matching paren 
               - an open-bracket, and anything up to the matching bracket 
               - a period and a name 
             any number of times, is evaluated as a Python expression.
 
         2.  A dollar sign immediately followed by an open-brace, and
             anything up to the matching close-brace, is evaluated as
             a Python expression.
 
         3.  Outside of the expressions described in the above two rules,
             two dollar signs in a row give you one literal dollar sign.
 
         Optional arguments:
 
         - codec('utf_8'): a string containing the name of a valid Python
         codec.
 
         - encoding_errors('backslashreplace'): a string with a valid error handling
         policy.  See the codecs module documentation for details.
 
         These are used to encode the format string if a call to str() fails on
         the expanded result."""
 
         if not isinstance(format,basestring):
             raise TypeError, "needs string initializer"
         self.format = format
         self.codec = codec
         self.encoding_errors = encoding_errors
         
         namechars = "abcdefghijklmnopqrstuvwxyz" \
             "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_";
         chunks = []
         pos = 0
 
         while 1:
             dollar = string.find(format, "$", pos)
             if dollar < 0: break
             nextchar = format[dollar+1]
 
             if nextchar == "{":
                 chunks.append((0, format[pos:dollar]))
                 pos, level = dollar+2, 1
                 while level:
                     match, pos = matchorfail(format, pos)
                     tstart, tend = match.regs[3]
                     token = format[tstart:tend]
                     if token == "{": level = level+1
                     elif token == "}": level = level-1
                 chunks.append((1, format[dollar+2:pos-1]))
 
             elif nextchar in namechars:
                 chunks.append((0, format[pos:dollar]))
                 match, pos = matchorfail(format, dollar+1)
                 while pos < len(format):
                     if format[pos] == "." and \
                         pos+1 < len(format) and format[pos+1] in namechars:
                         match, pos = matchorfail(format, pos+1)
                     elif format[pos] in "([":
                         pos, level = pos+1, 1
                         while level:
                             match, pos = matchorfail(format, pos)
                             tstart, tend = match.regs[3]
                             token = format[tstart:tend]
                             if token[0] in "([": level = level+1
                             elif token[0] in ")]": level = level-1
                     else: break
                 chunks.append((1, format[dollar+1:pos]))
 
             else:
                 chunks.append((0, format[pos:dollar+1]))
                 pos = dollar + 1 + (nextchar == "$")
 
         if pos < len(format): chunks.append((0, format[pos:]))
         self.chunks = chunks
 
     def __repr__(self):
         return "<Itpl %s >" % repr(self.format)
 
     def _str(self,glob,loc):
         """Evaluate to a string in the given globals/locals.
 
         The final output is built by calling str(), but if this fails, the
         result is encoded with the instance's codec and error handling policy,
         via a call to out.encode(self.codec,self.encoding_errors)"""
         result = []
         app = result.append
         for live, chunk in self.chunks:
             if live:
                 val = eval(chunk,glob,loc)
                 try:
                     app(str(val))
                 except UnicodeEncodeError:
                     app(unicode(val))
                 
             else: app(chunk)
         out = ''.join(result)
         try:
             return str(out)
         except UnicodeError:
             return out.encode(self.codec,self.encoding_errors)
 
     def __str__(self):
         """Evaluate and substitute the appropriate parts of the string."""
 
         # We need to skip enough frames to get to the actual caller outside of
         # Itpl.
         frame = sys._getframe(1)
         while frame.f_globals["__name__"] == __name__: frame = frame.f_back
         loc, glob = frame.f_locals, frame.f_globals
 
         return self._str(glob,loc)
     
 class ItplNS(Itpl):
     """Class representing a string with interpolation abilities.
 
     This inherits from Itpl, but at creation time a namespace is provided
     where the evaluation will occur.  The interpolation becomes a bit more
     efficient, as no traceback needs to be extracte.  It also allows the
     caller to supply a different namespace for the interpolation to occur than
     its own."""
     
     def __init__(self, format,globals,locals=None,
                  codec='utf_8',encoding_errors='backslashreplace'):
         """ItplNS(format,globals[,locals]) -> interpolating string instance.
 
         This constructor, besides a format string, takes a globals dictionary
         and optionally a locals (which defaults to globals if not provided).
 
         For further details, see the Itpl constructor."""
 
         if locals is None:
             locals = globals
         self.globals = globals
         self.locals = locals
         Itpl.__init__(self,format,codec,encoding_errors)
         
     def __str__(self):
         """Evaluate and substitute the appropriate parts of the string."""
         return self._str(self.globals,self.locals)
 
     def __repr__(self):
         return "<ItplNS %s >" % repr(self.format)
 
 # utilities for fast printing
 def itpl(text): return str(Itpl(text))
 def printpl(text): print itpl(text)
 # versions with namespace
 def itplns(text,globals,locals=None): return str(ItplNS(text,globals,locals))
 def printplns(text,globals,locals=None): print itplns(text,globals,locals)
 
 class ItplFile:
     """A file object that filters each write() through an interpolator."""
     def __init__(self, file): self.file = file
     def __repr__(self): return "<interpolated " + repr(self.file) + ">"
     def __getattr__(self, attr): return getattr(self.file, attr)
     def write(self, text): self.file.write(str(Itpl(text)))
 
 def filter(file=sys.stdout):
     """Return an ItplFile that filters writes to the given file object.
     
     'file = filter(file)' replaces 'file' with a filtered object that
     has a write() method.  When called with no argument, this creates
     a filter to sys.stdout."""
     return ItplFile(file)
 
 def unfilter(ifile=None):
     """Return the original file that corresponds to the given ItplFile.
     
     'file = unfilter(file)' undoes the effect of 'file = filter(file)'.
     'sys.stdout = unfilter()' undoes the effect of 'sys.stdout = filter()'."""
     return ifile and ifile.file or sys.stdout.file

IPython/Logger.py

@@ -1,270 +1,263 b''
 # -*- coding: utf-8 -*-
 """
 Logger class for IPython's logging facilities.
-
-$Id: Logger.py 2875 2007-11-26 08:37:39Z fperez $
 """
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
 #       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 log raw or processed input
         self.log_raw_input = False
 
         # 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,log_raw_input=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 parameters can override constructor defaults
         if logfname is not None: self.logfname = logfname
         if loghead is not None: self.loghead = loghead
         if logmode is not None: self.logmode = logmode
 
         # Parameters not part of the constructor
         self.timestamp = timestamp
         self.log_output = log_output
         self.log_raw_input = log_raw_input
         
         # 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 'Raw input log  :',self.log_raw_input
             print 'Timestamping   :',self.timestamp
             print 'State          :',state
 
     def log(self,line_ori,line_mod,continuation=None):
         """Write the line to a log and create input cache variables _i*.
 
         Inputs:
 
         - line_ori: unmodified input line from the user.  This is not
         necessarily valid Python.
 
         - line_mod: possibly modified input, such as the transformations made
         by input prefilters or input handlers of various kinds.  This should
         always be valid Python.
 
         - continuation: if True, indicates this is part of multi-line input."""
 
         # update the auto _i tables
         #print '***logging line',line_mod # 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()  # dbg
             return
         
         out_cache = self.shell.outputcache
 
         # add blank lines if the input cache fell out of sync.
         if out_cache.do_full_cache and \
             out_cache.prompt_count +1 > len(input_hist):
             input_hist.extend(['\n'] * (out_cache.prompt_count - len(input_hist)))
             
         if not continuation and line_mod:
             self._iii = self._ii
             self._ii = self._i
             self._i = self._i00
             # put back the final \n of every input line
             self._i00 = line_mod+'\n'
             #print 'Logging input:<%s>' % line_mod  # 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
 
             # 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_mod)
                 input_hist[in_num] = self._i00
             to_main[new_i] = self._i00
         self.shell.user_ns.update(to_main)
 
         # Write the log line, but decide which one according to the
         # log_raw_input flag, set when the log is started.
         if self.log_raw_input:
             self.log_write(line_ori)
         else:
             self.log_write(line_mod)
 
     def log_write(self,data,kind='input'):
         """Write data to the log file, if active"""
 
         #print 'data: %r' % data # dbg
         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 logstop(self):
         """Fully stop logging and close log file.
 
         In order to start logging again, a new logstart() call needs to be
         made, possibly (though not necessarily) with a new filename, mode and
         other options."""
         
         self.logfile.close()
         self.logfile = None
         self.log_active = False
 
     # For backwards compatibility, in case anyone was using this.
     close_log = logstop

IPython/Magic.py

@@ -1,3416 +1,3415 b''
 # -*- coding: utf-8 -*-
 """Magic functions for InteractiveShell.
-
-$Id: Magic.py 2996 2008-01-30 06:31:39Z fperez $"""
+"""
 
 #*****************************************************************************
 #       Copyright (C) 2001 Janko Hauser <[e-mail]> and
 #       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
 import textwrap
 from cStringIO import StringIO
 from getopt import getopt,GetoptError
 from pprint import pprint, pformat
 from sets import Set
 
 # cProfile was added in Python2.5
 try:
     import cProfile as profile
     import pstats
 except ImportError:
     # profile isn't bundled by default in Debian for license reasons
     try:
         import profile,pstats
     except ImportError:
         profile = pstats = None
 
 # Homebrewed
 import IPython
 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.ipstruct import Struct
 from IPython.macro import Macro
 from IPython.genutils import *
 from IPython import platutils
 import IPython.generics
 import IPython.ipapi
 from IPython.ipapi import UsageError
 from IPython.testing import decorators as testdec
 
 #***************************************************************************
 # 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
 
 def compress_dhist(dh):
     head, tail = dh[:-10], dh[-10:]
 
     newhead = []
     done = Set()
     for h in head:
         if h in done:
             continue
         newhead.append(h)
         done.add(h)
 
     return newhead + tail        
         
 
 #***************************************************************************
 # 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. It has been removed from the standard
 python packages because of its non-free license. To use profiling, install the
 python-profiler package 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 Set(magics):
             out.append(fn.replace('magic_','',1))
         out.sort()
         return out
     
     def extract_input_slices(self,slices,raw=False):
         """Return as a string a set of input history slices.
 
         Inputs:
 
           - 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.
 
         Optional inputs:
 
           - raw(False): by default, the processed input is used.  If this is
           true, the raw input history is used instead.
 
         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)."""
 
         if raw:
             hist = self.shell.input_hist_raw
         else:
             hist = self.shell.input_hist
 
         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(hist[ini:fin])
         return cmds
         
     def _ofind(self, oname, namespaces=None):
         """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()
 
         alias_ns = None
         if namespaces is None:
             # Namespaces to search in:
             # Put them in a list. The order is important so that we
             # find things in the same order that Python finds them.
             namespaces = [ ('Interactive', self.shell.user_ns),
                            ('IPython internal', self.shell.internal_ns),
                            ('Python builtin', __builtin__.__dict__),
                            ('Alias', self.shell.alias_table),
                            ]
             alias_ns = self.shell.alias_table
 
         # initialize results to 'null'
         found = 0; obj = None;  ospace = None;  ds = None;
         ismagic = 0; isalias = 0; parent = None
 
         # 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:
                 #print 'oname_rest:', oname_rest  # dbg
                 for part in oname_rest:
                     try:
                         parent = obj
                         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, 'parent':parent}
     
     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_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \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.
 
           -posix (True): whether to split the input line in POSIX mode or not,
           as per the conventions outlined in the shlex module from the
           standard library."""
  
         # 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)
         posix = kw.get('posix',True)
 
         # 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 = arg_split(arg_str,posix)
             # Do regular option processing
             try:
                 opts,args = getopt(argv,opt_str,*long_opts)
             except GetoptError,e:
                 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str, 
                                         " ".join(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.
         
         Supported formats: -latex, -brief, -rest        
         """
 
         mode = ''
         try:
             if parameter_s.split()[0] == '-latex':
                 mode = 'latex'
             if parameter_s.split()[0] == '-brief':
                 mode = 'brief'
             if parameter_s.split()[0] == '-rest':
                 mode = 'rest'
                 rest_docs = []
         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
             if mode == 'brief':
                 # only first line
                 if fn.__doc__:                    
                     fndoc = fn.__doc__.split('\n',1)[0]
                 else:
                     fndoc = 'No documentation'
             else:
                 fndoc = fn.__doc__.rstrip()
                 
             if mode == 'rest':
                 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
                                                     fname,fndoc))
                 
             else:
                 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
                                                     fname,fndoc))
                 
         magic_docs = ''.join(magic_docs)
 
         if mode == 'rest':
             return "".join(rest_docs)
         
         if mode == 'latex':
             print self.format_latex(magic_docs)
             return
         else:
             magic_docs = self.format_screen(magic_docs)
         if mode == 'brief':
             return 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_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_automagic(self, parameter_s = ''):
         """Make magic functions callable without having to type the initial %.
 
         Without argumentsl toggles on/off (when off, you must call it as
         %automagic, of course).  With arguments it sets the value, and you can
         use any of (case insensitive):
 
          - on,1,True: to activate
 
          - off,0,False: to deactivate.
 
         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
         arg = parameter_s.lower()
         if parameter_s in ('on','1','true'):
             rc.automagic = True
         elif parameter_s in ('off','0','false'):
             rc.automagic = False
         else:
             rc.automagic = not rc.automagic
         print '\n' + Magic.auto_status[rc.automagic]
 
     @testdec.skip_doctest
     def magic_autocall(self, parameter_s = ''):
         """Make functions callable without having to type parentheses.
 
         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).
 
         In more detail, these values mean:
 
         0 -> fully disabled
 
         1 -> active, but do not apply if there are no arguments on the line.
 
         In this mode, you get:
 
         In [1]: callable
         Out[1]: <built-in function callable>
 
         In [2]: callable 'hello'
         ------> callable('hello')
         Out[2]: False
 
         2 -> Active always.  Even if no arguments are present, the callable
         object is called:
 
         In [2]: float
         ------> float()
         Out[2]: 0.0
 
         Note that even with autocall off, you can still use '/' at the start of
         a line to treat the first argument on the command line as a function
         and add parentheses to it:
 
         In [8]: /str 43
         ------> str(43)
         Out[8]: '43'
 
         # all-random (note for auto-testing)
         """
 
         rc = self.shell.rc
 
         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_system_verbose(self, parameter_s = ''):
         """Set verbose printing of system calls.
 
         If called without an argument, act as a toggle"""
 
         if parameter_s:
             val = bool(eval(parameter_s))
         else:
             val = None
             
         self.shell.rc_set_toggle('system_verbose',val)
         print "System verbose printing is:",\
               ['OFF','ON'][self.shell.rc.system_verbose]
 
 
     def magic_page(self, parameter_s=''):
         """Pretty print the object and display it through a pager.
         
         %page [options] OBJECT
 
         If no object is given, use _ (last output).
         
         Options:
 
           -r: page str(object), don't pretty-print it."""
 
         # After a function contributed by Olivier Aubert, slightly modified.
 
         # Process options/args
         opts,args = self.parse_options(parameter_s,'r')
         raw = 'r' in opts
 
         oname = args and args or '_'
         info = self._ofind(oname)
         if info['found']:
             txt = (raw and str or pformat)( info['obj'] )
             page(txt)
         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 magic_pinfo(self, parameter_s='', namespaces=None):
         """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,
                           namespaces=namespaces)
 
     def magic_pdef(self, parameter_s='', namespaces=None):
         """Print the definition header for any callable object.
 
         If the object is a class, print the constructor information."""
         self._inspect('pdef',parameter_s, namespaces)
 
     def magic_pdoc(self, parameter_s='', namespaces=None):
         """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, namespaces)
 
     def magic_psource(self, parameter_s='', namespaces=None):
         """Print (or run through pager) the source code for an object."""
         self._inspect('psource',parameter_s, namespaces)
 
     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 _inspect(self,meth,oname,namespaces=None,**kw):
         """Generic interface to the inspector system.
 
         This function is meant to be called by pdef, pdoc & friends."""
 
         #oname = oname.strip()
         #print '1- oname: <%r>' % oname  # dbg
         try:
             oname = oname.strip().encode('ascii')
             #print '2- oname: <%r>' % oname  # dbg
         except UnicodeEncodeError:
             print 'Python identifiers can only contain ascii characters.'
             return 'not found'
             
         info = Struct(self._ofind(oname, namespaces))
         
         if info.found:
             try:
                 IPython.generics.inspect_object(info.obj)
                 return
             except IPython.ipapi.TryNext:
                 pass
             # Get the docstring of the class property if it exists.
             path = oname.split('.')
             root = '.'.join(path[:-1])
             if info.parent is not None:
                 try:
                     target = getattr(info.parent, '__class__') 
                     # The object belongs to a class instance. 
                     try: 
                         target = getattr(target, path[-1])
                         # The class defines the object. 
                         if isinstance(target, property):
                             oname = root + '.__class__.' + path[-1]
                             info = Struct(self._ofind(oname))
                     except AttributeError: pass
                 except AttributeError: pass
                         
             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_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"""
         try:
             parameter_s = parameter_s.encode('ascii')
         except UnicodeEncodeError:
             print 'Python identifiers can only contain ascii characters.'
             return
 
         # 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:
             if parameter_s:
                 print 'No variables match your requested type.'
             else:
                 print 'Interactive namespace is empty.'
             return
 
         # if we have variables, move on...
         count = 0
         for i in varlist:
             print i+'\t',
             count += 1
             if count > 8:
                 count = 0
                 print
         print
 
     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 numpy and 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:
             if parameter_s:
                 print 'No variables match your requested type.'
             else:
                 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 numpy/Numeric arrays, display summary info
         try:
             import numpy
         except ImportError:
             ndarray_type = None
         else:
             ndarray_type = numpy.ndarray.__name__
         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
         def get_vars(i):
             return self.shell.user_ns[i]
         
         # some types are well known and can be shorter
         abbrevs = {'IPython.macro.Macro' : 'Macro'}
         def type_name(v):
             tn = type(v).__name__
             return abbrevs.get(tn,tn)
             
         varlist = map(get_vars,varnames)
 
         typelist = []
         for vv in varlist:
             tt = type_name(vv)
 
             if tt=='instance':
                 typelist.append( abbrevs.get(str(vv.__class__),
                                              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 in [array_type,ndarray_type]:
                 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
                 if vtype==ndarray_type:
                     # numpy
                     vsize  = var.size
                     vbytes = vsize*var.itemsize
                     vdtype = var.dtype
                 else:
                     # Numeric
                     vsize  = Numeric.size(var)
                     vbytes = vsize*var.itemsize()
                     vdtype = var.typecode()
                     
                 if vbytes < 100000:
                     print aformat % (vshape,vsize,vdtype,vbytes)
                 else:
                     print aformat % (vshape,vsize,vdtype,vbytes),
                     if vbytes < Mb:
                         print '(%s kb)' % (vbytes/kb,)
                     else:
                         print '(%s Mb)' % (vbytes/Mb,)
             else:
                 try:
                     vstr = str(var)
                 except UnicodeEncodeError:
                     vstr = unicode(var).encode(sys.getdefaultencoding(),
                                                'backslashreplace')
                 vstr = vstr.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 = self.shell.ask_yes_no(
           "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
         if not ans:
             print 'Nothing done.'
             return
         user_ns = self.shell.user_ns
         for i in self.magic_who_ls():
             del(user_ns[i])
             
         # Also flush the private list of module references kept for script
         # execution protection
         self.shell._user_main_modules[:] = []
 
     def magic_logstart(self,parameter_s=''):
         """Start logging anywhere in a session.
 
         %logstart [-o|-r|-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
 
           -r: log 'raw' input.  Normally, IPython's logs contain the processed
           input, so that user lines are logged in their final form, converted
           into valid Python.  For example, %Exit is logged as
           '_ip.magic("Exit").  If the -r flag is given, all input is logged
           exactly as typed, with no transformations applied.
 
           -t: put timestamps before each input line logged (these are put in
           comments)."""
         
         opts,par = self.parse_options(parameter_s,'ort')
         log_output = 'o' in opts
         log_raw_input = 'r' 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,log_raw_input)
         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_raw_input:
                 input_hist = self.shell.input_hist_raw
             else:
                 input_hist = self.shell.input_hist
                 
             if log_output:
                 log_write = logger.log_write
                 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(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_logstop(self,parameter_s=''):
         """Fully stop logging and close log file.
 
         In order to start logging again, a new %logstart call needs to be made,
         possibly (though not necessarily) with a new filename, mode and other
         options."""
         self.logger.logstop()
 
     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 automatic 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.
 
         The initial state of this feature is set in your ipythonrc
         configuration file (the variable is called 'pdb').
 
         If you want to just activate the debugger AFTER an exception has fired,
         without having to type '%pdb on' and rerunning your code, you can use
         the %debug magic."""
 
         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.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_debug(self, parameter_s=''):
         """Activate the interactive debugger in post-mortem mode.
 
         If an exception has just occurred, this lets you inspect its stack
         frames interactively.  Note that this will always work only on the last
         traceback that occurred, so you must call this quickly after an
         exception that you wish to inspect has fired, because if another one
         occurs, it clobbers the previous one.
 
         If you want IPython to automatically do this on every exception, see
         the %pdb magic for more details.
         """
         
         self.shell.debugger(force=True)
 
     @testdec.skip_doctest
     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.
 
        -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.
         stdout_trap = StringIO()
 
         if hasattr(stats,'stream'):
             # In newer versions of python, the stats object has a 'stream'
             # attribute to write into.
             stats.stream = stdout_trap
             stats.print_stats(*lims)
         else:
             # For older versions, we manually redirect stdout during printing
             sys_stdout = sys.stdout
             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:
             pfile = file(text_file,'w')
             pfile.write(output)
             pfile.close()
             print '\n*** Profile printout saved to text file',\
                   `text_file`+'.',sys_exit
 
         if opts.has_key('r'):
             return stats
         else:
             return None
 
     @testdec.skip_doctest
     def magic_run(self, parameter_s ='',runner=None,
                   file_finder=get_py_filename):
         """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
         (except for sharing global objects such as previously imported
         modules). 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.
 
         There is one special usage for which the text above doesn't apply:
         if the filename ends with .ipy, the file is run as ipython script,
         just as if the commands were written on IPython prompt.
         """
 
         # 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 = file_finder(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
 
         if filename.lower().endswith('.ipy'):
             self.api.runlines(open(filename).read())
             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'):
             # Run in user's interactive namespace
             prog_ns = self.shell.user_ns
             __name__save = self.shell.user_ns['__name__']
             prog_ns['__name__'] = '__main__'
             main_mod = FakeModule(prog_ns)
         else:
             # Run in a fresh, empty namespace
             if opts.has_key('n'):
                 name = os.path.splitext(os.path.basename(filename))[0]
             else:
                 name = '__main__'
             main_mod = FakeModule()
             prog_ns = main_mod.__dict__
             prog_ns['__name__'] = name
             
             # The shell MUST hold a reference to main_mod so after %run exits,
             # the python deletion mechanism doesn't zero it out (leaving
             # dangling references)
             
             # XXX - the note above was written without further detail, but this
             # code actually causes problems.  By holding references to the
             # namespace where every script is executed, we effectively disable
             # just about all possible variable cleanup.  In particular,
             # generator expressions and other variables that point to open
             # files are kept alive, and as a user session lives on, it may run
             # out of available file descriptors.  Such a bug has already been
             # reported by JD Hunter.  I'm disabling this for now, but we need
             # to clarify exactly (and add tests) what from main_mod needs to be
             # kept alive and what is save to remove...  In fact, see note
             # below, where we append main_mod to sys.modules and then delete it
             # again.  The final cleanup is rendered moot by this reference kept
             # in _user_main_modules(), so we really need to look into this.
             
             self.shell._user_main_modules.append(main_mod)
 
             # /XXX
 
         # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
         # set the __file__ global in the script's namespace
         prog_ns['__file__'] = filename
 
         # pickle fix.  See iplib for an explanation.  But we need to make sure
         # that, if we overwrite __main__, we replace it at the end
         main_mod_name = prog_ns['__name__']
 
         if main_mod_name == '__main__':
             restore_main = sys.modules['__main__']
         else:
             restore_main = False
 
         # This needs to be undone at the end to prevent holding references to
         # every single object ever created.
         sys.modules[main_mod_name] = main_mod
         
         stats = None
         try:
             self.shell.savehist()
 
             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 "%s prompt to start your script." % deb.prompt
                     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'):
                         # timed execution
                         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:
                         # regular execution
                         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:
             # Ensure key global structures are restored
             sys.argv = save_argv
             if restore_main:
                 sys.modules['__main__'] = restore_main
             else:
                 # Remove from sys.modules the reference to main_mod we'd
                 # added.  Otherwise it will trap references to objects
                 # contained therein.
                 del sys.modules[main_mod_name]
             self.shell.reloadhist()
                 
         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)
 
     @testdec.skip_doctest
     def magic_timeit(self, parameter_s =''):
         """Time execution of a Python statement or expression
 
         Usage:\\
           %timeit [-n<N> -r<R> [-t|-c]] statement
 
         Time execution of a Python statement or expression using the timeit
         module.
 
         Options:
         -n<N>: execute the given statement <N> times in a loop. If this value
         is not given, a fitting value is chosen. 
         
         -r<R>: repeat the loop iteration <R> times and take the best result.
         Default: 3
         
         -t: use time.time to measure the time, which is the default on Unix.
         This function measures wall time.
         
         -c: use time.clock to measure the time, which is the default on
         Windows and measures wall time. On Unix, resource.getrusage is used
         instead and returns the CPU user time.
 
         -p<P>: use a precision of <P> digits to display the timing result.
         Default: 3
 
         
         Examples:
 
           In [1]: %timeit pass
           10000000 loops, best of 3: 53.3 ns per loop
 
           In [2]: u = None
 
           In [3]: %timeit u is None
           10000000 loops, best of 3: 184 ns per loop
 
           In [4]: %timeit -r 4 u == None
           1000000 loops, best of 4: 242 ns per loop
 
           In [5]: import time
 
           In [6]: %timeit -n1 time.sleep(2)
           1 loops, best of 3: 2 s per loop
           
 
         The times reported by %timeit will be slightly higher than those
         reported by the timeit.py script when variables are accessed. This is
         due to the fact that %timeit executes the statement in the namespace
         of the shell, compared with timeit.py, which uses a single setup
         statement to import function or create variables. Generally, the bias
         does not matter as long as results from timeit.py are not mixed with
         those from %timeit."""
 
         import timeit
         import math
 
         units = [u"s", u"ms", u"\xb5s", u"ns"]
         scaling = [1, 1e3, 1e6, 1e9]
 
         opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
                                         posix=False)
         if stmt == "":
             return
         timefunc = timeit.default_timer
         number = int(getattr(opts, "n", 0))
         repeat = int(getattr(opts, "r", timeit.default_repeat))
         precision = int(getattr(opts, "p", 3))
         if hasattr(opts, "t"):
             timefunc = time.time
         if hasattr(opts, "c"):
             timefunc = clock
 
         timer = timeit.Timer(timer=timefunc)
         # this code has tight coupling to the inner workings of timeit.Timer,
         # but is there a better way to achieve that the code stmt has access
         # to the shell namespace?
 
         src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
                                  'setup': "pass"}
         # Track compilation time so it can be reported if too long
         # Minimum time above which compilation time will be reported
         tc_min = 0.1
         
         t0 = clock()
         code = compile(src, "<magic-timeit>", "exec")
         tc = clock()-t0
         
         ns = {}
         exec code in self.shell.user_ns, ns
         timer.inner = ns["inner"]
         
         if number == 0:
             # determine number so that 0.2 <= total time < 2.0
             number = 1
             for i in range(1, 10):
                 number *= 10
                 if timer.timeit(number) >= 0.2:
                     break
         
         best = min(timer.repeat(repeat, number)) / number
 
         if best > 0.0:
             order = min(-int(math.floor(math.log10(best)) // 3), 3)
         else:
             order = 3
         print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
                                                           precision,
                                                           best * scaling[order],
                                                           units[order])
         if tc > tc_min:
             print "Compiler time: %.2f s" % tc
 
     @testdec.skip_doctest
     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, so this
         could be rewritten to use it (patches welcome).
         
         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
 
           Note that the time needed by Python to compile the given expression
           will be reported if it is more than 0.1s.  In this example, the
           actual exponentiation is done by Python at compilation time, so while
           the expression can take a noticeable amount of time to compute, that
           time is purely due to the compilation:
 
           In [5]: time 3**9999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
 
           In [6]: time 3**999999;
           CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
           Wall time: 0.00 s
           Compiler : 0.78 s
           """
         
         # fail immediately if the given expression can't be compiled
         
         expr = self.shell.prefilter(parameter_s,False)
 
         # Minimum time above which compilation time will be reported
         tc_min = 0.1
         
         try:
             mode = 'eval'
             t0 = clock()
             code = compile(expr,'<timed eval>',mode)
             tc = clock()-t0
         except SyntaxError:
             mode = 'exec'
             t0 = clock()
             code = compile(expr,'<timed exec>',mode)
             tc = clock()-t0
         # 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 s" % wall_time
         if tc > tc_min:
             print "Compiler : %.2f s" % tc
         return out
 
     @testdec.skip_doctest
     def magic_macro(self,parameter_s = ''):
         """Define a set of input lines as a macro for future re-execution.
 
         Usage:\\
           %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         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 [55]: %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]"""
 
         opts,args = self.parse_options(parameter_s,'r',mode='list')
         if not args:
             macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
             macs.sort()
             return macs
         if len(args) == 1:
             raise UsageError(
                 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
         name,ranges = args[0], args[1:]
         
         #print 'rng',ranges  # dbg
         lines = self.extract_input_slices(ranges,opts.has_key('r'))
         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 [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
 
         Options:
         
           -r: use 'raw' input.  By default, the 'processed' history is used,
           so that magics are loaded in their transformed version to valid
           Python.  If this option is given, the raw input as typed as the
           command line is used instead.
 
         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."""
 
         opts,args = self.parse_options(parameter_s,'r',mode='list')
         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,opts.has_key('r')))
         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)
 
     @testdec.skip_doctest
     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:
 
         -n <number>: open the editor at a specified line number.  By default,
         the IPython editor hook uses the unix syntax 'editor +N filename', but
         you can configure this by providing your own modified hook if your
         favorite editor supports line-number specifications with a different
         syntax.
         
         -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.
 
         -r: use 'raw' input.  This option only applies to input taken from the
         user's history.  By default, the 'processed' history is used, so that
         magics are loaded in their transformed version to valid Python.  If
         this option is given, the raw input as typed as the command line is
         used instead.  When you exit the editor, it will be executed by
         IPython's own processor.
         
         -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 [5]: ed
         Editing... done. Executing edited code...
         hello
         Out[5]: "print 'hello'n"
 
         Now we call it again with the previous output (stored in _):
 
         In [6]: ed _
         Editing... done. Executing edited code...
         hello world
         Out[6]: "print 'hello world'n"
 
         Now we call it with the output #8 (stored in _8, also as Out[8]):
 
         In [7]: ed _8
         Editing... done. Executing edited code...
         hello again
         Out[7]: "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,'prxn:')
         # Set a few locals from the options for convenience:
         opts_p = opts.has_key('p')
         opts_r = opts.has_key('r')
         
         # Default line number value
         lineno = opts.get('n',None)
 
         if opts_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_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,opts_r))
         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)
                     if 'fakemodule' in filename.lower() and inspect.isclass(data):                     
                         # class created by %edit? Try to find source
                         # by looking for method definitions instead, the
                         # __module__ in those classes is FakeModule.
                         attrs = [getattr(data, aname) for aname in dir(data)]
                         for attr in attrs:
                             if not inspect.ismethod(attr):
                                 continue
                             filename = inspect.getabsfile(attr)
                             if filename and 'fakemodule' not in filename.lower():
                                 # change the attribute to be the edit target instead
                                 data = attr 
                                 break
                     
                     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:
                         if lineno is None:
                             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)
             print 'IPython will make a temporary file named:',filename
 
         # do actual editing here
         print 'Editing...',
         sys.stdout.flush()
         self.shell.hooks.editor(filename,lineno)
         
         # XXX TODO: should this be generalized for all string vars?
         # For now, this is special-cased to blocks created by cpaste
         if args.strip() == 'pasted_block':
             self.shell.user_ns['pasted_block'] = file_read(filename)
         
         if opts.has_key('x'):  # -x prevents actual execution
             print
         else:
             print 'done. Executing edited code...'
             if opts_r:
                 self.shell.runlines(file_read(filename))
             else:
                 self.shell.safe_execfile(filename,self.shell.user_ns,
                                          self.shell.user_ns)
         
                                                      
         if use_temp:
             try:
                 return open(filename).read()
             except IOError,msg:
                 if msg.filename == filename:
                     warn('File not found. Did you forget to save?')
                     return
                 else:
                     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:
             raise UsageError(
                 "%colors: you must specify a color scheme. See '%colors?'")
             return
         # local shortcut
         shell = self.shell
 
         import IPython.rlineimpl as readline
 
         if not readline.have_readline and sys.platform == "win32":
             msg = """\
 Proper color support under MS Windows requires the pyreadline library.
 You can find it at:
 http://ipython.scipy.org/moin/PyReadline/Intro
 Gary's readline needs the ctypes module, from:
 http://starship.python.net/crew/theller/ctypes
 (Note that ctypes is already part of Python versions 2.5 and newer).
 
 Defaulting color scheme to 'NoColor'"""
             new_scheme = 'NoColor'
             warn(msg)
         
         # readline option is 0
         if not shell.has_readline:
             new_scheme = 'NoColor'
             
         # 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.rc.pprint = 1 - self.shell.rc.pprint
         print 'Pretty printing has been turned', \
               ['OFF','ON'][self.shell.rc.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.ask_exit()
 
     #......................................................................
     # Functions to implement unix shell-type things
 
     @testdec.skip_doctest
     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:
             stored = self.db.get('stored_aliases', {} )
             atab = self.shell.alias_table
             aliases = atab.keys()
             aliases.sort()
             res = []
             showlast = []
             for alias in aliases:
                 special = False
                 try:
                     tgt = atab[alias][1]
                 except (TypeError, AttributeError):
                     # unsubscriptable? probably a callable
                     tgt = atab[alias]
                     special = True
                 # 'interesting' aliases
                 if (alias in stored or
                     special or 
                     alias.lower() != os.path.splitext(tgt)[0].lower() or
                     ' ' in tgt):
                     showlast.append((alias, tgt))
                 else:
                     res.append((alias, tgt ))                
             
             # show most interesting aliases last
             res.extend(showlast)
             print "Total number of aliases:",len(aliases)
             return res
         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=0)
     # 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]
         stored = self.db.get('stored_aliases', {} )
         if aname in stored:
             print "Removing %stored alias",aname
             del stored[aname]
             self.db['stored_aliases'] = stored
             
 
     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'.
         
         This function also resets the root module cache of module completer,
         used on slow filesystems.
         """
         
         
         ip = self.api
 
         # for the benefit of module completer in ipy_completers.py
         del ip.db['rootmodules']
         
         path = [os.path.abspath(os.path.expanduser(p)) for p in 
             os.environ.get('PATH','').split(os.pathsep)]
         path = filter(os.path.isdir,path)
         
         alias_table = self.shell.alias_table
         syscmdlist = []
         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|py'
             if 'py' not in winext:
                 winext += '|py'
             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) and ff not in self.shell.no_alias:
                             # each entry in the alias table must be (N,name),
                             # where N is the number of positional arguments of the
                             # alias.                            
                             # Dots will be removed from alias names, since ipython
                             # assumes names with dots to be python code
                             alias_table[ff.replace('.','')] = (0,ff)
                             syscmdlist.append(ff)
             else:
                 for pdir in path:
                     os.chdir(pdir)
                     for ff in os.listdir(pdir):
                         base, ext = os.path.splitext(ff)
                         if isexec(ff) and base.lower() not in self.shell.no_alias:
                             if ext.lower() == '.exe':
                                 ff = base
                             alias_table[base.lower().replace('.','')] = (0,ff)
                             syscmdlist.append(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
             
             # no, we don't want them. if %rehashx clobbers them, good,
             # we'll probably get better versions
             # self.shell.init_auto_alias()
             db = ip.db
             db['syscmdlist'] = syscmdlist
         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. You can also
         do 'cd -<tab>' to see directory history conveniently.
 
         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 --foo: change to directory that matches 'foo' in 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.)
               'cd -b <tab>' allows you to tab-complete bookmark names. 
 
         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",{})
 
         oldcwd = os.getcwd()
         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 = {}
         elif parameter_s.startswith('--'):
             ps = None
             fallback = None
             pat = parameter_s[2:]
             dh = self.shell.user_ns['_dh']
             # first search only by basename (last component)
             for ent in reversed(dh):
                 if pat in os.path.basename(ent) and os.path.isdir(ent):
                     ps = ent
                     break
             
                 if fallback is None and pat in ent and os.path.isdir(ent):
                     fallback = ent
                 
             # if we have no last part match, pick the first full path match
             if ps is None:
                 ps = fallback
             
             if ps is None:
                 print "No matching entry in directory history"
                 return
             else:
                 opts = {}
                 
             
         else:
             #turn all non-space-escaping backslashes to slashes, 
             # for c:\windows\directory\names\
             parameter_s = re.sub(r'\\(?! )','/', parameter_s)            
             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:
                 raise UsageError('%cd -: No previous directory to change to.')
         # jump to bookmark if needed
         else:
             if not os.path.isdir(ps) or opts.has_key('b'):
                 bkms = self.db.get('bookmarks', {})
             
                 if bkms.has_key(ps):
                     target = bkms[ps]
                     print '(bookmark:%s) -> %s' % (ps,target)
                     ps = target
                 else:
                     if opts.has_key('b'):
                         raise UsageError("Bookmark '%s' not found.  "
                               "Use '%%bookmark -l' to see your bookmarks." % ps)
             
         # at this point ps should point to the target dir
         if ps:
             try:                
                 os.chdir(os.path.expanduser(ps))
                 if self.shell.rc.term_title:
                     #print 'set term title:',self.shell.rc.term_title  # dbg
                     platutils.set_term_title('IPy ' + abbrev_cwd())
             except OSError:
                 print sys.exc_info()[1]
             else:
                 cwd = os.getcwd()
                 dhist = self.shell.user_ns['_dh']
                 if oldcwd != cwd:
                     dhist.append(cwd)
                     self.db['dhist'] = compress_dhist(dhist)[-100:]
                 
         else:
             os.chdir(self.shell.home_dir)
             if self.shell.rc.term_title:
                 platutils.set_term_title("IPy ~")
             cwd = os.getcwd()
             dhist = self.shell.user_ns['_dh']
             
             if oldcwd != cwd:
                 dhist.append(cwd)
                 self.db['dhist'] = compress_dhist(dhist)[-100:]
         if not 'q' in opts and self.shell.user_ns['_dh']:
             print self.shell.user_ns['_dh'][-1]
 
 
     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']
         """
         
         dir_s = self.shell.dir_stack
         tgt = os.path.expanduser(parameter_s)
         cwd = os.getcwd().replace(self.home_dir,'~')
         if tgt:
             self.magic_cd(parameter_s)
         dir_s.insert(0,cwd)
         return self.magic_dirs()
 
     def magic_popd(self, parameter_s=''):
         """Change to directory popped off the top of the stack.
         """
         if not self.shell.dir_stack:
             raise UsageError("%popd on empty stack")
         top = self.shell.dir_stack.pop(0)
         self.magic_cd(top)
         print "popd ->",top
 
     def magic_dirs(self, parameter_s=''):
         """Return the current directory stack."""
 
         return self.shell.dir_stack
 
     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>.
         
         Note that most of time, you should view directory history by entering
         cd -<TAB>.
         
         """
 
         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)
 
     @testdec.skip_doctest
     def magic_sc(self, parameter_s=''):
         """Shell capture - execute a shell command and capture its output.
 
         DEPRECATED. Suboptimal, retained for backwards compatibility.
         
         You should use the form 'var = !command' instead. Example:
          
          "%sc -l myfiles = ls ~" should now be written as
             
          "myfiles = !ls ~"
          
         myfiles.s, myfiles.l and myfiles.n still apply as documented
         below.
 
         --
         %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.
         
         (A special format without variable name exists for internal use)
 
         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:
 
         # all-random
         
             # Capture into variable a
             In [1]: sc a=ls *py
 
             # a is a string with embedded newlines
             In [2]: a
             Out[2]: 'setup.py\\nwin32_manual_post_install.py'
 
             # which can be seen as a list:
             In [3]: a.l
             Out[3]: ['setup.py', 'win32_manual_post_install.py']
 
             # or as a whitespace-separated string:
             In [4]: a.s
             Out[4]: 'setup.py win32_manual_post_install.py'
 
             # a.s is useful to pass as a single command line:
             In [5]: !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 [6]: 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 [7]: sc -l b=ls *py
 
             In [8]: b
             Out[8]: ['setup.py', 'win32_manual_post_install.py']
 
             In [9]: b.s
             Out[9]: '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 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))
         if var:
             self.shell.user_ns.update({var:out})
         else:
             return 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_r(self, parameter_s=''):
         """Repeat previous input.
 
         Note: Consider using the more powerfull %rep instead!
         
         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 != '_ip.magic("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_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:
             raise UsageError("%bookmark: too many arguments")
 
         bkms = self.db.get('bookmarks',{})
             
         if opts.has_key('d'):
             try:
                 todel = args[0]
             except IndexError:
                 raise UsageError(
                     "%bookmark -d: must provide a bookmark to delete")
             else:
                 try:
                     del bkms[todel]
                 except KeyError:
                     raise UsageError(
                         "%%bookmark -d: 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:
                 raise UsageError("%bookmark: 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.db['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. """
         
         try:
             filename = get_py_filename(parameter_s)
             cont = file_read(filename)
         except IOError:
             try:
                 cont = eval(parameter_s,self.user_ns)
             except NameError:
                 cont = None
         if cont is None:
             print "Error: no such file or variable"
             return
             
         page(self.shell.pycolorize(cont),
              screen_lines=self.shell.rc.screen_length)
 
     def magic_cpaste(self, parameter_s=''):
         """Allows you to paste & execute a pre-formatted code block from clipboard.
         
         You must terminate the block with '--' (two minus-signs) alone on the
         line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
         is the new sentinel for this operation)
         
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
         ignored, to allow pasting directly from e-mails, diff files and
         doctests (the '...' continuation prompt is also stripped).  The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
         
         You can also pass a variable name as an argument, e.g. '%cpaste foo'.
         This assigns the pasted block to variable 'foo' as string, without 
         dedenting or executing it (preceding >>> and + is still stripped)
         
         '%cpaste -r' re-executes the block previously entered by cpaste.
         
         Do not be alarmed by garbled output on Windows (it's a readline bug). 
         Just press enter and type -- (and press enter again) and the block 
         will be what was just pasted.
         
         IPython statements (magics, shell escapes) are not supported (yet).
         """
         opts,args = self.parse_options(parameter_s,'rs:',mode='string')
         par = args.strip()
         if opts.has_key('r'):
             b = self.user_ns.get('pasted_block', None)
             if b is None:
                 raise UsageError('No previous pasted block available')
             print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
             exec b in self.user_ns
             return
         
         sentinel = opts.get('s','--')
 
         # Regular expressions that declare text we strip from the input:
         strip_re =  [r'^\s*In \[\d+\]:', # IPython input prompt
                      r'^\s*(\s?>)+', # Python input prompt
                      r'^\s*\.{3,}', # Continuation prompts
                      r'^\++',
                      ]
 
         strip_from_start = map(re.compile,strip_re)
         
         from IPython import iplib
         lines = []
         print "Pasting code; enter '%s' alone on the line to stop." % sentinel
         while 1:
             l = iplib.raw_input_original(':')
             if l ==sentinel:
                 break
             
             for pat in strip_from_start: 
                 l = pat.sub('',l)
             lines.append(l)
                          
         block = "\n".join(lines) + '\n'
         #print "block:\n",block
         if not par:
             b = textwrap.dedent(block)
             self.user_ns['pasted_block'] = b
             exec b in self.user_ns
         else:
             self.user_ns[par] = SList(block.splitlines())
             print "Block assigned to '%s'" % par
             
     def magic_quickref(self,arg):
         """ Show a quick reference sheet """
         import IPython.usage
         qr = IPython.usage.quick_reference + self.magic_magic('-brief')
         
         page(qr)
         
     def magic_upgrade(self,arg):
         """ Upgrade your IPython installation
         
         This will copy the config files that don't yet exist in your 
         ipython dir from the system config dir. Use this after upgrading 
         IPython if you don't wish to delete your .ipython dir.
 
         Call with -nolegacy to get rid of ipythonrc* files (recommended for
         new users)
 
         """
         ip = self.getapi()
         ipinstallation = path(IPython.__file__).dirname()
         upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
         src_config = ipinstallation / 'UserConfig'
         userdir = path(ip.options.ipythondir)
         cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
         print ">",cmd
         shell(cmd)
         if arg == '-nolegacy':
             legacy = userdir.files('ipythonrc*')
             print "Nuking legacy files:",legacy
             
             [p.remove() for p in legacy]
             suffix = (sys.platform == 'win32' and '.ini' or '')
             (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
 
 
     def magic_doctest_mode(self,parameter_s=''):
         """Toggle doctest mode on and off.
 
         This mode allows you to toggle the prompt behavior between normal
         IPython prompts and ones that are as similar to the default IPython
         interpreter as possible.
 
         It also supports the pasting of code snippets that have leading '>>>'
         and '...' prompts in them.  This means that you can paste doctests from
         files or docstrings (even if they have leading whitespace), and the
         code will execute correctly.  You can then use '%history -tn' to see
         the translated history without line numbers; this will give you the
         input after removal of all the leading prompts and whitespace, which
         can be pasted back into an editor.
 
         With these features, you can switch into this mode easily whenever you
         need to do testing and changes to doctests, without having to leave
         your existing IPython session.
         """
 
         # XXX - Fix this to have cleaner activate/deactivate calls.
         from IPython.Extensions import InterpreterPasteInput as ipaste
         from IPython.ipstruct import Struct
 
         # Shorthands
         shell = self.shell
         oc = shell.outputcache
         rc = shell.rc
         meta = shell.meta
         # dstore is a data store kept in the instance metadata bag to track any
         # changes we make, so we can undo them later.
         dstore = meta.setdefault('doctest_mode',Struct())
         save_dstore = dstore.setdefault
 
         # save a few values we'll need to recover later
         mode = save_dstore('mode',False)
         save_dstore('rc_pprint',rc.pprint)
         save_dstore('xmode',shell.InteractiveTB.mode)
         save_dstore('rc_separate_out',rc.separate_out)
         save_dstore('rc_separate_out2',rc.separate_out2)
         save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
         save_dstore('rc_separate_in',rc.separate_in)
 
         if mode == False:
             # turn on
             ipaste.activate_prefilter()
 
             oc.prompt1.p_template = '>>> '
             oc.prompt2.p_template = '... '
             oc.prompt_out.p_template = ''
 
             # Prompt separators like plain python
             oc.input_sep = oc.prompt1.sep = ''
             oc.output_sep = ''
             oc.output_sep2 = ''
 
             oc.prompt1.pad_left = oc.prompt2.pad_left = \
                                   oc.prompt_out.pad_left = False
 
             rc.pprint = False
 
             shell.magic_xmode('Plain')
 
         else:
             # turn off
             ipaste.deactivate_prefilter()
 
             oc.prompt1.p_template = rc.prompt_in1
             oc.prompt2.p_template = rc.prompt_in2
             oc.prompt_out.p_template = rc.prompt_out
 
             oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
 
             oc.output_sep = dstore.rc_separate_out
             oc.output_sep2 = dstore.rc_separate_out2
 
             oc.prompt1.pad_left = oc.prompt2.pad_left = \
                          oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
 
             rc.pprint = dstore.rc_pprint
 
             shell.magic_xmode(dstore.xmode)
 
         # Store new mode and inform
         dstore.mode = bool(1-int(mode))
         print 'Doctest mode is:',
         print ['OFF','ON'][dstore.mode]
 
 # end Magic

IPython/OInspect.py

@@ -1,613 +1,607 b''
 # -*- coding: utf-8 -*-
 """Tools for inspecting Python objects.
 
 Uses syntax highlighting for presenting the various information elements.
 
 Similar in spirit to the inspect module, but all calls take a name argument to
 reference the name under which an object is being read.
-
-$Id: OInspect.py 2843 2007-10-15 21:22:32Z fperez $
 """
 
 #*****************************************************************************
 #       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>' % Release.authors['Fernando']
-__license__ = Release.license
-
 __all__ = ['Inspector','InspectColors']
 
 # stdlib modules
 import __builtin__
 import StringIO
 import inspect
 import linecache
 import os
 import string
 import sys
 import types
 
 # IPython's own
 from IPython import PyColorize
 from IPython.genutils import page,indent,Term
 from IPython.Itpl import itpl
 from IPython.wildcard import list_namespace
 from IPython.ColorANSI import *
 
 #****************************************************************************
 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module.  We
 # simply monkeypatch inspect with code copied from python 2.4.
 if sys.version_info[:2] == (2,3):
     from inspect import ismodule, getabsfile, modulesbyfile
     def getmodule(object):
         """Return the module an object was defined in, or None if not found."""
         if ismodule(object):
             return object
         if hasattr(object, '__module__'):
             return sys.modules.get(object.__module__)
         try:
             file = getabsfile(object)
         except TypeError:
             return None
         if file in modulesbyfile:
             return sys.modules.get(modulesbyfile[file])
         for module in sys.modules.values():
             if hasattr(module, '__file__'):
                 modulesbyfile[
                     os.path.realpath(
                             getabsfile(module))] = module.__name__
         if file in modulesbyfile:
             return sys.modules.get(modulesbyfile[file])
         main = sys.modules['__main__']
         if not hasattr(object, '__name__'):
             return None
         if hasattr(main, object.__name__):
             mainobject = getattr(main, object.__name__)
             if mainobject is object:
                 return main
         builtin = sys.modules['__builtin__']
         if hasattr(builtin, object.__name__):
             builtinobject = getattr(builtin, object.__name__)
             if builtinobject is object:
                 return builtin
 
     inspect.getmodule = getmodule
 
 #****************************************************************************
 # Builtin color schemes
 
 Colors = TermColors  # just a shorthand
 
 # Build a few color schemes
 NoColor = ColorScheme(
     'NoColor',{
     'header' : Colors.NoColor,
     'normal' : Colors.NoColor  # color off (usu. Colors.Normal)
     }  )
 
 LinuxColors = ColorScheme(
     'Linux',{
     'header' : Colors.LightRed,
     'normal' : Colors.Normal  # color off (usu. Colors.Normal)
     } )
 
 LightBGColors = ColorScheme(
     'LightBG',{
     'header' : Colors.Red,
     'normal' : Colors.Normal  # color off (usu. Colors.Normal)
     }  )
 
 # Build table of color schemes (needed by the parser)
 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
                                  'Linux')
 
 #****************************************************************************
 # Auxiliary functions
 def getdoc(obj):
     """Stable wrapper around inspect.getdoc.
 
     This can't crash because of attribute problems.
 
     It also attempts to call a getdoc() method on the given object.  This
     allows objects which provide their docstrings via non-standard mechanisms
     (like Pyro proxies) to still be inspected by ipython's ? system."""
 
     ds = None  # default return value
     try:
         ds = inspect.getdoc(obj)
     except:
         # Harden against an inspect failure, which can occur with
         # SWIG-wrapped extensions.
         pass
     # Allow objects to offer customized documentation via a getdoc method:
     try:
         ds2 = obj.getdoc()
     except:
         pass
     else:
         # if we get extra info, we add it to the normal docstring.
         if ds is None:
             ds = ds2
         else:
             ds = '%s\n%s' % (ds,ds2)
     return ds
 
 
 def getsource(obj,is_binary=False):
     """Wrapper around inspect.getsource.
 
     This can be modified by other projects to provide customized source
     extraction.
 
     Inputs:
 
     - obj: an object whose source code we will attempt to extract.
 
     Optional inputs:
 
     - is_binary: whether the object is known to come from a binary source.
     This implementation will skip returning any output for binary objects, but
     custom extractors may know how to meaningfully process them."""
     
     if is_binary:
         return None
     else:
         try:
             src = inspect.getsource(obj)
         except TypeError:
             if hasattr(obj,'__class__'):
                 src = inspect.getsource(obj.__class__)
         return src
 
 def getargspec(obj):
     """Get the names and default values of a function's arguments.
 
     A tuple of four things is returned: (args, varargs, varkw, defaults).
     'args' is a list of the argument names (it may contain nested lists).
     'varargs' and 'varkw' are the names of the * and ** arguments or None.
     'defaults' is an n-tuple of the default values of the last n arguments.
 
     Modified version of inspect.getargspec from the Python Standard
     Library."""
 
     if inspect.isfunction(obj):
         func_obj = obj
     elif inspect.ismethod(obj):
         func_obj = obj.im_func
     else:
         raise TypeError, 'arg is not a Python function'
     args, varargs, varkw = inspect.getargs(func_obj.func_code)
     return args, varargs, varkw, func_obj.func_defaults
 
 #****************************************************************************
 # Class definitions
 
 class myStringIO(StringIO.StringIO):
     """Adds a writeln method to normal StringIO."""
     def writeln(self,*arg,**kw):
         """Does a write() and then a write('\n')"""
         self.write(*arg,**kw)
         self.write('\n')
 
 
 class Inspector:
     def __init__(self,color_table,code_color_table,scheme,
                  str_detail_level=0):
         self.color_table = color_table
         self.parser = PyColorize.Parser(code_color_table,out='str')
         self.format = self.parser.format
         self.str_detail_level = str_detail_level
         self.set_active_scheme(scheme)
 
     def __getdef(self,obj,oname=''):
         """Return the definition header for any callable object.
 
         If any exception is generated, None is returned instead and the
         exception is suppressed."""
         
         try:
             return oname + inspect.formatargspec(*getargspec(obj))
         except:
             return None
  
     def __head(self,h):
         """Return a header string with proper colors."""
         return '%s%s%s' % (self.color_table.active_colors.header,h,
                            self.color_table.active_colors.normal)
 
     def set_active_scheme(self,scheme):
         self.color_table.set_active_scheme(scheme)
         self.parser.color_table.set_active_scheme(scheme)
     
     def noinfo(self,msg,oname):
         """Generic message when no information is found."""
         print 'No %s found' % msg,
         if oname:
             print 'for %s' % oname
         else:
             print
             
     def pdef(self,obj,oname=''):
         """Print the definition header for any callable object.
 
         If the object is a class, print the constructor information."""
 
         if not callable(obj):
             print 'Object is not callable.'
             return
 
         header = ''
 
         if inspect.isclass(obj):
             header = self.__head('Class constructor information:\n')
             obj = obj.__init__
         elif type(obj) is types.InstanceType:
             obj = obj.__call__
 
         output = self.__getdef(obj,oname)
         if output is None:
             self.noinfo('definition header',oname)
         else:
             print >>Term.cout, header,self.format(output),
 
     def pdoc(self,obj,oname='',formatter = None):
         """Print the docstring for any object.
 
         Optional:
         -formatter: a function to run the docstring through for specially
         formatted docstrings."""
 
         head = self.__head  # so that itpl can find it even if private
         ds = getdoc(obj)
         if formatter:
             ds = formatter(ds)
         if inspect.isclass(obj):
             init_ds = getdoc(obj.__init__)
             output = itpl('$head("Class Docstring:")\n'
                           '$indent(ds)\n'
                           '$head("Constructor Docstring"):\n'
                           '$indent(init_ds)')
         elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
                  and hasattr(obj,'__call__'):
             call_ds = getdoc(obj.__call__)
             if call_ds:
                 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
                               '$head("Calling Docstring:")\n$indent(call_ds)')
             else:
                 output = ds
         else:
             output = ds
         if output is None:
             self.noinfo('documentation',oname)
             return
         page(output)
     
     def psource(self,obj,oname=''):
         """Print the source code for an object."""
 
         # Flush the source cache because inspect can return out-of-date source
         linecache.checkcache()
         try:
             src = getsource(obj) 
         except:
             self.noinfo('source',oname)
         else:
             page(self.format(src))
 
     def pfile(self,obj,oname=''):
         """Show the whole file where an object was defined."""
 
         try:
             try:
                 lineno = inspect.getsourcelines(obj)[1]
             except TypeError:
                 # For instances, try the class object like getsource() does
                 if hasattr(obj,'__class__'):
                     lineno = inspect.getsourcelines(obj.__class__)[1]
                     # Adjust the inspected object so getabsfile() below works
                     obj = obj.__class__
         except:
             self.noinfo('file',oname)
             return
 
         # We only reach this point if object was successfully queried
         
         # run contents of file through pager starting at line
         # where the object is defined
         ofile = inspect.getabsfile(obj)
 
         if (ofile.endswith('.so') or ofile.endswith('.dll')):
             print 'File %r is binary, not printing.' % ofile
         elif not os.path.isfile(ofile):
             print 'File %r does not exist, not printing.' % ofile
         else:
             # Print only text files, not extension binaries.  Note that
             # getsourcelines returns lineno with 1-offset and page() uses
             # 0-offset, so we must adjust.
             page(self.format(open(ofile).read()),lineno-1)
 
     def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
         """Show detailed information about an object.
 
         Optional arguments:
         
         - oname: name of the variable pointing to the object.
 
         - formatter: special formatter for docstrings (see pdoc)
 
         - info: a structure with some information fields which may have been
         precomputed already.
 
         - detail_level: if set to 1, more information is given.
         """
 
         obj_type = type(obj)
 
         header = self.__head
         if info is None:
             ismagic = 0
             isalias = 0
             ospace = ''
         else:
             ismagic = info.ismagic
             isalias = info.isalias
             ospace = info.namespace
         # Get docstring, special-casing aliases:
         if isalias:
             if not callable(obj):
                 try:
                     ds = "Alias to the system command:\n  %s" % obj[1]
                 except:
                     ds = "Alias: " + str(obj)
             else:
                 ds = "Alias to " + str(obj)
                 if obj.__doc__:
                     ds += "\nDocstring:\n" + obj.__doc__
         else:
             ds = getdoc(obj)
             if ds is None:
                 ds = '<no docstring>'
         if formatter is not None:
             ds = formatter(ds)
 
         # store output in a list which gets joined with \n at the end.
         out = myStringIO()
         
         string_max = 200 # max size of strings to show (snipped if longer)
         shalf = int((string_max -5)/2)
 
         if ismagic:
             obj_type_name = 'Magic function'
         elif isalias:
             obj_type_name = 'System alias'
         else:
             obj_type_name = obj_type.__name__
         out.writeln(header('Type:\t\t')+obj_type_name)
 
         try:
             bclass = obj.__class__
             out.writeln(header('Base Class:\t')+str(bclass))
         except: pass
 
         # String form, but snip if too long in ? form (full in ??)
         if detail_level >= self.str_detail_level:
             try:
                 ostr = str(obj)
                 str_head = 'String Form:'
                 if not detail_level and len(ostr)>string_max:
                     ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
                     ostr = ("\n" + " " * len(str_head.expandtabs())).\
                            join(map(string.strip,ostr.split("\n")))
                 if ostr.find('\n') > -1:
                     # Print multi-line strings starting at the next line.
                     str_sep = '\n'
                 else:
                     str_sep = '\t'
                 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
             except:
                 pass
 
         if ospace:
             out.writeln(header('Namespace:\t')+ospace)
 
         # Length (for strings and lists)
         try:
             length = str(len(obj))
             out.writeln(header('Length:\t\t')+length)
         except: pass
 
         # Filename where object was defined
         binary_file = False
         try:
             try:
                 fname = inspect.getabsfile(obj)
             except TypeError:
                 # For an instance, the file that matters is where its class was
                 # declared.
                 if hasattr(obj,'__class__'):
                     fname = inspect.getabsfile(obj.__class__)
             if fname.endswith('<string>'):
                 fname = 'Dynamically generated function. No source code available.'
             if (fname.endswith('.so') or fname.endswith('.dll')):
                 binary_file = True
             out.writeln(header('File:\t\t')+fname)
         except:
             # if anything goes wrong, we don't want to show source, so it's as
             # if the file was binary
             binary_file = True
 
         # reconstruct the function definition and print it:
         defln = self.__getdef(obj,oname)
         if defln:
             out.write(header('Definition:\t')+self.format(defln))
  
         # Docstrings only in detail 0 mode, since source contains them (we
         # avoid repetitions).  If source fails, we add them back, see below.
         if ds and detail_level == 0:
                 out.writeln(header('Docstring:\n') + indent(ds))
                 
         # Original source code for any callable
         if detail_level:
             # Flush the source cache because inspect can return out-of-date
             # source
             linecache.checkcache()
             source_success = False
             try:
                 try:
                     src = getsource(obj,binary_file)
                 except TypeError:
                     if hasattr(obj,'__class__'):
                         src = getsource(obj.__class__,binary_file)
                 if src is not None:
                     source = self.format(src)
                     out.write(header('Source:\n')+source.rstrip())
                     source_success = True
             except Exception, msg:
                 pass
             
             if ds and not source_success:
                 out.writeln(header('Docstring [source file open failed]:\n')
                             + indent(ds))
 
         # Constructor docstring for classes
         if inspect.isclass(obj):
             # reconstruct the function definition and print it:
             try:
                 obj_init =  obj.__init__
             except AttributeError:
                 init_def = init_ds = None
             else:
                 init_def = self.__getdef(obj_init,oname)
                 init_ds  = getdoc(obj_init)
                 # Skip Python's auto-generated docstrings
                 if init_ds and \
                        init_ds.startswith('x.__init__(...) initializes'):
                     init_ds = None
 
             if init_def or init_ds:
                 out.writeln(header('\nConstructor information:'))
                 if init_def:
                     out.write(header('Definition:\t')+ self.format(init_def))
                 if init_ds:
                     out.writeln(header('Docstring:\n') + indent(init_ds))
         # and class docstring for instances:
         elif obj_type is types.InstanceType or \
                  isinstance(obj,object):
 
             # First, check whether the instance docstring is identical to the
             # class one, and print it separately if they don't coincide.  In
             # most cases they will, but it's nice to print all the info for
             # objects which use instance-customized docstrings.
             if ds:
                 try:
                     cls = getattr(obj,'__class__')
                 except:
                     class_ds = None
                 else:
                     class_ds = getdoc(cls)
                 # Skip Python's auto-generated docstrings
                 if class_ds and \
                        (class_ds.startswith('function(code, globals[,') or \
                    class_ds.startswith('instancemethod(function, instance,') or \
                    class_ds.startswith('module(name[,') ):
                     class_ds = None
                 if class_ds and ds != class_ds:
                     out.writeln(header('Class Docstring:\n') +
                                 indent(class_ds))
 
             # Next, try to show constructor docstrings
             try:
                 init_ds = getdoc(obj.__init__)
                 # Skip Python's auto-generated docstrings
                 if init_ds and \
                        init_ds.startswith('x.__init__(...) initializes'):
                     init_ds = None
             except AttributeError:
                 init_ds = None
             if init_ds:
                 out.writeln(header('Constructor Docstring:\n') +
                             indent(init_ds))
 
             # Call form docstring for callable instances
             if hasattr(obj,'__call__'):
                 #out.writeln(header('Callable:\t')+'Yes')
                 call_def = self.__getdef(obj.__call__,oname)
                 #if call_def is None:
                 #    out.writeln(header('Call def:\t')+
                 #              'Calling definition not available.')
                 if call_def is not None:
                     out.writeln(header('Call def:\t')+self.format(call_def))
                 call_ds = getdoc(obj.__call__)
                 # Skip Python's auto-generated docstrings
                 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
                     call_ds = None
                 if call_ds:
                     out.writeln(header('Call docstring:\n') + indent(call_ds))
 
         # Finally send to printer/pager
         output = out.getvalue()
         if output:
             page(output)
         # end pinfo
 
     def psearch(self,pattern,ns_table,ns_search=[],
                 ignore_case=False,show_all=False):
         """Search namespaces with wildcards for objects.
 
         Arguments:
 
         - pattern: string containing shell-like wildcards to use in namespace
         searches and optionally a type specification to narrow the search to
         objects of that type.
 
         - ns_table: dict of name->namespaces for search.
 
         Optional arguments:
         
           - ns_search: list of namespace names to include in search.
 
           - ignore_case(False): make the search case-insensitive.
 
           - show_all(False): show all names, including those starting with
           underscores.
         """
         #print 'ps pattern:<%r>' % pattern # dbg
         
         # defaults
         type_pattern = 'all'
         filter = ''
 
         cmds = pattern.split()
         len_cmds  =  len(cmds)
         if len_cmds == 1:
             # Only filter pattern given
             filter = cmds[0]
         elif len_cmds == 2:
             # Both filter and type specified
             filter,type_pattern = cmds
         else:
             raise ValueError('invalid argument string for psearch: <%s>' %
                              pattern)
 
         # filter search namespaces
         for name in ns_search:
             if name not in ns_table:
                 raise ValueError('invalid namespace <%s>. Valid names: %s' %
                                  (name,ns_table.keys()))
 
         #print 'type_pattern:',type_pattern # dbg
         search_result = []
         for ns_name in ns_search:
             ns = ns_table[ns_name]
             tmp_res = list(list_namespace(ns,type_pattern,filter,
                                           ignore_case=ignore_case,
                                           show_all=show_all))
             search_result.extend(tmp_res)
         search_result.sort()
 
         page('\n'.join(search_result))

IPython/OutputTrap.py

@@ -1,263 +1,258 b''
 # -*- coding: utf-8 -*-
 """Class to trap stdout and stderr and log them separately.
-
-$Id: OutputTrap.py 958 2005-12-27 23:17:51Z fperez $"""
+"""
 
 #*****************************************************************************
 #       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>' % Release.authors['Fernando']
-__license__ = Release.license
-
 import exceptions
 import sys
 from cStringIO import StringIO
 
 class OutputTrapError(exceptions.Exception):
     """Exception for OutputTrap class."""
 
     def __init__(self,args=None):
         exceptions.Exception.__init__(self)
         self.args = args
 
 class OutputTrap:
 
     """Class to trap standard output and standard error. They get logged in
     StringIO objects which are available as <instance>.out and
     <instance>.err. The class also offers summary methods which format this
     data a bit.
 
     A word of caution: because it blocks messages, using this class can make
     debugging very tricky. If you are having bizarre problems silently, try
     turning your output traps off for a while. You can call the constructor
     with the parameter debug=1 for these cases. This turns actual trapping
     off, but you can keep the rest of your code unchanged (this has already
     been a life saver).
 
     Example:
 
     # config: trapper with a line of dots as log separator (final '\\n' needed)
     config = OutputTrap('Config','Out ','Err ','.'*80+'\\n')
 
     # start trapping output
     config.trap_all()
 
     # now all output is logged ...
     # do stuff...
 
     # output back to normal:
     config.release_all()
 
     # print all that got logged:
     print config.summary()
 
     # print individual raw data:
     print config.out.getvalue()
     print config.err.getvalue()
     """
 
     def __init__(self,name='Generic Output Trap',
                  out_head='Standard Output. ',err_head='Standard Error. ',
                  sum_sep='\n',debug=0,trap_out=0,trap_err=0,
                  quiet_out=0,quiet_err=0):
         self.name = name
         self.out_head = out_head
         self.err_head = err_head
         self.sum_sep = sum_sep
         self.out = StringIO()
         self.err = StringIO()
         self.out_save = None
         self.err_save = None
         self.debug = debug
         self.quiet_out = quiet_out
         self.quiet_err = quiet_err
         if trap_out:
             self.trap_out()
         if trap_err:
             self.trap_err()
 
     def trap_out(self):
         """Trap and log stdout."""
         if sys.stdout is self.out:
             raise OutputTrapError,'You are already trapping stdout.'
         if not self.debug:
             self._out_save = sys.stdout
             sys.stdout = self.out
 
     def release_out(self):
         """Release stdout."""
         if not self.debug:
             if not sys.stdout is self.out:
                 raise OutputTrapError,'You are not trapping stdout.'
             sys.stdout = self._out_save
             self.out_save = None
 
     def summary_out(self):
         """Return as a string the log from stdout."""
         out = self.out.getvalue()
         if out:
             if self.quiet_out:
                 return out
             else:
                 return self.out_head + 'Log by '+ self.name + ':\n' + out
         else:
             return ''
 
     def flush_out(self):
         """Flush the stdout log. All data held in the log is lost."""
 
         self.out.close()
         self.out = StringIO()
 
     def trap_err(self):
         """Trap and log stderr."""
         if sys.stderr is self.err:
             raise OutputTrapError,'You are already trapping stderr.'
         if not self.debug:
             self._err_save = sys.stderr
             sys.stderr = self.err
 
     def release_err(self):
         """Release stderr."""
         if not self.debug:
             if not sys.stderr is self.err:
                 raise OutputTrapError,'You are not trapping stderr.'
             sys.stderr = self._err_save
             self.err_save = None
 
     def summary_err(self):
         """Return as a string the log from stderr."""
         err = self.err.getvalue()
         if err:
             if self.quiet_err:
                 return err
             else:
                 return self.err_head + 'Log by '+ self.name + ':\n' + err
         else:
             return ''
 
     def flush_err(self):
         """Flush the stdout log. All data held in the log is lost."""
 
         self.err.close()
         self.err = StringIO()
 
     def trap_all(self):
         """Trap and log both stdout and stderr.
 
         Cacthes and discards OutputTrapError exceptions raised."""
         try:
             self.trap_out()
         except OutputTrapError:
             pass
         try:
             self.trap_err()
         except OutputTrapError:
             pass
 
     def release_all(self):
         """Release both stdout and stderr.
 
         Cacthes and discards OutputTrapError exceptions raised."""
         try:
             self.release_out()
         except OutputTrapError:
             pass
         try:
             self.release_err()
         except OutputTrapError:
             pass
         
     def summary_all(self):
         """Return as a string the log from stdout and stderr, prepending a separator
         to each (defined in __init__ as sum_sep)."""
         sum = ''
         sout = self.summary_out()
         if sout:
             sum += self.sum_sep + sout
         serr = self.summary_err()
         if serr:
             sum += '\n'+self.sum_sep + serr
         return sum
 
     def flush_all(self):
         """Flush stdout and stderr"""
         self.flush_out()
         self.flush_err()
 
     # a few shorthands
     trap = trap_all
     release = release_all
     summary = summary_all
     flush = flush_all
 # end OutputTrap
 
 
 #****************************************************************************
 # Module testing. Incomplete, I'm lazy...
 
 def _test_all():
 
     """Module testing functions, activated when the module is called as a
     script (not imported)."""
 
     # Put tests for this module in here.
     # Define them as nested functions so they don't clobber the
     # pydoc-generated docs
 
     def _test_():
         name = ''
         print '#'*50+'\nRunning test for ' + name
         # ...
         print 'Finished test for '+ name +'\n'+'#'*50
 
     def _test_OutputTrap():
         trap = OutputTrap(name = 'Test Trap', sum_sep = '.'*50+'\n',
                           out_head = 'SOut. ', err_head = 'SErr. ')
 
         name = 'OutputTrap class'
         print '#'*50+'\nRunning test for ' + name
         print 'Trapping out'
         trap.trap_out()
         print >>sys.stdout, '>>stdout. stdout is trapped.'
         print >>sys.stderr, '>>stderr. stdout is trapped.'
         trap.release_out()
         print trap.summary_out()
 
         print 'Trapping err'
         trap.trap_err()
         print >>sys.stdout, '>>stdout. stderr is trapped.'
         print >>sys.stderr, '>>stderr. stderr is trapped.'
         trap.release_err()
         print trap.summary_err()
 
         print 'Trapping all (no flushing)'
         trap.trap_all()
         print >>sys.stdout, '>>stdout. stdout/err is trapped.'
         print >>sys.stderr, '>>stderr. stdout/err is trapped.'
         trap.release_all()
         print trap.summary_all()
 
         print 'Trapping all (flushing first)'
         trap.flush()
         trap.trap_all()
         print >>sys.stdout, '>>stdout. stdout/err is trapped.'
         print >>sys.stderr, '>>stderr. stdout/err is trapped.'
         trap.release_all()
         print trap.summary_all()
         print 'Finished test for '+ name +'\n'+'#'*50
 
     # call the actual tests here:
     _test_OutputTrap()
 
 
 if __name__=="__main__":
     # _test_all() # XXX BROKEN.
     pass
 
 #************************ end of file <OutputTrap.py> ************************

IPython/Prompts.py

@@ -1,625 +1,624 b''
 # -*- coding: utf-8 -*-
 """
 Classes for handling input/output prompts.
-
-$Id: Prompts.py 3026 2008-02-07 16:03:16Z vivainio $"""
+"""
 
 #*****************************************************************************
 #       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
 
 # IPython's own
 from IPython import ColorANSI
 from IPython.Itpl import ItplNS
 from IPython.ipstruct import Struct
 from IPython.macro import Macro
 from IPython.genutils import *
 from IPython.ipapi import TryNext
 
 #****************************************************************************
 #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}',
     r'\#': '${self.col_num}' '${self.cache.prompt_count}' '${self.col_p}',
     # Just the prompt counter number, WITHOUT any coloring wrappers, so users
     # can get numbers displayed in whatever color they want.
     r'\N': '${self.cache.prompt_count}',
     # Prompt/history count, with the actual digits replaced by dots.  Used
     # mainly in continuation prompts (prompt_in2)
     r'\D': '${"."*len(str(self.cache.prompt_count))}',
     # Current working directory
     r'\w': '${os.getcwd()}',
     # Current time
     r'\t' : '${time.strftime("%H:%M:%S")}',
     # Basename of current working directory.
     # (use os.sep to make this portable across OSes)
     r'\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 '~'
     r'\X0': '${os.getcwd().replace("%s","~")}' % HOME,
     r'\X1': '${self.cwd_filt(1)}',
     r'\X2': '${self.cwd_filt(2)}',
     r'\X3': '${self.cwd_filt(3)}',
     r'\X4': '${self.cwd_filt(4)}',
     r'\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.
     r'\Y0': '${self.cwd_filt2(0)}',
     r'\Y1': '${self.cwd_filt2(1)}',
     r'\Y2': '${self.cwd_filt2(2)}',
     r'\Y3': '${self.cwd_filt2(3)}',
     r'\Y4': '${self.cwd_filt2(4)}',
     r'\Y5': '${self.cwd_filt2(5)}',
     # Hostname up to first .
     r'\h': HOSTNAME_SHORT,
     # Full hostname
     r'\H': HOSTNAME,
     # Username of current user
     r'\u': USER,
     # Escaped '\'
     '\\\\': '\\',
     # Newline
     r'\n': '\n',
     # Carriage return
     r'\r': '\r',
     # Release version
     r'\v': __version__,
     # Root symbol ($ or #)
     r'\$': 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[r'\#'] = '${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 = r'\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(object):
     """Interactive prompt similar to Mathematica's."""
 
     def _get_p_template(self):
         return self._p_template
 
     def _set_p_template(self,val):
         self._p_template = val
         self.set_p_str()
 
     p_template = property(_get_p_template,_set_p_template,
                           doc='Template for prompt string creation')
 
     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).
         # Use a property
         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()
         try:
             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)
         except:
             print "Illegal prompt template (check $ usage!):",self.p_template
             self.p_str = self.p_template
             self.p_str_nocolor = self.p_template
 
     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."""
 
         full_cwd = os.getcwd()
         cwd = full_cwd.replace(HOME,"~").split(os.sep)
         if '~' in cwd and len(cwd) == depth+1:
             depth += 1
         drivepart = ''
         if sys.platform == 'win32' and len(cwd) > depth:
             drivepart = os.path.splitdrive(full_cwd)[0]
         out = drivepart + '/'.join(cwd[-depth:])
 
         if out:
             return out
         else:
             return os.sep
 
     def __nonzero__(self):
         """Implement boolean behavior.
 
         Checks whether the p_str attribute is non-empty"""
 
         return bool(self.p_template)
 
 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 = 3
         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(r'\#') > -1 \
                    or ps1.find(r'\N') > -1:
                 ps1 = '>>> '
             if ps2.find('%n') > -1 or ps2.find(r'\#') > -1 \
                    or ps2.find(r'\N') > -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
         # Store the last prompt string each time, we need it for aligning
         # continuation and auto-rewrite prompts
         self.last_prompt = ''
         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
 
             # do not print output if input ends in ';'
             try:
                 if self.input_hist[self.prompt_count].endswith(';\n'):
                     return
             except IndexError:
                 # some uses of ipshellembed may fail here
                 pass
             # don't use print, puts an extra space
             cout_write(self.output_sep)
             outprompt = self.shell.hooks.generate_output_prompt()
             if self.do_full_cache:
                 cout_write(outprompt)
 
             # and now call a possibly user-defined print mechanism
             manipulated_val = self.display(arg)
             
             # user display hooks can change the variable to be stored in
             # output history
             
             if manipulated_val is not None:
                 arg = manipulated_val
                 
             # avoid recursive reference when displaying _oh/Out
             if arg is not self.user_ns['_oh']:
                 self.update(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.
 
         Do ip.set_hook("result_display", my_displayhook) for custom result
         display, e.g. when your own objects need special formatting.
         """
         try:
             return IPython.generics.result_display(arg)
         except TryNext:            
             return self.shell.hooks.result_display(arg)
 
     # Assign the default display method:
     display = _display
 
     def update(self,arg):
         #print '***cache_count', self.cache_count # dbg
         if len(self.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
             warn('Output cache limit (currently '+
                   `self.cache_size`+' entries) hit.\n'
                  'Flushing cache and resetting history counter...\n'
                  'The only history variables available will be _,__,___ and _1\n'
                  'with the current result.')
 
             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:
             new_result = '_'+`self.prompt_count`
             to_main[new_result] = arg
             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!"
         # 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.user_ns['_oh'].clear()
         
         if '_' not in __builtin__.__dict__:
             self.user_ns.update({'_':None,'__':None, '___':None})
         import gc
         gc.collect() # xxx needed?
 

IPython/PyColorize.py

@@ -1,301 +1,300 b''
 # -*- coding: utf-8 -*-
 """
     Class and program to colorize python source code for ANSI terminals.
 
     Based on an HTML code highlighter by Jurgen Hermann found at:
     http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52298
 
     Modifications by Fernando Perez ([e-mail]).
 
     Information on the original HTML highlighter follows:
     
     MoinMoin - Python Source Parser
 
     Title: Colorize Python source using the built-in tokenizer
            
     Submitter: Jurgen Hermann
     Last Updated:2001/04/06
            
     Version no:1.2
 
     Description:
 
     This code is part of MoinMoin (http://moin.sourceforge.net/) and converts
     Python source code to HTML markup, rendering comments, keywords,
     operators, numeric and string literals in different colors.
 
     It shows how to use the built-in keyword, token and tokenize modules to
     scan Python source code and re-emit it with no changes to its original
     formatting (which is the hard part).
-
-    $Id: PyColorize.py 2586 2007-08-06 19:30:09Z vivainio $"""
+"""
 
 __all__ = ['ANSICodeColors','Parser']
 
 _scheme_default = 'Linux'
 
 # Imports
 import cStringIO
 import keyword
 import os
 import optparse
 import string
 import sys
 import token
 import tokenize
 
 from IPython.ColorANSI import *
 
 #############################################################################
 ### Python Source Parser (does Hilighting)
 #############################################################################
 
 _KEYWORD = token.NT_OFFSET + 1
 _TEXT    = token.NT_OFFSET + 2
 
 #****************************************************************************
 # Builtin color schemes
 
 Colors = TermColors  # just a shorthand
 
 # Build a few color schemes
 NoColor = ColorScheme(
     'NoColor',{
     token.NUMBER     : Colors.NoColor,
     token.OP         : Colors.NoColor,
     token.STRING     : Colors.NoColor,
     tokenize.COMMENT : Colors.NoColor,
     token.NAME       : Colors.NoColor,
     token.ERRORTOKEN : Colors.NoColor,
 
     _KEYWORD         : Colors.NoColor,
     _TEXT            : Colors.NoColor,
 
     'normal'         : Colors.NoColor  # color off (usu. Colors.Normal)
     }  )
 
 LinuxColors = ColorScheme(
     'Linux',{
     token.NUMBER     : Colors.LightCyan,
     token.OP         : Colors.Yellow,
     token.STRING     : Colors.LightBlue,
     tokenize.COMMENT : Colors.LightRed,
     token.NAME       : Colors.White,
     token.ERRORTOKEN : Colors.Red,
 
     _KEYWORD         : Colors.LightGreen,
     _TEXT            : Colors.Yellow,
 
     'normal'         : Colors.Normal  # color off (usu. Colors.Normal)
     } )
 
 LightBGColors = ColorScheme(
     'LightBG',{
     token.NUMBER     : Colors.Cyan,
     token.OP         : Colors.Blue,
     token.STRING     : Colors.Blue,
     tokenize.COMMENT : Colors.Red,
     token.NAME       : Colors.Black,
     token.ERRORTOKEN : Colors.Red,
 
     _KEYWORD         : Colors.Green,
     _TEXT            : Colors.Blue,
 
     'normal'         : Colors.Normal  # color off (usu. Colors.Normal)
     }  )
 
 # Build table of color schemes (needed by the parser)
 ANSICodeColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
                                   _scheme_default)
 
 class Parser:
     """ Format colored Python source.
     """
 
     def __init__(self, color_table=None,out = sys.stdout):
         """ Create a parser with a specified color table and output channel.
 
         Call format() to process code.
         """
         self.color_table = color_table and color_table or ANSICodeColors
         self.out = out
 
     def format(self, raw, out = None, scheme = ''):
         return self.format2(raw, out, scheme)[0]
 
     def format2(self, raw, out = None, scheme = ''):
         """ Parse and send the colored source.
 
         If out and scheme are not specified, the defaults (given to
         constructor) are used.
 
         out should be a file-type object. Optionally, out can be given as the
         string 'str' and the parser will automatically return the output in a
         string."""
         
         string_output = 0
         if out == 'str' or self.out == 'str' or \
            isinstance(self.out,cStringIO.OutputType):
             # XXX - I don't really like this state handling logic, but at this
             # point I don't want to make major changes, so adding the
             # isinstance() check is the simplest I can do to ensure correct
             # behavior.
             out_old = self.out
             self.out = cStringIO.StringIO()
             string_output = 1
         elif out is not None:
             self.out = out
 
         # Fast return of the unmodified input for NoColor scheme
         if scheme == 'NoColor':
             error = False
             self.out.write(raw)
             if string_output:
                 return raw,error
             else:
                 return None,error
         
         # local shorthands
         colors = self.color_table[scheme].colors
         self.colors = colors # put in object so __call__ sees it
 
         # Remove trailing whitespace and normalize tabs
         self.raw = raw.expandtabs().rstrip()
         
         # store line offsets in self.lines
         self.lines = [0, 0]
         pos = 0
         raw_find = self.raw.find
         lines_append = self.lines.append
         while 1:
             pos = raw_find('\n', pos) + 1
             if not pos: break
             lines_append(pos)
         lines_append(len(self.raw))
 
         # parse the source and write it
         self.pos = 0
         text = cStringIO.StringIO(self.raw)
 
         error = False
         try:
             tokenize.tokenize(text.readline, self)
         except tokenize.TokenError, ex:
             msg = ex[0]
             line = ex[1][0]
             self.out.write("%s\n\n*** ERROR: %s%s%s\n" %
                            (colors[token.ERRORTOKEN],
                             msg, self.raw[self.lines[line]:],
                             colors.normal)
                            )
             error = True
         self.out.write(colors.normal+'\n')
         if string_output:
             output = self.out.getvalue()
             self.out = out_old
             return (output, error)
         return (None, error)
 
     def __call__(self, toktype, toktext, (srow,scol), (erow,ecol), line):
         """ Token handler, with syntax highlighting."""
 
         # local shorthands
         colors = self.colors
         owrite = self.out.write
 
         # line separator, so this works across platforms
         linesep = os.linesep
 
         # calculate new positions
         oldpos = self.pos
         newpos = self.lines[srow] + scol
         self.pos = newpos + len(toktext)
 
         # handle newlines
         if toktype in [token.NEWLINE, tokenize.NL]:
             owrite(linesep)
             return
 
         # send the original whitespace, if needed
         if newpos > oldpos:
             owrite(self.raw[oldpos:newpos])
 
         # skip indenting tokens
         if toktype in [token.INDENT, token.DEDENT]:
             self.pos = newpos
             return
 
         # map token type to a color group
         if token.LPAR <= toktype and toktype <= token.OP:
             toktype = token.OP
         elif toktype == token.NAME and keyword.iskeyword(toktext):
             toktype = _KEYWORD
         color = colors.get(toktype, colors[_TEXT])
 
         #print '<%s>' % toktext,    # dbg
 
         # Triple quoted strings must be handled carefully so that backtracking
         # in pagers works correctly. We need color terminators on _each_ line.
         if linesep in toktext:
             toktext = toktext.replace(linesep, '%s%s%s' %
                                       (colors.normal,linesep,color))
 
         # send text
         owrite('%s%s%s' % (color,toktext,colors.normal))
             
 def main(argv=None):
     """Run as a command-line script: colorize a python file or stdin using ANSI
     color escapes and print to stdout.
 
     Inputs:
 
       - argv(None): a list of strings like sys.argv[1:] giving the command-line
         arguments. If None, use sys.argv[1:].
     """
 
     usage_msg = """%prog [options] [filename]
 
 Colorize a python file or stdin using ANSI color escapes and print to stdout.
 If no filename is given, or if filename is -, read standard input."""
 
     parser = optparse.OptionParser(usage=usage_msg)
     newopt = parser.add_option
     newopt('-s','--scheme',metavar='NAME',dest='scheme_name',action='store',
            choices=['Linux','LightBG','NoColor'],default=_scheme_default,
            help="give the color scheme to use. Currently only 'Linux'\
  (default) and 'LightBG' and 'NoColor' are implemented (give without\
  quotes)")
 
     opts,args = parser.parse_args(argv)
 
     if len(args) > 1:
         parser.error("you must give at most one filename.")
 
     if len(args) == 0:
         fname = '-' # no filename given; setup to read from stdin
     else:
         fname = args[0]
 
     if fname == '-':
         stream = sys.stdin
     else:
         stream = file(fname)
 
     parser = Parser()
 
     # we need nested try blocks because pre-2.5 python doesn't support unified
     # try-except-finally
     try:
         try:
             # write colorized version to stdout
             parser.format(stream.read(),scheme=opts.scheme_name)
         except IOError,msg:
             # if user reads through a pager and quits, don't print traceback
             if msg.args != (32,'Broken pipe'):
                 raise
     finally:
         if stream is not sys.stdin:
             stream.close() # in case a non-handled exception happened above
 
 if __name__ == "__main__":
     main()

IPython/Shell.py

@@ -1,1238 +1,1233 b''
 # -*- coding: utf-8 -*-
 """IPython Shell classes.
 
 All the matplotlib support code was co-developed with John Hunter,
 matplotlib's author.
-
-$Id: Shell.py 3024 2008-02-07 15:34:42Z darren.dale $"""
+"""
 
 #*****************************************************************************
 #       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
 # Stdlib imports
 import __builtin__
 import __main__
 import Queue
 import inspect
 import os
 import sys
 import thread
 import threading
 import time
 
 from signal import signal, SIGINT
 
 try:
     import ctypes
     HAS_CTYPES = True
 except ImportError:
     HAS_CTYPES = False
 
 # IPython imports
 import IPython
 from IPython import ultraTB, ipapi
 from IPython.Magic import Magic
 from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
 from IPython.iplib import InteractiveShell
 from IPython.ipmaker import make_IPython
 from IPython.ipstruct import Struct
 from IPython.testing import decorators as testdec
 
 # Globals
 # global flag to pass around information about Ctrl-C without exceptions
 KBINT = False
 
 # global flag to turn on/off Tk support.
 USE_TK = False
 
 # ID for the main thread, used for cross-thread exceptions
 MAIN_THREAD_ID = thread.get_ident()
 
 # Tag when runcode() is active, for exception handling
 CODE_RUN = None
 
 # Default timeout for waiting for multithreaded shells (in seconds)
 GUI_TIMEOUT = 10
 
 #-----------------------------------------------------------------------------
 # 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()
 
 #-----------------------------------------------------------------------------
 def kill_embedded(self,parameter_s=''):
     """%kill_embedded : deactivate for good the current embedded IPython.
 
     This function (after asking for confirmation) sets an internal flag so that
     an embedded IPython will never activate again.  This is useful to
     permanently disable a shell that is being called inside a loop: once you've
     figured out what you needed from it, you may then kill it and the program
     will then continue to run without the interactive shell interfering again.
     """
     
     kill = ask_yes_no("Are you sure you want to kill this embedded instance "
                      "(y/n)? [y/N] ",'n')
     if kill:
         self.shell.embedded_active = False
         print "This embedded IPython will not reactivate anymore once you 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,
                  user_ns=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
         
         self.IP = make_IPython(argv,rc_override=rc_override,
                                embedded=True,
                                user_ns=user_ns)
 
         ip = ipapi.IPApi(self.IP)
         ip.expose_magic("kill_embedded",kill_embedded)
 
         # 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.  """
 
         # If the user has turned it off, go away
         if not self.IP.embedded_active:
             return
 
         # Normal exits from interactive mode set this flag, so the shell can't
         # re-enter (it checks this variable at the start of interactive mode).
         self.IP.exit_now = False
 
         # 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.set_completer()
 
         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
 
 #-----------------------------------------------------------------------------
 if HAS_CTYPES:
     #  Add async exception support.  Trick taken from:
     # http://sebulba.wikispaces.com/recipe+thread2
     def _async_raise(tid, exctype):
         """raises the exception, performs cleanup if needed"""
         if not inspect.isclass(exctype):
             raise TypeError("Only types can be raised (not instances)")
         res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid,
                                                          ctypes.py_object(exctype))
         if res == 0:
             raise ValueError("invalid thread id")
         elif res != 1:
             # """if it returns a number greater than one, you're in trouble, 
             # and you should call it again with exc=NULL to revert the effect"""
             ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, 0)
             raise SystemError("PyThreadState_SetAsyncExc failed")
 
     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
 
         if CODE_RUN:
             _async_raise(MAIN_THREAD_ID,KeyboardInterrupt)
         else:
             KBINT = True
             print '\nKeyboardInterrupt - Press <Enter> to continue.',
             Term.cout.flush()
 
 else:
     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='',
                  gui_timeout=GUI_TIMEOUT,**kw):
         """Similar to the normal InteractiveShell, but with threading control"""
         
         InteractiveShell.__init__(self,name,usage,rc,user_ns,
                                   user_global_ns,banner2)
 
         # Timeout we wait for GUI thread
         self.gui_timeout = gui_timeout
 
         # A queue to hold the code to be executed. 
         self.code_queue = Queue.Queue()
 
         # Stuff to do at closing time
         self._kill = None
         on_kill = kw.get('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
         # thread identity of the "worker thread" (that may execute code directly)
         self.worker_ident = None
         
     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
 
         if self._kill:
             # can't queue new code if we are being killed
             return True
         
         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
 
         # shortcut - if we are in worker thread, or the worker thread is not
         # running, execute directly (to allow recursion and prevent deadlock if
         # code is run early in IPython construction)
         
         if (self.worker_ident is None
             or self.worker_ident == thread.get_ident() ):
             InteractiveShell.runcode(self,code)
             return
 
         # Case 3
         # Store code in queue, so the execution thread can handle it.
 
         completed_ev, received_ev = threading.Event(), threading.Event() 
         
         self.code_queue.put((code,completed_ev, received_ev))
         # first make sure the message was received, with timeout
         received_ev.wait(self.gui_timeout)
         if not received_ev.isSet():
             # the mainloop is dead, start executing code directly
             print "Warning: Timeout for mainloop thread exceeded"
             print "switching to nonthreaded mode (until mainloop wakes up again)"
             self.worker_ident = None
         else:
             completed_ev.wait()
         return False
 
     def runcode(self):
         """Execute a code object.
 
         Multithreaded wrapper around IPython's runcode()."""
         
         global CODE_RUN
         
         # we are in worker thread, stash out the id for runsource() 
         self.worker_ident = thread.get_ident()
 
         if self._kill:
             print >>Term.cout, 'Closing threads...',
             Term.cout.flush()
             for tokill in self.on_kill:
                 tokill()
             print >>Term.cout, 'Done.'
             # allow kill() to return
             self._kill.set()
             return True
 
         # Install sigint handler.  We do it every time to ensure that if user
         # code modifies it, we restore our own handling.
         try:
             signal(SIGINT,sigint_handler)
         except SystemError:
             # This happens under Windows, which seems to have all sorts
             # of problems with signal handling.  Oh well...
             pass
 
         # Flush queue of pending code by calling the run methood of the parent
         # class with all items which may be in the queue.
         code_to_run = None
         while 1:
             try:
                 code_to_run, completed_ev, received_ev = self.code_queue.get_nowait()                
             except Queue.Empty:
                 break
             received_ev.set()
             
             # Exceptions need to be raised differently depending on which
             # thread is active.  This convoluted try/except is only there to
             # protect against asynchronous exceptions, to ensure that a KBINT
             # at the wrong time doesn't deadlock everything.  The global
             # CODE_TO_RUN is set to true/false as close as possible to the
             # runcode() call, so that the KBINT handler is correctly informed.
             try:
                 try:
                    CODE_RUN = True
                    InteractiveShell.runcode(self,code_to_run)
                 except KeyboardInterrupt:
                    print "Keyboard interrupted in mainloop"
                    while not self.code_queue.empty():
                       code, ev1,ev2 = self.code_queue.get_nowait()
                       ev1.set()
                       ev2.set()                      
                    break
             finally:
                 CODE_RUN = False
                 # allow runsource() return from wait
                 completed_ev.set()
                 
         
         # 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._kill = threading.Event()
         self._kill.wait()
 
 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,user_ns,user_global_ns=None):
         """Return 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
         import matplotlib.pylab as pylab
         self.pylab = pylab
 
         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, user_global_ns = IPython.ipapi.make_user_namespaces(user_ns,
             user_global_ns)
 
         # Import numpy as np/pyplot as plt are conventions we're trying to
         # somewhat standardize on.  Making them available to users by default
         # will greatly help this. 
         exec ("import numpy\n"
               "import numpy as np\n"
               "import matplotlib\n"
               "import matplotlib.pylab as pylab\n"
               "try:\n"
               "    import matplotlib.pyplot as plt\n"
               "except ImportError:\n"
               "    pass\n"
               ) 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,user_global_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
 
     @testdec.skip_doctest
     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,user_global_ns,b2 = self._matplotlib_config(name,user_ns,user_global_ns)
         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,user_global_ns,b2 = self._matplotlib_config(name,user_ns,user_global_ns)
         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
 
     try:
         import wx
     except ImportError:
         # For very old versions of WX
         import wxPython as wx
         
     ver = wx.__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 = wx.wxc.wxPyApp_MainLoop
         wx.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
 
 def hijack_qt():
     """Modifies PyQt's mainloop with a dummy so user code does not 
     block IPython.  This function returns the original 
     `qt.qApp.exec_loop` function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     import qt
     orig_mainloop = qt.qApp.exec_loop
     qt.qApp.exec_loop = dummy_mainloop
     qt.QApplication.exec_loop = dummy_mainloop
     return orig_mainloop
 
 def hijack_qt4():
     """Modifies PyQt4's mainloop with a dummy so user code does not
     block IPython.  This function returns the original 
     `QtGui.qApp.exec_` function that has been hijacked.
     """    
     def dummy_mainloop(*args, **kw):
         pass
     from PyQt4 import QtGui, QtCore
     orig_mainloop = QtGui.qApp.exec_
     QtGui.qApp.exec_ = dummy_mainloop
     QtGui.QApplication.exec_ = dummy_mainloop
     QtCore.QCoreApplication.exec_ = 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 IPThread(threading.Thread):
     def run(self):
         self.IP.mainloop(self._banner)
         self.IP.kill()
 
 class IPShellGTK(IPThread):
     """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 mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         if self.gtk.pygtk_version >= (2,4,0):
             import gobject
             gobject.idle_add(self.on_timer)
         else:
             self.gtk.idle_add(self.on_timer)
 
         if sys.platform != 'win32':
             try:
                 if self.gtk.gtk_version[0] >= 2:
                     self.gtk.gdk.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.gdk.threads_enter()
         self.gtk_mainloop()
         self.gtk.gdk.threads_leave()
         self.join()
 
     def on_timer(self):
         """Called when GTK is idle.
 
         Must return True always, otherwise GTK stops calling it"""
         
         update_tk(self.tk)
         self.IP.runcode()
         time.sleep(0.01)
         return True
 
 
 class IPShellWX(IPThread):
     """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):
 
         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])
 
         wantedwxversion=self.IP.rc.wxversion
         if wantedwxversion!="0":
             try:
                 import wxversion
             except ImportError:
                 error('The wxversion module is needed for WX version selection')
             else:
                 try:
                     wxversion.select(wantedwxversion)
                 except:
                     self.IP.InteractiveTB()
                     error('Requested wxPython version %s could not be loaded' %
                                                                wantedwxversion)
 
         import 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()
         
         # 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 mainloop(self,sys_exit=0,banner=None):
 
         self._banner = banner
         
         self.start()
 
         class TimerAgent(self.wx.MiniFrame):
             wx = self.wx
             IP = self.IP
             tk = self.tk
             def __init__(self, parent, interval):
                 style = self.wx.DEFAULT_FRAME_STYLE | self.wx.TINY_CAPTION_HORIZ
                 self.wx.MiniFrame.__init__(self, parent, -1, ' ', pos=(200, 200),
                                              size=(100, 100),style=style)
                 self.Show(False)
                 self.interval = interval
                 self.timerId = self.wx.NewId()                                
 
             def StartWork(self):
                 self.timer = self.wx.Timer(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.App):
             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(False)
                 self.agent.StartWork()
                 return True
 
         self.app = App(redirect=False)
         self.wx_mainloop(self.app)
         self.join()
 
 
 class IPShellQt(IPThread):
     """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
 
         self.exec_loop = hijack_qt()
 
         # 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 mainloop(self, sys_exit=0, banner=None):
 
         import qt
 
         self._banner = banner
 
         if qt.QApplication.startingUp():
             a = qt.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
             self.exec_loop()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         result = self.IP.runcode()
         self.timer.start(self.TIMEOUT, True)
         return result
 
 
 class IPShellQt4(IPThread):
     """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):
 
         from PyQt4 import QtCore, QtGui
 
         try:
             # present in PyQt4-4.2.1 or later
             QtCore.pyqtRemoveInputHook()
         except AttributeError:
             pass
 
         if QtCore.PYQT_VERSION_STR == '4.3':
             warn('''PyQt4 version 4.3 detected.
 If you experience repeated threading warnings, please update PyQt4.
 ''')
 
         self.exec_ = hijack_qt4()
 
         # 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=[QtGui.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 mainloop(self, sys_exit=0, banner=None):
 
         from PyQt4 import QtCore, QtGui
 
         self._banner = banner
 
         if QtGui.QApplication.startingUp():
             a = QtGui.QApplication(sys.argv)
 
         self.timer = QtCore.QTimer()
         QtCore.QObject.connect(self.timer,
                                QtCore.SIGNAL('timeout()'),
                                self.on_timer)
 
         self.start()
         self.timer.start(self.TIMEOUT)
         while True:
             if self.IP._kill: break
             self.exec_()
         self.join()
 
     def on_timer(self):
         update_tk(self.tk)
         result = self.IP.runcode()
         self.timer.start(self.TIMEOUT)
         return result
 
 
 # A set of matplotlib public IPython shell classes, for single-threaded (Tk*
 # and FLTK*) and multithreaded (GTK*, WX* and Qt*) backends to use.
 def _load_pylab(user_ns):
     """Allow users to disable pulling all of pylab into the top-level
     namespace.
 
     This little utility must be called AFTER the actual ipython instance is
     running, since only then will the options file have been fully parsed."""
     
     ip = IPython.ipapi.get()
     if ip.options.pylab_import_all:
         ip.ex("from matplotlib.pylab import *")
         ip.IP.user_config_ns.update(ip.user_ns)
         
 
 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)
         _load_pylab(self.IP.user_ns)
 
 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)
         _load_pylab(self.IP.user_ns)
 
 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)
         _load_pylab(self.IP.user_ns)
 
 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)
         _load_pylab(self.IP.user_ns)
 
 class IPShellMatplotlibQt4(IPShellQt4):
     """Subclass IPShellQt4 with MatplotlibMTShell as the internal shell.
 
     Multi-threaded class, meant for the Qt4* backends."""
 
     def __init__(self,argv=None,user_ns=None,user_global_ns=None,debug=1):
         IPShellQt4.__init__(self,argv,user_ns,user_global_ns,debug,
                            shell_class=MatplotlibMTShell)
         _load_pylab(self.IP.user_ns)
 
 #-----------------------------------------------------------------------------
 # Factory functions to actually start the proper thread-aware shell
 
 def _select_shell(argv):
     """Select a shell from the given argv vector.
 
     This function implements the threading selection policy, allowing runtime
     control of the threading mode, both for general users and for matplotlib.
 
     Return:
       Shell class to be instantiated for runtime operation.
     """
     
     global USE_TK
 
     mpl_shell = {'gthread' : IPShellMatplotlibGTK,
                  'wthread' : IPShellMatplotlibWX,
                  'qthread' : IPShellMatplotlibQt,
                  'q4thread' : IPShellMatplotlibQt4,
                  'tkthread' : IPShellMatplotlib,  # Tk is built-in
                  }
 
     th_shell = {'gthread' : IPShellGTK,
                 'wthread' : IPShellWX,
                 'qthread' : IPShellQt,
                 'q4thread' : IPShellQt4,
                 'tkthread' : IPShell, # Tk is built-in
                 }
 
     backends = {'gthread' : 'GTKAgg',
                 'wthread' : 'WXAgg',
                 'qthread' : 'QtAgg',
                 'q4thread' :'Qt4Agg',
                 'tkthread' :'TkAgg',
                 }
 
     all_opts = set(['tk','pylab','gthread','qthread','q4thread','wthread',
                     'tkthread'])
     user_opts = set([s.replace('-','') for s in argv[:3]])
     special_opts = user_opts & all_opts            
 
     if 'tk' in special_opts:
         USE_TK = True
         special_opts.remove('tk')
 
     if 'pylab' in special_opts:
 
         try:
             import matplotlib
         except ImportError:
             error('matplotlib could NOT be imported!  Starting normal IPython.')
             return IPShell
         
         special_opts.remove('pylab')
         # If there's any option left, it means the user wants to force the
         # threading backend, else it's auto-selected from the rc file
         if special_opts:
             th_mode = special_opts.pop()
             matplotlib.rcParams['backend'] = backends[th_mode]
         else:
             backend = matplotlib.rcParams['backend']
             if backend.startswith('GTK'):
                 th_mode = 'gthread'
             elif backend.startswith('WX'):
                 th_mode = 'wthread'
             elif backend.startswith('Qt4'):
                 th_mode = 'q4thread'
             elif backend.startswith('Qt'):
                 th_mode = 'qthread'
             else:
                 # Any other backend, use plain Tk
                 th_mode = 'tkthread'
                 
         return mpl_shell[th_mode]
     else:
         # No pylab requested, just plain threads
         try:
             th_mode = special_opts.pop()
         except KeyError:
             th_mode = 'tkthread'
         return th_shell[th_mode]
 
 
 # This is the one which should be called by external code.
 def start(user_ns = None):
     """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."""
 
     shell = _select_shell(sys.argv)
     return shell(user_ns = user_ns)
 
 # Some aliases for backwards compatibility
 IPythonShell = IPShell
 IPythonShellEmbed = IPShellEmbed
 #************************ End of file <Shell.py> ***************************

IPython/__init__.py

@@ -1,72 +1,71 b''
 # -*- coding: utf-8 -*-
 """
 IPython -- An enhanced Interactive Python
 
 One of Python's nicest features is its interactive interpreter. This allows
 very fast testing of ideas without the overhead of creating test files as is
 typical in most programming languages. However, the interpreter supplied with
 the standard Python distribution is fairly primitive (and IDLE isn't really
 much better).
 
 IPython tries to:
 
   i - provide an efficient environment for interactive work in Python
   programming. It tries to address what we see as shortcomings of the standard
   Python prompt, and adds many features to make interactive work much more
   efficient.
 
   ii - offer a flexible framework so that it can be used as the base
   environment for other projects and problems where Python can be the
   underlying language. Specifically scientific environments like Mathematica,
   IDL and Mathcad inspired its design, but similar ideas can be useful in many
   fields. Python is a fabulous language for implementing this kind of system
   (due to its dynamic and introspective features), and with suitable libraries
   entire systems could be built leveraging Python's power.
 
   iii - serve as an embeddable, ready to go interpreter for your own programs.
 
-IPython requires Python 2.3 or newer.
-
-$Id: __init__.py 2399 2007-05-26 10:23:10Z vivainio $"""
+IPython requires Python 2.4 or newer.
+"""
 
 #*****************************************************************************
 #       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.
 #*****************************************************************************
 
 # Enforce proper version requirements
 import sys
 
 if sys.version[0:3] < '2.4':
     raise ImportError('Python Version 2.4 or above is required for IPython.')
 
 # Make it easy to import extensions - they are always directly on pythonpath.
 # Therefore, non-IPython modules can be added to Extensions directory
 import os
 sys.path.append(os.path.dirname(__file__) + "/Extensions")
 
 # Define what gets imported with a 'from IPython import *'
 __all__ = ['ipapi','generics','ipstruct','Release','Shell']
 
 # Load __all__ in IPython namespace so that a simple 'import IPython' gives
 # access to them via IPython.<name>
 glob,loc = globals(),locals()
 for name in __all__:
     #print 'Importing: ',name # dbg
     __import__(name,glob,loc,[])
 
 import Shell
 
 # Release data
 from IPython import Release # do it explicitly so pydoc can see it - pydoc bug
 __author__   = '%s <%s>\n%s <%s>\n%s <%s>' % \
                ( Release.authors['Fernando'] + Release.authors['Janko'] + \
                  Release.authors['Nathan'] )
 __license__  = Release.license
 __version__  = Release.version
 __revision__ = Release.revision
 
 # Namespace cleanup
 del name,glob,loc

IPython/background_jobs.py

@@ -1,496 +1,490 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 994 2006-01-08 08:29:44Z fperez $
 """
 
 #*****************************************************************************
 #       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/deep_reload.py

@@ -1,189 +1,182 b''
 # -*- coding: utf-8 -*-
 """
 A module to change reload() so that it acts recursively.
 To enable it type:
     >>> import __builtin__, deep_reload
     >>> __builtin__.reload = deep_reload.reload
 
 You can then disable it with:
     >>> __builtin__.reload = deep_reload.original_reload
     
 Alternatively, you can add a dreload builtin alongside normal reload with:
     >>> __builtin__.dreload = deep_reload.reload
     
 This code is almost entirely based on knee.py from the standard library.
-
-$Id: deep_reload.py 958 2005-12-27 23:17:51Z fperez $"""
+"""
 
 #*****************************************************************************
 #       Copyright (C) 2001 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.
 #*****************************************************************************
 
-from IPython import Release # do it explicitly so pydoc can see it - pydoc bug
-__author__  = '%s <%s>' %  Release.authors['Nathan']
-__license__ = Release.license
-__version__ = "0.5"
-__date__    = "21 August 2001"
-
 import __builtin__
 import imp
 import sys
 
 # Replacement for __import__()
 def deep_import_hook(name, globals=None, locals=None, fromlist=None, level=-1):
     # For now level is ignored, it's just there to prevent crash  
     # with from __future__ import absolute_import
     parent = determine_parent(globals)
     q, tail = find_head_package(parent, name)
     m = load_tail(q, tail)
     if not fromlist:
         return q
     if hasattr(m, "__path__"):
         ensure_fromlist(m, fromlist)
     return m
 
 def determine_parent(globals):
     if not globals or  not globals.has_key("__name__"):
         return None
     pname = globals['__name__']
     if globals.has_key("__path__"):
         parent = sys.modules[pname]
         assert globals is parent.__dict__
         return parent
     if '.' in pname:
         i = pname.rfind('.')
         pname = pname[:i]
         parent = sys.modules[pname]
         assert parent.__name__ == pname
         return parent
     return None
 
 def find_head_package(parent, name):
     # Import the first
     if '.' in name:
         # 'some.nested.package' -> head = 'some', tail = 'nested.package'
         i = name.find('.')
         head = name[:i]
         tail = name[i+1:]
     else:
         # 'packagename' -> head = 'packagename', tail = ''
         head = name
         tail = ""
     if parent:
         # If this is a subpackage then qname = parent's name + head
         qname = "%s.%s" % (parent.__name__, head)
     else:
         qname = head
     q = import_module(head, qname, parent)
     if q: return q, tail
     if parent:
         qname = head
         parent = None
         q = import_module(head, qname, parent)
         if q: return q, tail
     raise ImportError, "No module named " + qname
 
 def load_tail(q, tail):
     m = q
     while tail:
         i = tail.find('.')
         if i < 0: i = len(tail)
         head, tail = tail[:i], tail[i+1:]
 
         # fperez: fix dotted.name reloading failures by changing:
         #mname = "%s.%s" % (m.__name__, head)
         # to:
         mname = m.__name__
         # This needs more testing!!! (I don't understand this module too well)
         
         #print '** head,tail=|%s|->|%s|, mname=|%s|' % (head,tail,mname)  # dbg
         m = import_module(head, mname, m)
         if not m:
             raise ImportError, "No module named " + mname
     return m
 
 def ensure_fromlist(m, fromlist, recursive=0):
     for sub in fromlist:
         if sub == "*":
             if not recursive:
                 try:
                     all = m.__all__
                 except AttributeError:
                     pass
                 else:
                     ensure_fromlist(m, all, 1)
             continue
         if sub != "*" and not hasattr(m, sub):
             subname = "%s.%s" % (m.__name__, sub)
             submod = import_module(sub, subname, m)
             if not submod:
                 raise ImportError, "No module named " + subname
 
 # Need to keep track of what we've already reloaded to prevent cyclic evil
 found_now = {}
 
 def import_module(partname, fqname, parent):
     global found_now
     if found_now.has_key(fqname):
         try:
             return sys.modules[fqname]    
         except KeyError:
             pass
     
     print 'Reloading', fqname #, sys.excepthook is sys.__excepthook__, \
             #sys.displayhook is sys.__displayhook__
     
     found_now[fqname] = 1
     try:
         fp, pathname, stuff = imp.find_module(partname,
                                               parent and parent.__path__)
     except ImportError:
         return None
         
     try:
         m = imp.load_module(fqname, fp, pathname, stuff)
     finally:
         if fp: fp.close()
         
     if parent:
         setattr(parent, partname, m)
 
     return m
 
 def deep_reload_hook(module):
     name = module.__name__
     if '.' not in name:
         return import_module(name, name, None)
     i = name.rfind('.')
     pname = name[:i]
     parent = sys.modules[pname]
     return import_module(name[i+1:], name, parent)
 
 # Save the original hooks
 original_reload = __builtin__.reload
 
 # Replacement for reload()
 def reload(module, exclude=['sys', '__builtin__', '__main__']):
     """Recursively reload all modules used in the given module.  Optionally
     takes a list of modules to exclude from reloading.  The default exclude
     list contains sys, __main__, and __builtin__, to prevent, e.g., resetting 
     display, exception, and io hooks.
     """
     global found_now
     for i in exclude:
         found_now[i] = 1
     original_import = __builtin__.__import__
     __builtin__.__import__ = deep_import_hook    
     try:
         ret = deep_reload_hook(module)
     finally:
         __builtin__.__import__ = original_import
         found_now = {}
     return ret
 
 # Uncomment the following to automatically activate deep reloading whenever
 # this module is imported
 #__builtin__.reload = reload

IPython/excolors.py

@@ -1,143 +1,137 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-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
 
 def exception_colors():
     """Return a color table with fields for exception reporting.
 
     The table is an instance of ColorSchemeTable with schemes added for
     'Linux', 'LightBG' and 'NoColor' and fields for exception handling filled
     in.
 
     Examples:
 
     >>> ec = exception_colors()
     >>> ec.active_scheme_name
     ''
     >>> print ec.active_colors
     None
 
     Now we activate a color scheme:    
     >>> ec.set_active_scheme('NoColor')
     >>> ec.active_scheme_name
     'NoColor'
     >>> ec.active_colors.keys()
     ['em', 'caret', '__allownew', 'name', 'val', 'vName', 'Normal', 'normalEm',
     'filename', 'linenoEm', 'excName', 'lineno', 'valEm', 'filenameEm',
     'nameEm', 'line', 'topline']
     """
     
     ex_colors = ColorSchemeTable()
 
     # Populate it with color schemes
     C = TermColors # shorthand and local lookup
     ex_colors.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
     ex_colors.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
     ex_colors.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
         ))
 
     return ex_colors
 
 
 # For backwards compatibility, keep around a single global object.  Note that
 # this should NOT be used, the factory function should be used instead, since
 # these objects are stateful and it's very easy to get strange bugs if any code
 # modifies the module-level object's state.
 ExceptionColors = exception_colors()

IPython/external/Itpl.py

@@ -1,278 +1,276 b''
 # -*- coding: utf-8 -*-
 """String interpolation for Python (by Ka-Ping Yee, 14 Feb 2000).
 
 This module lets you quickly and conveniently interpolate values into
 strings (in the flavour of Perl or Tcl, but with less extraneous
 punctuation).  You get a bit more power than in the other languages,
 because this module allows subscripting, slicing, function calls,
 attribute lookup, or arbitrary expressions.  Variables and expressions
 are evaluated in the namespace of the caller.
 
 The itpl() function returns the result of interpolating a string, and
 printpl() prints out an interpolated string.  Here are some examples:
 
     from Itpl import printpl
     printpl("Here is a $string.")
     printpl("Here is a $module.member.")
     printpl("Here is an $object.member.")
     printpl("Here is a $functioncall(with, arguments).")
     printpl("Here is an ${arbitrary + expression}.")
     printpl("Here is an $array[3] member.")
     printpl("Here is a $dictionary['member'].")
 
 The filter() function filters a file object so that output through it
 is interpolated.  This lets you produce the illusion that Python knows
 how to do interpolation:
 
     import Itpl
     sys.stdout = Itpl.filter()
     f = "fancy"
-    print "Isn't this $f?"
+    print "Is this not $f?"
     print "Standard output has been replaced with a $sys.stdout object."
     sys.stdout = Itpl.unfilter()
     print "Okay, back $to $normal."
 
 Under the hood, the Itpl class represents a string that knows how to
 interpolate values.  An instance of the class parses the string once
 upon initialization; the evaluation and substitution can then be done
 each time the instance is evaluated with str(instance).  For example:
 
     from Itpl import Itpl
     s = Itpl("Here is $foo.")
     foo = 5
     print str(s)
     foo = "bar"
     print str(s)
-
-$Id: Itpl.py 2305 2007-05-04 05:34:42Z bgranger $
-"""                   # ' -> close an open quote for stupid emacs
+"""
 
 #*****************************************************************************
 #
 # Copyright (c) 2001 Ka-Ping Yee <[e-mail]>
 #
 #
 # Published under the terms of the MIT license, hereby reproduced:
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
 # deal in the Software without restriction, including without limitation the
 # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 # sell copies of the Software, and to permit persons to whom the Software is
 # furnished to do so, subject to the following conditions:
 #
 # The above copyright notice and this permission notice shall be included in
 # all copies or substantial portions of the Software.
 #
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 #
 #*****************************************************************************
 
 __author__  = 'Ka-Ping Yee <[e-mail]>'
 __license__ = 'MIT'
 
 import string
 import sys
 from tokenize import tokenprog
 from types import StringType
 
 class ItplError(ValueError):
     def __init__(self, text, pos):
         self.text = text
         self.pos = pos
     def __str__(self):
         return "unfinished expression in %s at char %d" % (
             repr(self.text), self.pos)
 
 def matchorfail(text, pos):
     match = tokenprog.match(text, pos)
     if match is None:
         raise ItplError(text, pos)
     return match, match.end()
 
 class Itpl:
     """Class representing a string with interpolation abilities.
     
     Upon creation, an instance works out what parts of the format
     string are literal and what parts need to be evaluated.  The
     evaluation and substitution happens in the namespace of the
     caller when str(instance) is called."""
 
     def __init__(self, format,codec='utf_8',encoding_errors='backslashreplace'):
         """The single mandatory argument to this constructor is a format
         string.
 
         The format string is parsed according to the following rules:
 
         1.  A dollar sign and a name, possibly followed by any of: 
               - an open-paren, and anything up to the matching paren 
               - an open-bracket, and anything up to the matching bracket 
               - a period and a name 
             any number of times, is evaluated as a Python expression.
 
         2.  A dollar sign immediately followed by an open-brace, and
             anything up to the matching close-brace, is evaluated as
             a Python expression.
 
         3.  Outside of the expressions described in the above two rules,
             two dollar signs in a row give you one literal dollar sign.
 
         Optional arguments:
 
         - codec('utf_8'): a string containing the name of a valid Python
         codec.
 
         - encoding_errors('backslashreplace'): a string with a valid error handling
         policy.  See the codecs module documentation for details.
 
         These are used to encode the format string if a call to str() fails on
         the expanded result."""
 
         if not isinstance(format,basestring):
             raise TypeError, "needs string initializer"
         self.format = format
         self.codec = codec
         self.encoding_errors = encoding_errors
         
         namechars = "abcdefghijklmnopqrstuvwxyz" \
             "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_";
         chunks = []
         pos = 0
 
         while 1:
             dollar = string.find(format, "$", pos)
             if dollar < 0: break
             nextchar = format[dollar+1]
 
             if nextchar == "{":
                 chunks.append((0, format[pos:dollar]))
                 pos, level = dollar+2, 1
                 while level:
                     match, pos = matchorfail(format, pos)
                     tstart, tend = match.regs[3]
                     token = format[tstart:tend]
                     if token == "{": level = level+1
                     elif token == "}": level = level-1
                 chunks.append((1, format[dollar+2:pos-1]))
 
             elif nextchar in namechars:
                 chunks.append((0, format[pos:dollar]))
                 match, pos = matchorfail(format, dollar+1)
                 while pos < len(format):
                     if format[pos] == "." and \
                         pos+1 < len(format) and format[pos+1] in namechars:
                         match, pos = matchorfail(format, pos+1)
                     elif format[pos] in "([":
                         pos, level = pos+1, 1
                         while level:
                             match, pos = matchorfail(format, pos)
                             tstart, tend = match.regs[3]
                             token = format[tstart:tend]
                             if token[0] in "([": level = level+1
                             elif token[0] in ")]": level = level-1
                     else: break
                 chunks.append((1, format[dollar+1:pos]))
 
             else:
                 chunks.append((0, format[pos:dollar+1]))
                 pos = dollar + 1 + (nextchar == "$")
 
         if pos < len(format): chunks.append((0, format[pos:]))
         self.chunks = chunks
 
     def __repr__(self):
         return "<Itpl %s >" % repr(self.format)
 
     def _str(self,glob,loc):
         """Evaluate to a string in the given globals/locals.
 
         The final output is built by calling str(), but if this fails, the
         result is encoded with the instance's codec and error handling policy,
         via a call to out.encode(self.codec,self.encoding_errors)"""
         result = []
         app = result.append
         for live, chunk in self.chunks:
             if live: app(str(eval(chunk,glob,loc)))
             else: app(chunk)
         out = ''.join(result)
         try:
             return str(out)
         except UnicodeError:
             return out.encode(self.codec,self.encoding_errors)
 
     def __str__(self):
         """Evaluate and substitute the appropriate parts of the string."""
 
         # We need to skip enough frames to get to the actual caller outside of
         # Itpl.
         frame = sys._getframe(1)
         while frame.f_globals["__name__"] == __name__: frame = frame.f_back
         loc, glob = frame.f_locals, frame.f_globals
 
         return self._str(glob,loc)
     
 class ItplNS(Itpl):
     """Class representing a string with interpolation abilities.
 
     This inherits from Itpl, but at creation time a namespace is provided
     where the evaluation will occur.  The interpolation becomes a bit more
     efficient, as no traceback needs to be extracte.  It also allows the
     caller to supply a different namespace for the interpolation to occur than
     its own."""
     
     def __init__(self, format,globals,locals=None,
                  codec='utf_8',encoding_errors='backslashreplace'):
         """ItplNS(format,globals[,locals]) -> interpolating string instance.
 
         This constructor, besides a format string, takes a globals dictionary
         and optionally a locals (which defaults to globals if not provided).
 
         For further details, see the Itpl constructor."""
 
         if locals is None:
             locals = globals
         self.globals = globals
         self.locals = locals
         Itpl.__init__(self,format,codec,encoding_errors)
         
     def __str__(self):
         """Evaluate and substitute the appropriate parts of the string."""
         return self._str(self.globals,self.locals)
 
     def __repr__(self):
         return "<ItplNS %s >" % repr(self.format)
 
 # utilities for fast printing
 def itpl(text): return str(Itpl(text))
 def printpl(text): print itpl(text)
 # versions with namespace
 def itplns(text,globals,locals=None): return str(ItplNS(text,globals,locals))
 def printplns(text,globals,locals=None): print itplns(text,globals,locals)
 
 class ItplFile:
     """A file object that filters each write() through an interpolator."""
     def __init__(self, file): self.file = file
     def __repr__(self): return "<interpolated " + repr(self.file) + ">"
     def __getattr__(self, attr): return getattr(self.file, attr)
     def write(self, text): self.file.write(str(Itpl(text)))
 
 def filter(file=sys.stdout):
     """Return an ItplFile that filters writes to the given file object.
     
     'file = filter(file)' replaces 'file' with a filtered object that
     has a write() method.  When called with no argument, this creates
     a filter to sys.stdout."""
     return ItplFile(file)
 
 def unfilter(ifile=None):
     """Return the original file that corresponds to the given ItplFile.
     
     'file = unfilter(file)' undoes the effect of 'file = filter(file)'.
     'sys.stdout = unfilter()' undoes the effect of 'sys.stdout = filter()'."""
     return ifile and ifile.file or sys.stdout.file